canonical: https://jentic.com/apis/linear.app/linear

# Linear App Linear API

Query and mutate issues, projects, cycles, teams, and workflows through Linear's GraphQL endpoint. Supports Bearer token authentication with personal API keys and OAuth 2.0 for third-party integrations. The single /graphql endpoint provides typed access to all Linear data including issues, comments, labels, milestones, roadmaps, and team configurations.

## For AI agents

Create and track issues, manage project cycles, assign work across teams, and query workflow states through Linear's GraphQL API. Provides typed access to the full Linear data model via a single endpoint.

## Scope

Does not handle source control, CI/CD pipelines, or document collaboration - use for issue tracking, sprint planning, and project workflow management only.

## Capabilities

- Create issues with title, description, assignee, labels, priority, and cycle assignment in a single GraphQL mutation
- Query issues across teams with filters on status, priority, assignee, label, and date ranges
- Move issues through workflow states and update priority, assignee, and project linkage
- Plan and monitor cycles (sprints) with scope tracking and automatic issue rollover
- Configure team workflows, label taxonomies, and project templates
- Link issues to GitHub pull requests and branches for development tracking
- Subscribe to webhook events for real-time issue state changes and comment notifications

## Use cases

### AI Agent Issue Management

AI agents use the Linear API through Jentic to automate issue lifecycle management - creating issues from bug reports, triaging by priority, assigning to team members, and tracking through workflow states. An agent searches Jentic for 'create a linear issue', receives the GraphQL mutation schema, and executes with title, team, priority, and label parameters. The entire flow from incident detection to issue creation and assignment completes in seconds.

Example prompt: Create a P1 issue in the Platform team titled 'API latency spike detected' with label 'incident', assign it to the on-call engineer, and add it to the current cycle

### Sprint Cycle Tracking and Planning

Query active cycles, monitor completion metrics, and plan upcoming cycles by moving backlog issues into scope. Linear's API exposes cycle start/end dates, scope (total issues), completed count, and progress percentage. Agents automate standup reporting by summarizing what moved to Done, what's in progress, and what's blocked across a team's active cycle.

Example prompt: Query the active cycle for the Backend team, calculate the percentage of issues completed vs total scope, list any issues marked as blocked, and generate a cycle health summary

### Cross-Team Issue Search and Reporting

Execute filtered queries across multiple teams to generate reports on workload distribution, priority balance, and aging issues. The GraphQL API supports filtering by team, state, label, priority, assignee, and created/updated dates. Agents build leadership dashboards by aggregating issue counts and identifying teams with high P1 backlogs.

Example prompt: Search for all P1 and P2 issues across all teams that have been in 'In Progress' for more than 5 days and generate a summary grouped by team

### Development Workflow Integration

Link Linear issues to GitHub pull requests and branches, automatically updating issue status when PRs are merged. The API provides bidirectional sync between code changes and project tracking. Teams use this to maintain traceability from feature requests through implementation to deployment without manual status updates.

Example prompt: Find all issues in the Frontend team linked to merged PRs in the last week that are still in 'In Review' state, and transition them to 'Done'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /graphql | Execute GraphQL queries and mutations for all Linear operations |

## Key resources

- **Issues** — Create, search, update, and track issues with priority, labels, assignees, and workflow states
- **Cycles** — Plan sprints, track progress, and manage issue scope within time-boxed cycles
- **Projects** — Organize work into projects with milestones, status, and linked issues
- **Teams** — Configure team settings, workflow states, labels, and member assignments
- **Comments** — Add, read, and manage comments and reactions on issues
- **Workflows** — Define and manage team-specific workflow states and transitions

## Why Jentic

- **Setup:** Wiring the Linear API by hand means setting its bearer token or OAuth access, then writing raw GraphQL queries and mutations against the single /graphql endpoint at api.linear.app yourself. Through Jentic you install once, import the Linear API from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Linear exposes one /graphql endpoint where the operation is the GraphQL query or mutation in the request body, so scope the agent to the operations it needs, such as creating an issue or reading sprint progress. You leave out mutations you do not want it to run, so it only calls the ones you allow.
- **Credential handling:** Your Linear API key or OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Linear issue' or 'check sprint progress', and Jentic returns the matching GraphQL operation with its typed field schema so the agent runs the right query without writing raw GraphQL or browsing the reference docs.

## Related APIs

- **The Jira Cloud platform REST API** — Enterprise project tracking with customizable workflows, fields, and permissions
- **GitHub v3 REST API** — Source control platform whose PRs and branches link to Linear issues
- **GitLab REST API** — DevOps platform with merge requests that can sync with Linear issues

## FAQ

### What authentication does the Linear API use?

The Linear API uses Bearer token authentication. You can use personal API keys generated from Linear settings, or OAuth 2.0 for third-party app integrations with scoped access. Through Jentic, tokens are stored encrypted in your Jentic One instance - agents receive authenticated access without the raw API key entering their context.

### How do I create an issue through the Linear API via Jentic?

Search Jentic for 'create a linear issue', load the GraphQL mutation schema for the issueCreate mutation via POST /graphql, and execute with title, teamId, priority, and optional fields like labelIds and assigneeId. Jentic handles Bearer token injection automatically. The response returns the issue identifier and URL.

### What are the rate limits for the Linear API?

Linear applies rate limits of 1500 requests per hour for personal API keys and higher limits for OAuth apps. The API returns HTTP 429 with a Retry-After header when limits are exceeded. GraphQL complexity limits also apply - deeply nested queries count more against the limit. Typical automation use cases stay well within these bounds.

### Can I query issues across multiple teams with the Linear API?

Yes. The issues query in the GraphQL API accepts filter parameters for team, state, priority, label, assignee, and date ranges. You can query without a team filter to get issues across all teams you have access to. Results support cursor-based pagination for large result sets.

### How does Linear's GraphQL API differ from REST?

Linear uses a single POST /graphql endpoint for all operations instead of separate REST endpoints per resource. You write queries to fetch exactly the fields you need and mutations to create or update data. This means fewer HTTP round-trips but requires constructing GraphQL query strings. Through Jentic, the query structure is templated so agents can execute without writing raw GraphQL.

### Is the Linear API free to use?

API access is included with all Linear plans. Linear offers a free plan for small teams with full API access. Paid plans (Standard, Plus, Enterprise) increase storage and feature access. There is no separate API usage fee beyond the plan subscription.

### Can I limit what my agent is allowed to do with the Linear API?

Yes. Because you run your own self-hosted Jentic One instance, your rules decide which Linear operations and credentials the agent can use. The Linear API is a single /graphql endpoint where each operation is the query or mutation in the request body, so you scope the agent to only the operations it needs, such as creating an issue or reading sprint progress, and leave out any mutations you do not want it to run. Your Linear API key stays with your instance and is injected at execution time, so the agent only calls the operations you allow.