Linear API

The Linear API lets developers build custom integrations, automate workflows in code, and pull data into external systems. If Linear's built-in automation can't do exactly what your team needs, the API fills the gap. Everything visible in the Linear interface is accessible through the API.

What the Linear API Can Do

Use Case	Example
Create issues programmatically	An internal alert system auto-creates a Linear issue when a server goes down
Update issue properties from external tools	A CI/CD pipeline changes issue status to "Done" after a successful deployment
Read issue data for dashboards	Pull all open bugs into a custom Slack dashboard each morning
Sync with external databases	Mirror Linear issues into a Notion database or Google Sheet
Build internal tools	A support team portal that creates Linear issues from a form submission

API Type: GraphQL

Linear uses a GraphQL API. GraphQL is a query language for APIs that lets you request exactly the data you need in one call — no more, no less. Unlike traditional REST APIs that return fixed data structures, GraphQL gives you full control over what comes back.

REST API vs GraphQL: Side-by-Side

REST API (Traditional)
───────────────────────
GET /issues/ENG-88
Returns ALL fields:
  id, title, description, status, priority,
  assignee, labels, comments, createdAt,
  updatedAt, projectId, cycleId, estimate...
  (Even the fields you don't need)

GraphQL (Linear)
────────────────
query {
  issue(id: "ENG-88") {
    title
    status { name }
    assignee { name }
  }
}
Returns ONLY:
  title, status name, assignee name
  (Exactly what you asked for)

Get Your API Key

Go to Settings > API > Personal API Keys and click Create Key. Give the key a descriptive label so you remember what it's used for (e.g., "Sentry Integration" or "Custom Dashboard Script").

Your API key is a long string of characters. Store it securely — treat it like a password. Anyone with your API key can read and write data in your Linear workspace on your behalf.

Make Your First API Call

Linear's API endpoint is:

https://api.linear.app/graphql

Every request sends a GraphQL query in the request body and includes your API key in the Authorization header.

Example: Fetch Your Assigned Issues

Request Headers:
  Content-Type: application/json
  Authorization: Bearer YOUR_API_KEY

Request Body:
  {
    "query": "{ viewer { assignedIssues { nodes { id title status { name } } } } }"
  }

Response:
  {
    "data": {
      "viewer": {
        "assignedIssues": {
          "nodes": [
            { "id": "ENG-88", "title": "Add dark mode", "status": { "name": "In Progress" } },
            { "id": "ENG-91", "title": "Fix cart bug", "status": { "name": "Todo" } }
          ]
        }
      }
    }
  }

Common API Operations

Operation	GraphQL Type	Example
Read data	Query	Get all issues in a team
Create data	Mutation	Create a new issue with title and priority
Update data	Mutation	Change an issue's status or assignee
Delete data	Mutation	Archive or cancel an issue
Listen for changes	Webhook	Receive a notification when any issue is updated

Webhooks

Webhooks let Linear send data to your system the moment something changes — instead of your system asking Linear repeatedly. Set up a webhook to receive instant updates when issues are created, updated, or closed.

WITHOUT WEBHOOKS (Polling):

Your System: "Linear, are there any new issues?" → Every 60 seconds
Linear: "No." (59 times out of 60)
Your System: "Linear, any new issues?"
Linear: "Yes! One new issue." ← Finally, after 60 seconds of waiting

WITH WEBHOOKS (Push):

New issue created in Linear
         │
         ▼
Linear instantly sends data → Your System receives it in under 1 second

Set Up a Webhook

Go to Settings > API > Webhooks
Click New Webhook
Enter the URL where your server receives POST requests
Choose which events trigger the webhook (issue created, status changed, etc.)
Click Save and test the webhook using the Test button

Linear SDK

Anthropic Linear provides an official JavaScript/TypeScript SDK that wraps the GraphQL API in clean, typed functions. Install it with:

npm install @linear/sdk

The SDK eliminates the need to write raw GraphQL queries. Instead, you call JavaScript methods that handle the query structure automatically and return typed data objects. This makes building integrations faster and reduces errors from malformed queries.

SDK Example: Create an Issue

import { LinearClient } from "@linear/sdk";

const client = new LinearClient({ apiKey: "YOUR_API_KEY" });

// Create a new issue
const issue = await client.createIssue({
  teamId: "TEAM_ID",
  title: "Fix null error in cart",
  priority: 2,     // 1=Urgent, 2=High, 3=Medium, 4=Low
  labelIds: ["LABEL_BUG_ID"],
});

console.log(issue.issue?.id);
// → ENG-199

Previous lessons

Back to courses

Next lessons