Skip to content
Skills Library
Management & product · Tool integration

linear-api

/linear-api

Read and manage Linear issues, projects, cycles, teams, comments, and labels. Use this whenever the user wants to list their issues, search issues, create or update an issue, move an issue between states, add a comment, check a project or cycle, look up a team, or ask "what's on my plate in Linear" — even if they don't say "API" or "GraphQL". Also use it for any linear.app URL or an issue identifier like "ENG-123". Always start from this skill when interacting with this service — its bundled scripts and recipes are the fastest path.

Licence
Apache-2.0
Last repository change
07.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 07.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/linear_issues.sh

What it does and when to use it

Read and manage Linear issues, projects, cycles, teams, comments, and labels. Use this whenever the user wants to list their issues, search issues, create or update an issue, move an issue between states, add a comment, check a project or cycle, look up a team, or ask "what's on my plate in Linear" — even if they don't say "API" or "GraphQL". Also use it for any linear.app URL or an issue identifier like "ENG-123". Always start from this skill when interacting with this service — its bundled scripts and recipes are the fastest path.

Triggers from the description

what— even if they donAPIGraphQLENG-123
Original author description

Read and manage Linear issues, projects, cycles, teams, comments, and labels. Use this whenever the user wants to list their issues, search issues, create or update an issue, move an issue between states, add a comment, check a project or cycle, look up a team, or ask "what's on my plate in Linear" — even if they don't say "API" or "GraphQL". Also use it for any linear.app URL or an issue identifier like "ENG-123". Always start from this skill when interacting with this service — its bundled scripts and recipes are the fastest path.

How it works

  1. Request setup
  2. Core operations
  3. Pagination
  4. Rate limits
  5. Error handling
  6. Going deeper
Original SKILL.md headings · 316 lines, 1,778 words
SKILL.md preview
---
name: linear-api
description: Read and manage Linear issues, projects, cycles, teams, comments, and labels. Use this whenever the user wants to list their issues, search issues, create or update an issue, move an issue between states, add a comment, check a project or cycle, look up a team, or ask "what's on my plate in Linear" — even if they don't say "API" or "GraphQL". Also use it for any linear.app URL or an issue identifier like "ENG-123". Always start from this skill when interacting with this service — its bundled scripts and recipes are the fastest path.
---

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.

```bash
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:

```bash
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:

```bash
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:

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

## Core operations

### 1. Who am I / what's assigned to me

```bash
linear_gql '{
  viewer {
    id name email
    assignedIssues(first: 25, orderBy: updatedAt, filter: {state: {type: {nin: ["completed","canceled"]}}}) {
      nodes { identifier title state { name type } priority team { key } updatedAt }
    }
  }
}' | jq '.errors // .data.viewer'
```

Priority: `0` = no priority, `1` = Urgent, `2` = High, `3` = Medium, `4` = Low.

### 2. Search issues

```bash
linear_gql 'query($q: String!) {
  searchIssues(term: $q, first: 25) {
    nodes { identifier title state { name } assignee { name } team { key } priority url }
  }
}' '{"q": "login crash"}' | jq '.data.searchIssues.nodes'
```

### 3. Get one issue (by identifier or UUID)

```bash
linear_gql 'query($id: String!) {
  issue(id: $id) {
    id identifier title description url priority estimate
    state { name type }
    assignee { name email }
    creator { name }
    team { id key name }
    project { id name }
    cycle { id number name }
    labels { nodes { name color } }
    comments(first: 50) { nodes { body user { name } createdAt } }
    children { nodes { identifier title state { name } } }
    parent { identifier title }
    createdAt updatedAt dueDate
  }
}' '{"id": "ENG-123"}' | jq '.data.issue'
```

### 4. List and filter issues (`scripts/linear_issues.sh`)

List issues through the bundled script (path is relative to this skill's directory): it builds an
`IssueFilter` from flags, pages through `pageInfo.endCursor`, checks `.errors` on every response,
and emits TSV or JSONL.

```bash
scripts/linear_issues.sh --team ENG --state-type started --assignee me --limit 100
```

- All filter flags are optional and combine (AND): `--team KEY`, `--state NAME`, `--state-type
  TYPE` (one of `backlog` `unstarted` `started` `completed` `canceled` `triage` `duplicate`),
  `--assignee EMAIL` (or `me` — resolves the viewer id first), `--label NAME`. Instance specifics come from
  `LINEAR_API_KEY` above.
- `--query TEXT` does a case-insensitive substring match over title and description; combined with
  other flags it's wrapped as `and: [ {…flags}, {or: [title, description]} ]`.
- `--limit N` caps total issues fetched (default 50, `0` = everything); `--page-size N` (max 100)
  sets the per-page size; `--json` emits one JSON object per issue instead of TSV with a header
  (`identifier`, `title`, `state`, `assignee`, `updatedAt`, `url`). Row counts go to stderr.
- Exit codes: `0` success, `1` request failed, GraphQL `.errors`, or bad arguments — the API's own
  message and `extensions.code` are on stderr.

If the script errors, read it — it's plain `curl` + `jq` — and debug against `references/api.md`.

For filter shapes the flags don't cover — comparators like `lte`/`gte`, `or` groups, nested
`some`/`every` — pass the `filter` object yourself with `linear_gql`:

```bash
linear_gql 'query($teamKey: String!) {
  issues(first: 50, orderBy: updatedAt, filter: {
    team: { key: { eq: $teamKey } }
    priority: { lte: 2, gte: 1 }
    state: { type: { nin: ["completed", "canceled"] } }
  }) { nodes { identifier title priority state { name } assignee { name } } }
}' '{"teamKey": "ENG"}' | jq '.data.issues.nodes'
```

Full filter grammar: `references/api.md`, section Filter operators.

### 5. Create an issue

You need the team's UUID (not its key). Get it once (recipe 8), then:

```bash
linear_gql 'mutation($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue { id identifier url }
  }
}' '{"input": {
  "teamId": "TEAM_UUID",
  "title": "Crash on empty input",
  "description": "Steps to reproduce…\n\n1. …",
  "priority": 2,
  "assigneeId": "USER_UUID",
  "labelIds": ["LABEL_UUID"]
}}' | jq '.data.issueCreate'
```

`description` is **Markdown**.

### 6. Update an issue (change state, assignee, priority, …)

```bash
linear_gql 'mutation($id: String!, $input: IssueUpdateInput!) {
  issueUpdate(id: $id, input: $input) {
    success
    issue { identifier state { name } assignee { name } }
  }
}' '{"id": "ENG-123", "input": {"stateId": "STATE_UUID", "priority": 1}}' | jq '.data.issueUpdate'
```

To move to "Done" / "In Progress" / etc. you need the workflow **state UUID**, which is per-team
(recipe 8 shows how to list them).

### 7. Comment on an issue

```bash
linear_gql 'mutation($input: CommentCreateInput!) {
  commentCreate(input: $input) { success comment { id url } }
}' '{"input": {"issueId": "ISSUE_UUID", "body": "Reproduced on main — looking into it."}}' \
  | jq '.data.commentCreate'
```

`body` is Markdown. `issueId` must be the UUID, not the identifier — fetch it with recipe 3 first.

### 8. Discover teams, workflow states, labels, members

You'll need these UUIDs for create/update mutations.

```bash
linear_gql '{
  teams {
    nodes {
      id key name
      states { nodes { id name type position } }
      labels { nodes { id name color } }
      members { nodes { id name email } }
    }
  }
}' | jq '.data.teams.nodes'
```

State `type` ∈ `backlog`, `unstarted`, `started`, `completed`, `canceled`, `triage`, `duplicate`.

### 9. Projects and cycles

```bash
linear_gql '{
  projects(first: 25, orderBy: updatedAt, filter: {status: {type: {neq: "completed"}}}) {
    nodes {
      id name description progress targetDate url
      status { name type }
      lead { name }
      teams { nodes { key } }
      issues(first: 5) { nodes { identifier title state { name } } }
    }
  }
}' | jq '.data.projects.nodes'

# current cycle for a team
linear_gql 'query($teamId: String!) {
  team(id: $teamId) {
    activeCycle {
      id number name startsAt endsAt progress
      issues { nodes { identifier title state { name } assignee { name } } }
    }
  }
}' '{"teamId": "TEAM_UUID"}' | jq '.data.team.activeCycle'
```

Connections have no `totalCount` field — to count issues, paginate and count `nodes`, or read an
aggregate field like `team { issueCount }`. Exception: the search payloads (`searchIssues`,
`searchProjects`, `searchDocuments`) do return `totalCount`.

### 10. Recent activity across the workspace

```bash
linear_gql '{
  issues(first: 25, orderBy: updatedAt) {
    nodes { identifier title state { name } assignee { name } team { key } updatedAt }
  }
}' | jq '.data.issues.nodes'
```

## Pagination

Every list field (`issues`, `nodes`, `projects`, `comments`, …) is a **connection** with cursor
pagination. The response carries `pageInfo`:

```bash
linear_gql 'query($cursor: String) {
  issues(first: 50, after: $cursor, orderBy: createdAt) {
    pageInfo { hasNextPage endCursor }
    nodes { identifier title }
  }
}' '{"cursor": null}' | jq '.data.issues'
```

Loop: pass `pageInfo.endCursor` as `$cursor`, stop when `hasNextPage` is `false`. Also stop (and
print the body) if the response has `.errors` or the extracted cursor is empty or the literal string
`null` — otherwise an error envelope loops forever. Always bound the loop with a max page count.
`first` caps at **250** per page (default 50). For reverse pagination use `last` / `before`.

## Rate limits

Linear enforces **per-user request limits** and **complexity limits** (roughly proportional to how
many nodes a query could touch). Every response carries:

```
X-RateLimit-Requests-Limit / -Remaining / -Reset
X-Complexity
X-RateLimit-Complexity-Limit / -Remaining / -Reset
```

API-key auth gets 5,000 requests/hour and 3,000,000 complexity points/hour (OAuth apps: 5,000
requests and 2,000,000 points per user per hour); a single query may not exceed 10,000 points. When
you're over, Linear returns **HTTP `400`** (not `429`) with
`errors[].extensions.code: "RATELIMITED"`. The `-Reset` headers are **UTC epoch milliseconds** —
works on both BSD/macOS and GNU date:

```bash
sleep $(( reset_ms / 1000 - $(date +%s) + 1 ))   # reset_ms from X-RateLimit-Requests-Reset
```

To lower complexity, request fewer fields, cap `first:`, and don't deeply nest connections you don't
need (e.g. don't select `comments` on every issue in a list).

## Error handling

GraphQL returns HTTP `200` for most application errors — **always check the body's `errors[]`**.

- **HTTP `400` + `code: "GRAPHQL_VALIDATION_FAILED"`** — Schema validation failed (unknown field/type). `errors[].message` names the bad field — fix the query, don't debug quoting.
- **HTTP `500` + `code: "GRAPHQL_VALIDATION_FAILED"`** — GraphQL **syntax** error (unbalanced braces, etc.). `errors[].message` shows the parse position.
- **HTTP `401`** — Bad or missing API key. Check `LINEAR_API_KEY`. Personal keys go in `Authorization:` with **no** `Bearer` prefix.
- **HTTP `400` + `code: "RATELIMITED"`** — Rate or complexity limit hit. Sleep until `X-RateLimit-…-Reset` (epoch **ms**), retry; or simplify the query (fewer fields, smaller `first:`).
- **`errors[].extensions.code: "INVALID_INPUT"` / `"INPUT_ERROR"`** — Validation failed. `message` names the bad field. Common: passing a key (`ENG`) where a UUID is required, or a query over the 10,000-point complexity cap.
- **`errors[].extensions.code: "ENTITY_NOT_FOUND"`** — ID doesn't exist or not visible. Check the ID. API-key scope is workspace-wide but respects team/project access.
- **`errors[].message: "Cannot query field …"`** — Typo or schema mismatch. Field doesn't exist. Check spelling; use introspection (`references/api.md`).

Mutations return a `success` boolean even when HTTP and `errors` are clean — check it before
assuming the write landed.

## Going deeper

`references/api.md` has the fuller catalog: all major object types and their fields, the filter
operator grammar, webhook config, file attachments, reactions, notifications, favorites,
workspace/organization queries, and schema introspection. Read it when you need an object or
mutation not covered above, or when you need the exact input shape for a create/update.
Files in this package (3)
  • SKILL.md 12 KB
  • references/api.md 13 KB
  • scripts/linear_issues.sh 8 KB

Versions

The database has no other skills named linear-api.

Database snapshot: 13.11.2026 · package version 07e1a5c7f7f2 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100linear
    Manage Linear teams, projects, cycles, issues, comments, workflow state, and documents from a terminal through Linear's public GraphQL API. Use when a user asks to list, search, inspect, create, update, move, or comment on Linear work, or to find Linear documents. Do not use to…
  • 90linear
    Use when user references Linear, linear.app/*/issue/ URLs, or an issue key like ENG-123, or asks to list, read, search or update Linear issues, teams, projects or cycles. Goes through the linear MCP server.
  • 100jira-api
    Read and manage Jira Cloud issues, projects, boards, sprints, comments, and transitions. Use this whenever the user wants to search issues with JQL, create or update a ticket, transition an issue (move to In Progress / Done), add a comment, check a sprint or board, look up a…
  • 90linear
    Manage Linear issues, projects and cycles via the Linear MCP server. Use when the user wants to read, triage, create or update Linear tickets, plan a sprint, audit Linear documentation, or rebalance team workload.
  • 100cc-linear
    Execute Linear operations via direct GraphQL API — create issues, update status/priority/title, add comments, search tasks, manage labels, assign work, and link PRs. Use this skill when the user mentions Linear explicitly, or references a Linear-style identifier (uppercase team…
  • 100cc-linear
    Execute Linear operations via direct GraphQL API — create issues, update status/priority/title, add comments, search tasks, manage labels, assign work, and link PRs. Use this skill when the user mentions Linear explicitly, or references a Linear-style identifier (uppercase team…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.