Working with the GraphQL API
Linear's public API is built using GraphQL. It's the same API we use internally for developing our applications.
If you're new to GraphQL, Apollo has resources for beginners. The official documentation is another good starting point.
Endpoint
Linear's GraphQL endpoint is:
It supports introspection so you can query the whole schema.
Authentication
Right now we support personal API keys and OAuth2 authentication.
OAuth2
If you're building an application for others to use, we recommend you use OAuth2 authentication. Once you completed the authentication flow and acquired an access token, you can pass it with header: Authorization: Bearer <ACCESS_TOKEN>
Personal API keys
For personal scripts API keys are the easiest way to access the API. They can be created in the API settings. To authenticate your requests, you need to pass the newly created key with header: Authorization: <API_KEY>
Linear SDK
The Linear SDK exposes the Linear GraphQL schema, and makes it easy to access models, or perform mutations. We recommend using it to interact with the GraphQL API. It is written in TypeScript, allowing all operations to be strongly typed.
Getting Started
We recommend using a GraphQL client to introspect and explore the schema if you are not using the Linear Client (SDK).
Our GraphQL API is explorable and queryable via Apollo Studio, no download or log in required. Click the Schema tab to browse the schema, and click the Explorer tab to run queries.
Once you have your client installed, you can start making queries (read) and mutations (write) to the API.
Queries & Mutations
To get information about the authenticated user, you can use the viewer
query:
As issues (and most other objects) are team based, you first need to get the ID of the team you want to interact with:
Once you have found the correct team, you can get the issues for that team. Lets make a request with also some other issue metadata:
We can also get an issue by id:
To get the full list of available queries and mutations, introspect the API schema using your favorite GraphQL client.
Protip: Locate the IDs of teams, issues and other entities directly within Linear itself from the command menu: ⌘/CTRL+K
"Copy model UUID". This will show results based on the page you're currently viewing within Linear.
Creating & Editing Issues
To create a new issue, we'll need to create a mutation:
This mutation will create a new issue and return its id
and title
if the call was successful (success: true
).
If an issue is created without a specified stateId
(the status field for the issue), the issue will be assigned to the team's first state in the Backlog workflow state category. If the "Triage" feature is turned on for the team, then the issue will be assigned to the Triage workflow state.
A common use case after creating an issue is updating the issue. To do this we can use the issueUpdate
mutation, using the input field to include whatever it is we want to change. The id
provided can be either be the uuid returned by the creation query, or the shorthand id like BLA-123
below.
Accessing images
Linear hosts images and other assets uploaded into Linear behind authentication. Only authenticated users can view their assets. This also applies to the API and all images will require authentication to be displayed outside Linear's application. Regular API authentication (OAuth or API keys) is accepted for displaying images. If you're displaying images outside Linear's applications, you should download and self-host them in your application's environment.
Fetching updates
If you're working on building an application which display Linear data and you want the information to update (near) realtime, you have few options. To prevent excessive usage of our API, we recommend that you be mindful about your implementation.
Lets say you're displaying a big number of issues in your application and want to update them:
Do's:
Register a programmatic webhook and get updates for all issues for the team. When you detect changes, update the issue information. You can also automatically register webhooks for OAuth applications.
If you have to poll recent changes, order results by returning recently updated issue first. See Pagination section above how to implement this
Filter issues in your GraphQL request instead of fetching all issues and filtering in code.
Dont's:
Poll updates for each issue in the application. There should never be a reason to do this and your application might get rate limited. See above tactics to implement this better
If you have any questions, visit #api channel on our customer Slack.
Other Examples
Queries
There are many ways to fetch issues. One common use case is to get all the issues assigned to a user.
First let's find our user's id:
Now we can use the assignedIssues
field on User:
We can do the same thing with workflowStates
which represent status fields for teams:
Archived resources
Archived resources are hidden by default from the paginated responses. They can be included by passing optional includeArchived: true
as a query parameter for pagination.
Support
If you run into problems or have questions or suggestions, you can join our customer Slack or send us a note (hello@linear.app). Both options are available through the user menu in the Linear application.
Last updated