Linear API: Project Management Integration English for Developers

Linear is a project management tool popular among software teams for its speed and keyboard-first design. Its API lets you build integrations, automate workflows, and embed issue tracking into your own products. The API is GraphQL-based, which means the vocabulary includes both Linear-specific concepts and general GraphQL terminology. This post will help ESL developers read the Linear API documentation, write integration code, and discuss project management tooling in English.

Core Data Model

Issue — the fundamental unit of work in Linear; an issue has a title, description, status, assignee, priority, and estimate, and it belongs to a Team and optionally a Project or Cycle.

“Our GitHub Action creates a Linear Issue automatically whenever a Sentry error occurs more than ten times in an hour, linking the error ID in the issue description.”

Team — a group of people in Linear who share a backlog, workflow states, and label definitions; every issue belongs to exactly one Team.

“We scope our webhook subscription to a single Team so the integration only receives events relevant to the backend engineers and does not process front-end issues.”

Project — a container for a collection of issues that share a goal and a timeline; projects sit above individual issues and can span multiple Teams.

“We created a Project called ‘Q3 API Refactor’ to group all the related issues so stakeholders can track overall progress on a single page.”

Cycle — Linear’s term for a time-boxed iteration (equivalent to a sprint); issues are assigned to a Cycle to indicate they are planned for completion within that time period.

“Our planning bot queries the current Cycle and posts a summary of its issues to Slack every Monday morning so the team starts the week with full context.”

Roadmap — a higher-level view that groups Projects over time; the Linear API exposes Roadmap data so you can surface strategic plans in external dashboards or executive reports.

“We pull Roadmap data from the Linear API every night to update the investor-facing dashboard with the latest delivery timelines.”

GraphQL Schema and Queries

GraphQL schema — the typed definition of every object, field, query, and mutation available in the Linear API; Linear publishes an introspectable schema you can explore with tools like GraphQL Playground.

“We ran an introspection query against the Linear GraphQL schema to discover the exact fields available on the Issue type before writing our integration.”

mutation — a GraphQL operation that changes data; Linear exposes mutations for creating issues, updating statuses, assigning users, and more.

“The integration calls the issueCreate mutation with the title and team ID derived from the Sentry alert payload to open a new issue in Linear.”

connection — the GraphQL pagination pattern Linear uses for list fields; a connection contains a list of edges, each holding a node (the actual object) and a cursor for fetching the next page.

“We iterate through the issues connection using the after cursor to fetch all 500 issues in the backlog, 50 at a time.”

Workflow and Triage

triage — the process of reviewing newly created issues and assigning them a priority, status, and owner; Linear has a dedicated triage state and inbox for this purpose.

“We set up an automation rule in Linear that moves every issue submitted through the public bug form into the triage state so the on-call engineer reviews it before it enters the active backlog.”

estimate — a numerical value (often in story points or time units) attached to an issue to indicate the expected effort required; accessible via the API for burndown and velocity calculations.

“Our reporting script reads the estimate field for every completed issue in the current Cycle and calculates the team’s actual velocity against the planned total.”

Webhooks and OAuth

webhook event — a JSON payload that Linear sends to a configured URL whenever a specified action occurs, such as an issue being created, updated, or deleted.

“We configured a webhook event subscription for issueUpdated so our deployment pipeline automatically closes related issues when a release tag is pushed to GitHub.”

OAuth — the authorisation flow Linear uses to grant third-party applications access to a user’s or organisation’s data on their behalf, without sharing credentials.

“We implemented the OAuth flow so users can connect their Linear workspace to our tool in three clicks, and we store the access token securely to make API calls on their behalf.”

Practice

Write a GraphQL query that fetches the title, status, and assignee name for all open issues in a specific Linear Team. Then write a mutation that updates one of those issues to a different status. In English, explain to a colleague what triage means in a software team context and why having a dedicated triage state is different from simply having an unassigned backlog.