Linear Python SDK

Warnings

• breaking There is no official Python SDK for Linear. linear-py, linear-api, and linear-python are all community packages with no official support. Linear's official SDK is TypeScript only.
  Fix: Use raw GraphQL over HTTP for production. Use linear-api for prototyping if you want an ORM-style wrapper.
• breaking GraphQL queries return 200 OK even on errors. The 'errors' array in the response must be checked explicitly — HTTP status alone does not indicate success.
  Fix: Always check 'if errors in result' before accessing result['data'].
• breaking OAuth apps: starting October 1 2025 all newly created OAuth apps issue refresh tokens by default. Existing apps must migrate to refresh tokens by April 1 2026 or OAuth tokens will stop working.
  Fix: Implement refresh token flow before April 1 2026. See Linear OAuth developer documentation.
• breaking userPromoteAdmin, userDemoteAdmin, userPromoteMember, userDemoteMember mutations removed from GraphQL schema. Any code using these will get schema validation errors.
  Fix: Use the current user role management mutations in the schema.
• gotcha Linear API token format is 'lin_api_...' — do not use Bearer prefix. Correct header is Authorization: lin_api_... not Authorization: Bearer lin_api_...
  Fix: headers = {'Authorization': 'lin_api_YOUR_KEY'} — no Bearer prefix.
• gotcha Issue search by identifier (e.g. ENG-123) requires filtering by number first then matching identifier. Direct filter on identifier string is not supported.
  Fix: Filter by number: {'number': {'eq': 123}} then match exact identifier in results.
• gotcha issueAddLabel mutation does not exist. Common LLM-generated code attempts to call it and gets a 400 error.
  Fix: Use issueUpdate with labelIds array instead.
• deprecated linear-python (PyPI) is an older abandoned wrapper. Do not confuse with linear-api or linear-py.
  Fix: Use linear-api for community wrapper or raw GraphQL.

Install

• pip install linear-api Python (best community wrapper — Pydantic models, auto-pagination)
• pip install linear-py Python (minimal community wrapper — limited features)

Imports

• LinearClient

  from linear_api import LinearClient

  linear-api installs as linear_api, not linear. No official Python package named linear exists.
• Raw GraphQL (recommended)

  import urllib.request  # raw GraphQL over HTTP

  For production use, raw GraphQL is more reliable than any community wrapper. linear-py has very limited feature coverage.

Quickstart

Raw GraphQL approach — recommended for production Python use with Linear API.

import json
import urllib.request

API_KEY = 'lin_api_YOUR_KEY'

def graphql_request(query, variables=None):
    data = json.dumps({'query': query, 'variables': variables or {}}).encode()
    req = urllib.request.Request(
        'https://api.linear.app/graphql',
        data=data,
        headers={
            'Authorization': API_KEY,
            'Content-Type': 'application/json'
        }
    )
    with urllib.request.urlopen(req) as resp:
        result = json.loads(resp.read())
    if 'errors' in result:
        raise Exception(result['errors'])
    return result['data']

# Get current user
me = graphql_request('{ viewer { id name email } }')
print(me)

# Get issues for a team
query = '''
query TeamIssues($teamId: String!) {
    team(id: $teamId) {
        issues { nodes { id identifier title state { name } } }
    }
}
'''
issues = graphql_request(query, {'teamId': 'YOUR_TEAM_ID'})