Linear AI Agents: API Guide, Apps and Governed Workflows
Understand Linear's native AI and GraphQL API, then design issue triage, planning intake, and delivery reporting on Major with durable app state and human approvals.

Linear AI agents read work, interpret context, and propose or execute changes through Linear's own features or its API. This guide covers Linear's native AI, eight useful API operations, and how Major adds governed apps, cross-system judgment, and approval workflows for engineering operations leaders.
What Linear is and who relies on it
Linear organizes product development around issues, team workflows, projects, and cycles. An issue can represent a bug, feature, follow-up task, or internal request. Teams own the workflow that moves that issue from intake toward completion, as described in Linear's conceptual model.
Engineering leads use those records to assign ownership and plan near-term work. Product managers group related issues into projects and milestones, then communicate progress toward an outcome. Triage owners review incoming requests before they enter a team's planned work.
The distinction matters for automation. A new report is not automatically a commitment, and a completed issue is not automatically proof that a customer problem has disappeared. An agent needs context to interpret both.
Major is the enterprise platform where agents build the software they run on. For Linear operations, that software can be a deterministic intake app holding source references, proposed changes, reviewer assignments, and execution history. The agent judges ambiguous requests; the app preserves the record and runs repeatable validation.
Linear's built-in AI and where Major adds value
Linear Agent can answer questions across workspace information and code, summarize ongoing work, and create or update issues, projects, milestones, and initiatives. It operates within the invoking user's existing permissions. It also has MCP connectors for outside context, so cross-tool access is not exclusive to Major.
Linear's skills save useful instructions for reuse. Loops run agent workflows on schedules or supported Linear, Slack, and GitHub events. When enabled, coding sessions can handle well-scoped implementation work. These are substantial native capabilities, particularly when the operator already works inside Linear.
Triage Intelligence suggests issue properties using historical patterns and issue content. It detects possible duplicates and relationships, and administrators can configure property suggestions to appear, remain hidden, or apply automatically.
Major adds a different execution model: agents build durable software for the repeatable parts of the process. An intake app can retain a cross-system case history, enforce field-specific approvals, and reconcile unfinished actions after an interruption. The agent still makes judgment calls about severity, ownership, and evidence. Use this model when the process needs a shared control surface and explicit business state beyond an individual interaction.
How Linear connects to Major
Major has a native Linear connector. IT sets it up once, with centrally stored, scoped credentials in the connector vault rather than keys copied into code or prompts. The connector catalog also carries a legacy provider identifier, but the verified connection mode for this hub is native, not custom API setup.
Major orchestrates Linear; it never replaces it. Linear remains the system of record for engineering issues and their workflow state. The Major app holds operational state: source-to-issue mappings, proposals, approvals, retries, and evidence supporting each action.
Build the process as four cooperating pieces:
- Connector: expose only the Linear teams and operations the process needs, plus approved Slack, GitHub, or Notion context.
- App: hold managed database tables, review screens, validation logic, and execution receipts.
- Agent: classify unclear reports, compare conflicting evidence, and draft a reasoned recommendation.
- Workflow: trigger runs, sequence checks, request approvals, and retry eligible failures.
SSO, RBAC, and audit logs cover the apps, agents, and workflows. Start with read access and a review-only output before permitting writes to consequential fields.
Linear API guide: eight useful operations
Linear is GraphQL-first. The operations below all use POST /graphql at the base URL https://api.linear.app. They are eight queries or mutations, not eight REST endpoints. Their shared official reference documents the operation names and request examples.
Authentication, delivery, and testing
Authentication supports personal API keys in the Authorization header without the Bearer prefix, and OAuth access tokens with that prefix. OAuth scopes include read, write, issues:create, and comments:create. Notably, issues:create allows issue creation and updates; comments:create allows creating, but not editing, issue comments. Request the narrowest permissions that support the intended process.
For a separately implemented Linear app actor, actor=app attributes work to the application and requires admin approval for installation. app:mentionable enables mentions; app:assignable enables delegation while a human remains the assignee. App actors cannot request admin scope. This developer option does not mean every native connector installation automatically appears as a mentionable Linear agent.
Pagination uses first and after, or last and before. Continue with the returned endCursor while hasNextPage is true. The default is 50 records. Specify smaller pages for nested queries.
Standard rate limits are 2,500 requests per hour per API-key user and 5,000 per OAuth user or app user. Standard hourly complexity budgets are 3,000,000 and 2,000,000 points respectively, with a 10,000-point single-query maximum. Plan multipliers and dynamic allowances can change effective quotas.
Monitor X-RateLimit-Requests-Limit, X-RateLimit-Requests-Remaining, and X-RateLimit-Requests-Reset, plus the corresponding complexity headers and X-Complexity. Operation-specific limits have additional endpoint headers. HTTP 429 responses include Retry-After in seconds; inspect the GraphQL error code as well.
Webhooks cover created, updated, and removed issues, comments, projects, cycles, and other documented resources. Verify the raw body's HMAC-SHA256 against Linear-Signature and check webhookTimestamp freshness. Linear recommends a one-minute freshness window. Deduplicate Linear-Delivery before processing.
Return HTTP 200 within five seconds after verification and durable acceptance. Failed deliveries receive up to three retries, after one minute, one hour, and six hours. Workspace admins or appropriately authorized user-actor applications manage webhook creation; do not give the runtime agent administrative access for convenience.
No dedicated sandbox mode is documented in the developer guides reviewed here. Test in an isolated workspace or team with synthetic issues and an allowlisted write scope. Linear's agent guide says developing agents is free and installed agents do not count as billable users. That is not a promise of a separate sandbox environment.
Read the acting identity: viewer
POST /graphql, viewer query returns the authenticated identity. Establish whose permissions and attribution the integration actually uses.
- App: display the connected identity beside execution records.
- Agent: recognize when available context belongs to a different installation than expected.
- Workflow: validate identity during setup and stop a run if its stored installation mapping no longer matches.
Discover permitted teams: teams
POST /graphql, teams query lists accessible teams and their IDs. IDs are safer routing inputs than a team name copied from prose.
- App: populate the approved destination-team selector.
- Agent: recommend the most suitable team from that permitted set.
- Workflow: refresh the allowlist and reject a destination that is no longer accessible.
Read a team's issue context: team
POST /graphql, team query can retrieve a team's issues with titles, descriptions, assignees, and timestamps. Request only fields needed for the task.
- App: maintain a bounded issue index and source links.
- Agent: compare a new report with existing work for likely duplication.
- Workflow: populate the initial index, then reconcile changes using paginated reads and event-driven updates.
Re-read one issue: issue
POST /graphql, issue query retrieves an issue using its UUID or shorthand identifier. It is the final context check before an approved change.
- App: show current values beside the proposed diff.
- Agent: reconsider a recommendation when another person has added important information.
- Workflow: re-read before writing and send stale proposals back to review instead of overwriting newer work.
Create approved work: issueCreate
POST /graphql, issueCreate mutation creates an issue from inputs including title, description, and team ID. Inspect both the success field and returned issue ID.
- App: retain the external request ID and resulting Linear issue ID.
- Agent: draft a clear problem statement and acceptance criteria from fragmented reports.
- Workflow: create once after approval, then persist the mapping before attempting downstream notifications.
Apply a reviewed change: issueUpdate
POST /graphql, issueUpdate mutation changes an existing issue, including its title or workflow-state ID. Limit the write to reviewed fields.
- App: store before-and-after values with the approval record.
- Agent: propose a better description or status based on evidence.
- Workflow: apply the approved diff, verify the result, and record any partial failure rather than claiming completion.
Resolve status IDs: workflowStates
POST /graphql, workflowStates query exposes workflow status records. A status label should not be treated as a universal value across teams.
- App: maintain permitted status mappings for each destination.
- Agent: explain which permitted status fits the reported progress.
- Workflow: validate the chosen status ID before an update and flag configuration changes for an operator.
Resolve people: users
POST /graphql, users query retrieves user records including names and IDs. Use IDs to avoid confusing people with similar names.
- App: present a validated owner directory in the review screen.
- Agent: recommend an owner from documented responsibility context, without inventing a person.
- Workflow: resolve and validate the selected owner before executing an authorized assignment.
Linear automation use cases on Major
These are proposed multi-tool designs, not claims about existing deployments. Each uses the native Linear connector, a managed app, an agent judgment step, and a workflow with a defined write policy.
Slack intake to reviewed Linear issues
- App: hold source messages, duplicate candidates, and the review queue.
- Agent: distinguish a reproducible bug from a question and draft missing-information requests.
- Workflow: collect allowed Slack context, route the proposal for approval, then create or update the issue.
- Linear operations: teams, team, issue, issueCreate, and issueUpdate through POST /graphql.
GitHub delivery evidence to stakeholder updates
- App: map issues to repository evidence and retain previous updates.
- Agent: judge whether merged work actually resolves the issue or still needs validation.
- Workflow: gather authorized GitHub context on a schedule, request owner approval, and deliver a Slack digest. Do not equate a merge with customer resolution.
- Linear operations: team, issue, and workflowStates through POST /graphql; issueUpdate only when explicitly authorized.
Notion planning context to engineering intake
- App: track the planning-document version, proposed issues, and accepted mappings.
- Agent: identify actionable work, ambiguous requirements, and dependencies worth clarifying.
- Workflow: collect approved Notion context, route drafts to the project owner, then create accepted issues and publish a receipt.
- Linear operations: viewer, teams, users, and issueCreate through POST /graphql.
Keep the boundary clear: a workflow orchestrates collection and approval, an agent interprets the evidence, and the app keeps the durable record. Related patterns appear in the GitHub automation hub and Notion integration hub.
Architecture: build the Linear control surface on Major

Figure 1. The agent judges the request; the app holds state and the review queue.
Start with an event envelope containing the workspace, source record, and intended process. The workflow verifies the event and asks the app whether it has already been accepted. A duplicate can return its existing receipt without triggering another model call.
The connector supplies scoped Linear context, alongside authorized Slack evidence. The workflow passes a bounded evidence packet to the agent, which returns a recommendation, rationale, and proposed fields. The app validates IDs and allowed fields; it does not decide whether the report is serious.
Store separate records for the incoming request, proposal version, approval, and each attempted action. That separation lets an operator see whether a request is waiting for judgment, waiting for a person, or waiting for a failed API call to recover.
As the process stabilizes, the agent can build reusable app functions for normalization, mapping, and validation. Those functions run as deterministic software on subsequent requests. Reason once. Run forever. The model remains responsible for new ambiguity, not for reconstructing settled mechanics.
A worked example with numbers
For example, suppose an engineering operations team reviews 200 incoming reports each week. Manually opening the conversation, finding related Linear issues, drafting an intake summary, and recording the outcome takes six minutes per report. That is 200 × 6 = 1,200 minutes, or 20 hours weekly.
In an illustrative Major design, the workflow collects context and the app runs source matching and validation. The agent drafts the interpretation and proposed issue. Reviewers spend two minutes on each report, including rejecting weak drafts or asking for clarification. That is 200 × 2 = 400 minutes.
Allow another 80 minutes per week for exception handling, mapping maintenance, and checking failed actions. The modeled total becomes 480 minutes, or eight hours. The arithmetic difference is 720 minutes, or 12 hours, not a measured customer result or a guaranteed saving.
Pilot with a read-only review queue first. Measure accepted drafts, incorrect duplicate suggestions, review time, and reopened decisions. If reviewers repeatedly reconstruct the full context, improve the evidence packet before enabling writes. Fast drafts only help when the approval remains informed.
Governance and failure handling

Figure 2. Consequential changes require an approved, current proposal.
Define approvals by action and field, not just model confidence. A workflow may permit a routine enrichment under a written policy while requiring a named owner for priority changes, closure, team transfers, or customer commitments. The agent judges the evidence; authorization determines whether that judgment can be executed.
Never allow the agent alone to expand connector permissions, erase audit records, or treat untrusted issue text as instructions to bypass policy. Store who approved which proposal version. Re-read the issue before execution and require fresh approval when the underlying facts materially change.
GraphQL can return partial data and errors with HTTP 200. Validate required fields and mutation success before advancing. On rate limits, honor Retry-After, use bounded backoff with jitter, and keep retries in persisted workflow state.
Deduplicate webhook deliveries and prevent self-generated updates from endlessly retriggering the same process. If a create request times out after sending, reconcile its outcome before creating again. Preserve your own audit record: Linear documents that issue-property changes in the first three minutes can be treated as part of creation rather than separate activity-log changes.
Linear AI Apps, Agents and Workflow Automations
Every published Major use case that works with Linear, newest first. Each one names the Linear API objects involved and shows the app, agent and workflow split.
- Windsurf Alternatives: 8 Tools for Coding and Production: Replacing Windsurf? Compare coding assistants and app-building platforms by the work they run, how agents keep context, and what happens when code needs to become a governed production workflow.
- Linear Issue Triage Agent: Rules in Code, Judgment by Exception: Build a Linear issue triage agent where routing rules, state and logs live in code and the model only handles the issues those rules cannot settle.
- How to Use Notion's API for Custom Automation: Webhooks, Polling and Limits: Set up the Notion API for custom automation: create an integration, share pages, subscribe webhooks, poll as a safety net and design around rate limits.
- AI Agents for Project Management: 6 Cross-Tool Workflows That Actually: Every PM tool ships its own AI, but real programs span Jira, Asana, Linear, and Monday. Six cross-tool agent workflows, status rollups, risk detection, and exec digests, that keep the PM in control.
- Slack Alert Triage Agent: When Workflow Builder Is Not Enough: Slack Workflow Builder handles forms, schedules and approvals. A Slack alert triage agent groups on-call alerts, checks context and posts one summary to act on.
- Capturing AI Insights Into Notion: 5 Workflows That Use Notion as the Data Layer: Five workflows for capturing AI insights into Notion and acting on them in Linear, Slack or a CMS, each with its own trigger, state and audit log.
Frequently asked questions
Can a Linear AI agent automatically triage new issues?
Yes. Linear Triage Intelligence can suggest or automatically apply configured properties. On Major, an agent can classify unclear reports and recommend ownership or severity, while a workflow executes only actions allowed by policy. Require human approval for consequential changes rather than relying solely on a confidence score.
How should automations handle Linear API rate limits?
Read request, complexity, and operation-specific rate-limit headers. Honor Retry-After on HTTP 429, persist the pending action, and retry with bounded backoff. Use narrow queries, explicit pagination sizes, and webhooks instead of repeatedly polling individual issues.
What authentication methods work for Linear API-based agents?
Linear supports personal API keys and OAuth access tokens. OAuth supports user and app actors; actor=app attributes work to the application. Separately implemented Linear agents can request mention and delegation scopes. IT should approve scopes and keep credentials in Major's vault.
How does a Linear AI agent differ from Linear Agent and integrations?
Linear Agent is Linear's native assistant, with workspace actions, skills, Loops, and external connectors. An integration can add another agent or specialized behavior. On Major, the distinctive piece is an agent that builds and runs deterministic apps holding process state, review queues, and reusable execution logic.
When should models make decisions versus rules or humans?
Use deterministic app code for validation, mappings, and exact policy checks. Give the agent ambiguity that requires interpretation, such as conflicting severity evidence. Route consequential proposed actions to an authorized human when policy requires it, and preserve the evidence behind the recommendation.
Why is auditability important in custom Linear automations?
Auditability connects the source request, agent rationale, approval, attempted write, and verified outcome. That chain helps explain incorrect routing and distinguish an approved decision from an execution failure. Keep an independent process record instead of assuming Linear's issue activity captures every integration step.
Sources
These official Linear pages were read for this guide. The GraphQL getting-started page supplies the shared HTTP endpoint and all eight query or mutation examples. The operational guides document authentication, pagination, delivery verification, and quotas. Product documentation establishes what Linear's native AI already does, so the comparison does not depend on assumptions about missing features.
- Linear developer overview: Entry point for the API, SDK, and agent documentation.
- GraphQL getting started: Authentication headers, operations, partial errors, and issue activity behavior.
- OAuth 2.0 authentication: Actor identity, token renewal, and exact scope definitions.
- Pagination: Cursor arguments, continuation, and default page size.
- Rate limiting: Request and complexity budgets, plan variation, and retry headers.
- Webhooks: Supported resources, signatures, delivery identifiers, and retry timing.
- Developing agents: Installation permissions, mention scopes, delegation, and development access.
- Linear conceptual model: Issues, teams, cycles, projects, and their relationships.
- Linear Agent: Native actions, skills, Loops, coding sessions, and MCP connectors.
- Triage Intelligence: Property suggestions, automatic application, and duplicate detection.
Start building on Major
Build a Linear intake app with scoped context, agent judgment, and a review queue your team can inspect. Start with proposed changes, then enable approved writes as the process proves itself.
About the author
Ritvij Gautam is Head of Growth at Major.
Last reviewed November 20, 2026 by Ritvij Gautam.
Frequently asked questions
- Can a Linear AI agent automatically triage new issues?
- Yes. Linear Triage Intelligence can suggest or automatically apply configured properties. On Major, an agent can classify unclear reports and recommend ownership or severity, while a workflow executes only actions allowed by policy. Require human approval for consequential changes rather than relying solely on a confidence score.
- How should automations handle Linear API rate limits?
- Read request, complexity, and operation-specific rate-limit headers. Honor Retry-After on HTTP 429, persist the pending action, and retry with bounded backoff. Use narrow queries, explicit pagination sizes, and webhooks instead of repeatedly polling individual issues.
- What authentication methods work for Linear API-based agents?
- Linear supports personal API keys and OAuth access tokens. OAuth supports user and app actors; actor=app attributes work to the application. Separately implemented Linear agents can request mention and delegation scopes. IT should approve scopes and keep credentials in Major's vault.
- How does a Linear AI agent differ from Linear Agent and integrations?
- Linear Agent is Linear's native assistant, with workspace actions, skills, Loops, and external connectors. An integration can add another agent or specialized behavior. On Major, the distinctive piece is an agent that builds and runs deterministic apps holding process state, review queues, and reusable execution logic.
- When should models make decisions versus rules or humans?
- Use deterministic app code for validation, mappings, and exact policy checks. Give the agent ambiguity that requires interpretation, such as conflicting severity evidence. Route consequential proposed actions to an authorized human when policy requires it, and preserve the evidence behind the recommendation.
- Why is auditability important in custom Linear automations?
- Auditability connects the source request, agent rationale, approval, attempted write, and verified outcome. That chain helps explain incorrect routing and distinguish an approved decision from an execution failure. Keep an independent process record instead of assuming Linear's issue activity captures every integration step.