Linear

Linear has emerged as the developer-preferred issue tracker, and its API reflects that sensibility. The GraphQL API at api.linear.app/graphql provides full access to issues, projects, cycles, roadmaps, teams, and users. For agents managing development workflows — creating issues from alerts, updating status based on CI outcomes, querying sprint progress — Linear's API is excellent. The data model is opinionated but clean: issues belong to teams, teams have workflows (status sets), projects group issues across teams, and cycles represent time-boxed iterations. Webhook events cover issue lifecycle comprehensively. The API is fast — queries typically resolve in under 200ms. Integration with GitHub/GitLab for branch → issue linking is first-class. Main limitation: the GraphQL-only API means agents must construct queries rather than using simple REST endpoints.

Linear's entire API is GraphQL — no REST fallback. This is both a strength and constraint: agents get precise field selection, nested relationship traversal, and mutations in a single request, but must construct GraphQL queries rather than hitting simple endpoints. The schema is well-typed with clear object relationships. Filtering uses a consistent filter input type across resources. Pagination uses cursor-based relay-style connections. Mutations return the modified object, enabling create-then-read in a single call. Batch mutations for bulk issue updates exist. The IssueConnection type supports complex filtering by team, project, cycle, assignee, label, and custom fields. Rate limiting uses a complexity-based budget (10,000 units per hour) rather than simple request counting — efficient for agents that need complex queries.

GraphQL errors follow the standard errors[] array in the response body — HTTP status is typically 200 even on error (standard GraphQL behavior). Agents must check the errors field. Rate limiting uses complexity points: each field in a query costs points, with a budget of 10,000 points per hour. This rewards efficient queries and penalizes expensive ones — agents that request only needed fields stay well within limits. Deeply nested queries can exhaust the budget quickly. The extensions field in responses includes rateLimit with remaining points. Mutations return specific error types for validation failures (e.g., 'Issue not found', 'Invalid status'). API performance is consistently fast — Linear's infrastructure handles query resolution efficiently. Webhook delivery retries with exponential backoff.

Personal API keys (generated in Settings → API) provide full account access via Bearer header — the quickest path for internal agent integrations. OAuth 2.0 (authorization code with PKCE) is available for public integrations with scoped permissions (read, write, issues:create, etc.). Workspace API keys are available for workspace-wide integrations. OAuth scopes are granular enough to limit agent access to specific resource types. Webhook signing uses a configurable secret for payload verification. For agents, the personal API key is frictionless for single-workspace deployments. The OAuth flow is well-documented for multi-workspace agents. No API key expiry — keys persist until revoked. IP restriction is not available at the API level.

Developer documentation at developers.linear.app is clean, modern, and well-structured. The GraphQL schema explorer provides interactive query building. Webhook event documentation lists all event types with payload examples. OAuth guide is step-by-step. The SDK (linear-sdk for TypeScript) provides typed client generation from the schema — excellent for TypeScript-based agents. Python and other language clients are community-maintained. Linear's changelog and public roadmap keep developers informed. The company's developer-focused culture shows in documentation quality — guides explain design decisions, not just API mechanics. The main gap: GraphQL requires more upfront learning for agents accustomed to REST, and the documentation assumes some GraphQL familiarity.