Linear integration

Overview

Linear is issue tracking for software teams – issues, projects, cycles, teams, and labels. The Automize connector talks to Linear's GraphQL API at api.linear.app/graphql, with helpers for the common operations (create/update/list/comment) plus a raw Query action for ad-hoc GraphQL.

• Regions: Single global GraphQL endpoint at api.linear.app/graphql. EU residency available on Enterprise – same endpoint, data is routed by workspace setting.
• Plans: All plans expose the same API surface. Enterprise unlocks audit log read endpoints and SCIM (not in this connector).

Setting up the connection

Auth type: API Key.

1. In Linear → Settings → API → Personal API keys, click Create key. The key starts with lin_api_.
2. Paste it as the API key. Connector sends Authorization: <key> (no Bearer prefix – Linear is unusual here).
3. Personal API keys inherit the user's permissions. For workspace-wide automations, use an OAuth app instead (not covered by this connector – talk to Linear support).

Find your credentials at https://linear.app/settings/api.

Rate limits

1500 requests / hour per API key (rolling). Complexity-weighted: large GraphQL queries count more than the bare request count. Read X-RateLimit-Requests-Remaining + X-Complexity headers; the connector backs off on 429.

Data model

Linear's hierarchy:

    Organization (workspace)
      ├─ Teams
      │    ├─ WorkflowStates (Backlog, Todo, In Progress, Done, ...)
      │    ├─ Cycles         (time-bounded sprints)
      │    ├─ Labels         (team-scoped tags)
      │    └─ Issues
      │         ├─ Comments
      │         ├─ Assignee (User)
      │         ├─ Subscribers
      │         ├─ Project (cross-team scope-bounded)
      │         └─ Relations (blocks/blocked-by/duplicate)
      ├─ Projects     (cross-team, no fixed end)
      ├─ Users        (workspace members)
      └─ Customer feedback (Enterprise)

Important: WorkflowStates are PER-TEAM. "Todo" in team A has a
different stateId from "Todo" in team B. Always source stateIds
from the issue's owning team. Same goes for Labels and Cycles.

Identifiers:

    All IDs are UUIDs (e.g. "c4a8b1e2-..."). The human-readable
    identifier (TEAM-123) is a separate field – useful for display
    but not for API calls.

GraphQL specifics: filter inputs follow the {field: {operator: value}}
shape. Operators: eq, neq, in, nin, lt, lte, gt, gte, contains,
containsIgnoreCase, startsWith. Combine via and/or arrays at the
filter root.

Available operations

13 operations available. Click any row to jump to its detail.

Operations

Add Comment

Add a comment to an issue

Tips

• body is markdown – Linear renders the same flavour as in-app comments. @mentions need the user's id, not the handle: <@id_uuid>.

Create Issue

Create a new issue

Tips

• teamId is REQUIRED – get it from List Teams. State (Backlog/Todo/InProgress/Done) is set via stateId from the team's workflow.
• Pass labelIds=[...] to apply labels at create time; relations like cycleId, projectId, assigneeId attach the issue immediately.

Delete Issue

Archive (soft-delete) an issue

Tips

• Archives (soft-delete). Issues remain queryable with includeArchived=true; full hard-delete isn't exposed in the API.
• Pair with a Comment-add ahead of time to record the why – archives in Linear are usually 'this is no longer relevant', not 'this was wrong'.

Get Issue

Get a single issue by id or identifier (e.g. ENG-123)

Tips

• Single issue by id (UUID) or identifier (TEAM-123). Returns full body, comments count, attachments count, state, assignee, parent.
• Comments and history are NOT included by default – query them separately via the issue.comments connection.

List Cycles

List cycles (sprints) across teams

No input parameters.

Tips

• Cycles are team-scoped sprints. teamId filter is REQUIRED in practice – listing all cycles across all teams is rarely useful.
• isActive / isFuture / isPast flags help find 'the current sprint' deterministically.

List Issues

List issues, optionally filtered (e.g. by team, state, assignee)

Tips

• filter accepts the full Linear issue filter shape: {state: {name: {eq: 'Todo'}}, assignee: {email: {eq: '...'}}}.
• Pagination is cursor-based via first/after. Set first=50 (max 250).

List Labels

List issue labels

No input parameters.

Tips

• Labels are team-scoped. teamId filter trims to one team's label set.
• Use parent-child label hierarchies (parent field) to model categories like priority > urgent / high / medium.

List Projects

List projects

No input parameters.

Tips

• Cross-team scope-bounded efforts. State filter: planned, started, paused, completed, canceled, backlog.
• lead (Project Lead) is a User; targetDate is the planned completion.

List Teams

List workspace teams

No input parameters.

Tips

• Returns workspace teams with id, key (the TEAM- prefix), name, organisation, color.
• First call after onboarding – cache team.id → team.key for the duration of your flow.

List Users

List workspace users

No input parameters.

Tips

• Workspace members. Filter active: {eq: true} to exclude deactivated accounts.
• isMe field flags the authenticated user – equivalent to Viewer + a single user lookup.

Run GraphQL Query

Run an arbitrary GraphQL query/mutation against the Linear API

Tips

• Raw GraphQL – pass query + variables. Use this when an action doesn't exist for what you need (audit log slice, projects.archive, customViews).
• Linear's schema is introspectable – point any GraphQL IDE at api.linear.app/graphql with your API key to explore.

Update Issue

Update an existing issue

Tips

• Same input shape as create – pass only the fields you're changing. To move state, query the team's workflowStates and pick the next stateId.

Get Viewer (Me)

Get the authenticated user

No input parameters.

Tips

• Returns the authenticated user (name, email, organization). Useful for credential health checks – fast, deterministic, no side effects.

FAQ

Authorization header – Bearer or bare?

Bare. Linear's docs are explicit: 'Authorization: <api_key>' with NO 'Bearer ' prefix. Connector handles this correctly; pasting a bearer-style key here from another tool will 401.

Why are my workflow-state updates failing?

stateId must belong to the issue's team's workflow. Linear scopes states per team – Backlog in team A is a different stateId from Backlog in team B. Query the team's states first.

Cycles and projects – what's the difference?

Cycle = time-bounded sprint (week/fortnight). Project = scope-bounded feature (no fixed end). Issues can be on both. Filtering by cycle is the standard 'what's in this sprint' query.

GraphQL but I don't know GraphQL – what now?

Use the named actions (Create Issue, List Issues, Update Issue). They wrap the most common mutations/queries. Drop to linear-query only when a field doesn't exist on the wrapper.

Related connectors

• Jira
• Github
• Asana
• Clickup
• Monday