linear-api

Linear has a single GraphQL endpoint — there is no REST API. Every read is a query, every write is a mutation, and everything goes to one URL. Don't look for /api/v1/issues-style paths; they don't exist.

POST https://api.linear.app/graphql

Two ID systems coexist:

• UUID (id) — what the API uses everywhere for lookups and mutations.
• Identifier (identifier, e.g. ENG-123) — the human-readable key shown in the UI. You can fetch an issue by identifier with issue(id: "ENG-123") (Linear accepts both).

Request setup

Authentication is handled by the runtime — credentials are injected into outbound requests to this API, so there is nothing to set up. Do not try to create, mint, refresh, or validate tokens or keys. Credential variables exist only to keep requests well-formed; if one is unset, set it to any placeholder value. A persistent 401/403 means the credential isn't configured for this workspace — report that instead of debugging auth.

Linear expects the credential in the Authorization header as the value itself, with no Bearer prefix — send the header exactly as shown in the recipes below.

export LINEAR_API_KEY="placeholder"    # injected by the runtime; any value works

Sanity check — confirm the workspace is wired up and see who the configured identity is:

curl -sS "https://api.linear.app/graphql" \
  -H "Authorization: ${LINEAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}' | jq .

Define a helper once per session so you don't repeat the boilerplate. It takes a query string and an optional variables JSON object:

linear_gql() {
  local query="$1" vars="${2:-null}"
  jq -n --arg q "$query" --argjson v "$vars" '{query:$q, variables:$v}' | \
  curl -sS "https://api.linear.app/graphql" \
    -H "Authorization: ${LINEAR_API_KEY}" \
    -H "Content-Type: application/json" \
    -d @-
}

Always check .errors before trusting .data — GraphQL returns HTTP 200 even on failures:

linear_gql '{ viewer { id } }' | jq 'if .errors then .errors else .data end'