Copy page

Linear

Twin of the Linear GraphQL API.

Twin of the Linear GraphQL API. Everything is one endpoint, POST /graphql.

Covers	api.linear.app
Auth	Personal API keys, OAuth
Webhooks	No
Operations	29 root fields

Coverage

Those root fields cover the viewer and organization, users, teams, and issues with the filter grammar and create, update and archive, plus projects, milestones, roadmaps, cycles, workflow states, labels, comments, attachments and issue search, all over Relay pagination. The OAuth issuer sits on the same base at /oauth/authorize and /oauth/token.

Credentials

A well-formed personal API key authenticates by default, so your existing lin_api_… key needs no change. Set auth.mode to enforced to accept only the keys the world knows. See Credentials.

OAuth access tokens are different: only a token this sandbox issued works. Both kinds carry scopes, and a write without write or the matching *:create scope gets Linear’s FORBIDDEN error naming the scope.

Vendor specific details

• The API key goes in Authorization raw, with no Bearer prefix. Send a real key with the prefix and you get a 400 telling you to remove it, not a 401.
• HTTP status is not a reliable signal. A syntax error is 500, a validation error is 400, and a not-found or a bad argument is a 200 carrying errors with data: null. Read extensions.code.
• Anything that is not Content-Type: application/json is refused with Apollo’s CSRF block, a 400 with code BAD_REQUEST. That includes every GET.
• searchIssues is a case-insensitive substring match over title and description, in ordinary connection order. Real Linear ranks by relevance.
• issueArchive is a soft delete. Archived issues leave every connection unless you pass includeArchived: true, and there is no hard delete here.

Its own notes

Once a sandbox is running, this twin serves its own operating notes at {control_url}/veris/manual: the credentials it accepts, the API versions it serves, and the fault statuses you can arm against it. They are generated from the same source as its behaviour, so they cannot drift.