Back to Details

linear

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Linear — Issue & Project Management

Linear — 任务与项目管理

Manage Linear issues, projects, and teams directly via the GraphQL API using 
curl
. No MCP server, no OAuth flow, no extra dependencies.
无需MCP服务器、OAuth流程或额外依赖，直接通过GraphQL API使用
curl
管理Linear任务、项目与团队。

Setup

配置步骤

  1. Get a personal API key from Linear Settings > Account > Security & access > Personal API keys (URL: https://linear.app/settings/account/security). Note: the org-level Settings > API page only shows OAuth apps and workspace-member keys, not personal keys.
  2. Set 
    LINEAR_API_KEY
    in your environment (via 
    hermes setup
    or your env config)
  1. 从Linear设置 > 账户 > 安全与访问 > 个人API密钥获取个人API密钥（链接：https://linear.app/settings/account/security）。注意：组织级别的*设置 > API*页面仅显示OAuth应用和工作区成员密钥，不显示个人密钥。
  2. 在环境变量中设置
    LINEAR_API_KEY
    （可通过
    hermes setup
    或环境配置文件完成）

API Basics

API基础信息

  • Endpoint: 
    https://api.linear.app/graphql
    (POST)
  • Auth header: 
    Authorization: $LINEAR_API_KEY
    (no "Bearer" prefix for API keys)
  • All requests are POST with 
    Content-Type: application/json
  • Both UUIDs and short identifiers (e.g., 
    ENG-123
    ) work for 
    issue(id:)
Base curl pattern:
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name } }"}' | python3 -m json.tool
  • 端点地址： 
    https://api.linear.app/graphql
    （POST请求）
  • 认证头： 
    Authorization: $LINEAR_API_KEY
    （API密钥无需添加"Bearer"前缀）
  • 所有请求均为POST，需设置
    Content-Type: application/json
  • UUID和短标识符（例如
    ENG-123
    ）均可用于
    issue(id:)
    查询
基础curl调用模板：
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name } }"}' | python3 -m json.tool

Python helper script (ergonomic alternative)

Python辅助脚本（更便捷的替代方案）

For faster one-liners that don't need hand-written GraphQL, this skill ships a stdlib Python CLI at 
scripts/linear_api.py
. Zero dependencies. Same auth (reads 
LINEAR_API_KEY
).
bash
SCRIPT=$(dirname "$(find ~/.hermes -path '*skills/productivity/linear/scripts/linear_api.py' 2>/dev/null | head -1)")/linear_api.py

python3 "$SCRIPT" whoami
python3 "$SCRIPT" list-teams
python3 "$SCRIPT" get-issue ENG-42
python3 "$SCRIPT" get-document 38359beef67c      # fetch a doc by slugId from the URL
python3 "$SCRIPT" raw 'query { viewer { name } }'
All subcommands: 
whoami
, 
list-teams
, 
list-projects
, 
list-states
, 
list-issues
, 
get-issue
, 
search-issues
, 
create-issue
, 
update-issue
, 
update-status
, 
add-comment
, 
list-documents
, 
get-document
, 
search-documents
, 
raw
. Run with 
--help
for flags.
Use the script when: you want a quick answer without crafting GraphQL. Use curl when: you need a query the script doesn't wrap, or you want to compose filters inline.
如需快速执行单命令操作，无需手动编写GraphQL语句，本技能提供了一个基于标准库的Python CLI脚本，位于
scripts/linear_api.py
，无额外依赖，同样通过读取
LINEAR_API_KEY
进行认证。
bash
SCRIPT=$(dirname "$(find ~/.hermes -path '*skills/productivity/linear/scripts/linear_api.py' 2>/dev/null | head -1)")/linear_api.py

python3 "$SCRIPT" whoami
python3 "$SCRIPT" list-teams
python3 "$SCRIPT" get-issue ENG-42
python3 "$SCRIPT" get-document 38359beef67c      # 通过URL中的slugId获取文档
python3 "$SCRIPT" raw 'query { viewer { name } }'
所有子命令：
whoami
、
list-teams
、
list-projects
、
list-states
、
list-issues
、
get-issue
、
search-issues
、
create-issue
、
update-issue
、
update-status
、
add-comment
、
list-documents
、
get-document
、
search-documents
、
raw
。添加
--help
参数可查看各命令的可用选项。
当你无需编写GraphQL语句即可快速获取结果时，使用该脚本；当脚本未封装所需查询，或需要自定义过滤条件时，使用curl。

Workflow States

工作流状态

Linear uses 
WorkflowState
objects with a 
type
field. 6 state types:
TypeDescription
triage
Incoming issues needing review
backlog
Acknowledged but not yet planned
unstarted
Planned/ready but not started
started
Actively being worked on
completed
Done
canceled
Won't do
Each team has its own named states (e.g., "In Progress" is type 
started
). To change an issue's status, you need the 
stateId
(UUID) of the target state — query workflow states first.
Priority values: 0 = None, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low
Linear使用带有
type
字段的
WorkflowState
对象，包含6种状态类型：
类型描述
triage
待审核的新提交任务
backlog
已确认但尚未规划的任务
unstarted
已规划/就绪但未开始的任务
started
正在处理中的任务
completed
已完成的任务
canceled
无需处理的任务
每个团队都有自定义命名的状态（例如"进行中"对应
started
类型）。如需更改任务状态，需先获取目标状态的
stateId
（UUID）——可先查询工作流状态列表。
优先级值： 0 = 无，1 = 紧急，2 = 高，3 = 中，4 = 低

Common Queries

常用查询

Get current user

获取当前用户信息

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}' | python3 -m json.tool

List teams

列出所有团队

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ teams { nodes { id name key } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ teams { nodes { id name key } } }"}' | python3 -m json.tool

List workflow states for a team

列出指定团队的工作流状态

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ workflowStates(filter: { team: { key: { eq: \"ENG\" } } }) { nodes { id name type } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ workflowStates(filter: { team: { key: { eq: \"ENG\" } } }) { nodes { id name type } } }"}' | python3 -m json.tool

List issues (first 20)

列出任务（前20条）

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(first: 20) { nodes { identifier title priority state { name type } assignee { name } team { key } url } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(first: 20) { nodes { identifier title priority state { name type } assignee { name } team { key } url } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool

List my assigned issues

列出我负责的任务

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { assignedIssues(first: 25) { nodes { identifier title state { name type } priority url } } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { assignedIssues(first: 25) { nodes { identifier title state { name type } priority url } } } }"}' | python3 -m json.tool

Get a single issue (by identifier like ENG-123)

获取单个任务（通过ENG-123这类标识符）

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issue(id: \"ENG-123\") { id identifier title description priority state { id name type } assignee { id name } team { key } project { name } labels { nodes { name } } comments { nodes { body user { name } createdAt } } url } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issue(id: \"ENG-123\") { id identifier title description priority state { id name type } assignee { id name } team { key } project { name } labels { nodes { name } } comments { nodes { body user { name } createdAt } } url } }"}' | python3 -m json.tool

Search issues by text

通过文本搜索任务

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issueSearch(query: \"bug login\", first: 10) { nodes { identifier title state { name } assignee { name } url } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issueSearch(query: \"bug login\", first: 10) { nodes { identifier title state { name } assignee { name } url } } }"}' | python3 -m json.tool

Filter issues by state type

按状态类型过滤任务

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(filter: { state: { type: { in: [\"started\"] } } }, first: 20) { nodes { identifier title state { name } assignee { name } } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(filter: { state: { type: { in: [\"started\"] } } }, first: 20) { nodes { identifier title state { name } assignee { name } } } }"}' | python3 -m json.tool

Filter by team and assignee

按团队和负责人过滤任务

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(filter: { team: { key: { eq: \"ENG\" } }, assignee: { email: { eq: \"user@example.com\" } } }, first: 20) { nodes { identifier title state { name } priority } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issues(filter: { team: { key: { eq: \"ENG\" } }, assignee: { email: { eq: \"user@example.com\" } } }, first: 20) { nodes { identifier title state { name } priority } } }"}' | python3 -m json.tool

List projects

列出所有项目

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ projects(first: 20) { nodes { id name description progress lead { name } teams { nodes { key } } url } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ projects(first: 20) { nodes { id name description progress lead { name } teams { nodes { key } } url } } }"}' | python3 -m json.tool

List team members

列出团队成员

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ users { nodes { id name email active } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ users { nodes { id name email active } } }"}' | python3 -m json.tool

List labels

列出标签

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issueLabels { nodes { id name color } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ issueLabels { nodes { id name color } } }"}' | python3 -m json.tool

Common Mutations

常用变更操作

Create an issue

创建任务

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title url } } }",
    "variables": {
      "input": {
        "teamId": "TEAM_UUID",
        "title": "Fix login bug",
        "description": "Users cannot login with SSO",
        "priority": 2
      }
    }
  }' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title url } } }",
    "variables": {
      "input": {
        "teamId": "TEAM_UUID",
        "title": "修复登录bug",
        "description": "用户无法通过SSO登录",
        "priority": 2
      }
    }
  }' | python3 -m json.tool

Update issue status

更新任务状态

First get the target state UUID from the workflow states query above, then:
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { stateId: \"STATE_UUID\" }) { success issue { identifier state { name type } } } }"}' | python3 -m json.tool
先通过上述工作流状态查询获取目标状态UUID，然后执行：
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { stateId: \"STATE_UUID\" }) { success issue { identifier state { name type } } } }"}' | python3 -m json.tool

Assign an issue

分配任务

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { assigneeId: \"USER_UUID\" }) { success issue { identifier assignee { name } } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { assigneeId: \"USER_UUID\" }) { success issue { identifier assignee { name } } } }"}' | python3 -m json.tool

Set priority

设置优先级

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { priority: 1 }) { success issue { identifier priority } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { priority: 1 }) { success issue { identifier priority } } }"}' | python3 -m json.tool

Add a comment

添加评论

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { commentCreate(input: { issueId: \"ISSUE_UUID\", body: \"Investigated. Root cause is X.\" }) { success comment { id body } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { commentCreate(input: { issueId: \"ISSUE_UUID\", body: \"已完成调查，根因为X。\" }) { success comment { id body } } }"}' | python3 -m json.tool

Set due date

设置截止日期

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { dueDate: \"2026-04-01\" }) { success issue { identifier dueDate } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { dueDate: \"2026-04-01\" }) { success issue { identifier dueDate } } }"}' | python3 -m json.tool

Add labels to an issue

为任务添加标签

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { labelIds: [\"LABEL_UUID_1\", \"LABEL_UUID_2\"] }) { success issue { identifier labels { nodes { name } } } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { labelIds: [\"LABEL_UUID_1\", \"LABEL_UUID_2\"] }) { success issue { identifier labels { nodes { name } } } } }"}' | python3 -m json.tool

Add issue to a project

将任务添加到项目

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { projectId: \"PROJECT_UUID\" }) { success issue { identifier project { name } } } }"}' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { issueUpdate(id: \"ENG-123\", input: { projectId: \"PROJECT_UUID\" }) { success issue { identifier project { name } } } }"}' | python3 -m json.tool

Create a project

创建项目

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($input: ProjectCreateInput!) { projectCreate(input: $input) { success project { id name url } } }",
    "variables": {
      "input": {
        "name": "Q2 Auth Overhaul",
        "description": "Replace legacy auth with OAuth2 and PKCE",
        "teamIds": ["TEAM_UUID"]
      }
    }
  }' | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation($input: ProjectCreateInput!) { projectCreate(input: $input) { success project { id name url } } }",
    "variables": {
      "input": {
        "name": "Q2认证体系重构",
        "description": "用OAuth2和PKCE替换旧认证系统",
        "teamIds": ["TEAM_UUID"]
      }
    }
  }' | python3 -m json.tool

Documents

文档功能

Linear Documents are prose docs (RFCs, specs, notes) stored alongside issues. They have their own 
documents
root query and 
document(id:)
single-fetch.
Linear的Documents是与任务存储在一起的纯文本文档（如RFC、规范、笔记），拥有独立的
documents
根查询和
document(id:)
单文档查询接口。

Document URLs and 
slugId

文档URL与
slugId

Document URLs look like:
https://linear.app/<workspace>/document/<slug>-<hexSlugId>
The trailing hex segment is the 
slugId
. Example: 
https://linear.app/nousresearch/document/rfc-hermes-permission-gateway-discord-38359beef67c
→ 
slugId
is 
38359beef67c
.
Important schema detail: the Markdown body is in the 
content
field. The ProseMirror JSON is in 
contentState
(not 
contentData
— that field does not exist and the API returns 400).
文档URL格式如下：
https://linear.app/<workspace>/document/<slug>-<hexSlugId>
末尾的十六进制部分即为
slugId
。示例：
https://linear.app/nousresearch/document/rfc-hermes-permission-gateway-discord-38359beef67c
→ 
slugId
为
38359beef67c
。
重要模式细节： Markdown内容存储在
content
字段中，ProseMirror JSON格式内容存储在
contentState
字段（注意：不存在
contentData
字段，若使用该字段API会返回400错误）。

Fetch a document by slugId

通过slugId获取文档

document(id:)
only accepts UUIDs. To fetch by the URL's hex slug, filter the collection:
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "query($s: String!) { documents(filter: { slugId: { eq: $s } }, first: 1) { nodes { id title content contentState slugId url creator { name } project { name } updatedAt } } }", "variables": {"s": "38359beef67c"}}' \
  | python3 -m json.tool
Or via the Python helper:
bash
python3 scripts/linear_api.py get-document 38359beef67c
document(id:)
仅接受UUID参数。如需通过URL中的十六进制slug获取文档，需使用集合过滤：
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "query($s: String!) { documents(filter: { slugId: { eq: $s } }, first: 1) { nodes { id title content contentState slugId url creator { name } project { name } updatedAt } } }", "variables": {"s": "38359beef67c"}}' \
  | python3 -m json.tool
或通过Python辅助脚本：
bash
python3 scripts/linear_api.py get-document 38359beef67c

Fetch a document by UUID

通过UUID获取文档

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ document(id: \"11700cff-b514-4db3-afcc-3ed1afacba1c\") { title content url } }"}' \
  | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ document(id: \"11700cff-b514-4db3-afcc-3ed1afacba1c\") { title content url } }"}' \
  | python3 -m json.tool

List recent documents

列出最近更新的文档

bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ documents(first: 25, orderBy: updatedAt) { nodes { id title slugId url updatedAt project { name } } } }"}' \
  | python3 -m json.tool
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ documents(first: 25, orderBy: updatedAt) { nodes { id title slugId url updatedAt project { name } } } }"}' \
  | python3 -m json.tool

Search documents by title

通过标题搜索文档

Linear's schema has no 
searchDocuments
root. Use a title-substring filter instead:
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ documents(filter: { title: { containsIgnoreCase: \"RFC\" } }, first: 25) { nodes { title slugId url } } }"}' \
  | python3 -m json.tool
Linear的模式中没有
searchDocuments
根查询，可使用标题子串过滤替代：
bash
curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ documents(filter: { title: { containsIgnoreCase: \"RFC\" } }, first: 25) { nodes { title slugId url } } }"}' \
  | python3 -m json.tool

Pagination

分页机制

Linear uses Relay-style cursor pagination:
bash
undefined
Linear采用Relay风格的游标分页：
bash
undefined

First page

第一页

curl -s -X POST https://api.linear.app/graphql
-H "Authorization: $LINEAR_API_KEY"
-H "Content-Type: application/json"
-d '{"query": "{ issues(first: 20) { nodes { identifier title } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool
curl -s -X POST https://api.linear.app/graphql
-H "Authorization: $LINEAR_API_KEY"
-H "Content-Type: application/json"
-d '{"query": "{ issues(first: 20) { nodes { identifier title } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool

Next page — use endCursor from previous response

下一页 — 使用上一次响应中的endCursor

curl -s -X POST https://api.linear.app/graphql
-H "Authorization: $LINEAR_API_KEY"
-H "Content-Type: application/json"
-d '{"query": "{ issues(first: 20, after: "CURSOR_FROM_PREVIOUS") { nodes { identifier title } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool

Default page size: 50. Max: 250. Always use `first: N` to limit results.
curl -s -X POST https://api.linear.app/graphql
-H "Authorization: $LINEAR_API_KEY"
-H "Content-Type: application/json"
-d '{"query": "{ issues(first: 20, after: "CURSOR_FROM_PREVIOUS") { nodes { identifier title } pageInfo { hasNextPage endCursor } } }"}' | python3 -m json.tool

默认分页大小：50条。最大分页大小：250条。请始终使用`first: N`限制返回结果数量。

Filtering Reference

过滤参考

Comparators: 
eq
, 
neq
, 
in
, 
nin
, 
lt
, 
lte
, 
gt
, 
gte
, 
contains
, 
startsWith
, 
containsIgnoreCase
Combine filters with 
or: [...]
for OR logic (default is AND within a filter object).
比较运算符：
eq
、
neq
、
in
、
nin
、
lt
、
lte
、
gt
、
gte
、
contains
、
startsWith
、
containsIgnoreCase
使用
or: [...]
组合过滤器实现OR逻辑（过滤器对象内默认使用AND逻辑）。

Typical Workflow

典型工作流

  1. Query teams to get team IDs and keys
  2. Query workflow states for target team to get state UUIDs
  3. List or search issues to find what needs work
  4. Create issues with team ID, title, description, priority
  5. Update status by setting 
    stateId
    to the target workflow state
  6. Add comments to track progress
  7. Mark complete by setting 
    stateId
    to the team's "completed" type state
  1. 查询团队信息获取团队ID和标识
  2. 查询目标团队的工作流状态获取状态UUID
  3. 列出或搜索任务找到需要处理的内容
  4. 创建任务，指定团队ID、标题、描述和优先级
  5. 更新任务状态，将
    stateId
    设置为目标工作流状态的UUID
  6. 添加评论跟踪进度
  7. 标记任务完成，将
    stateId
    设置为团队对应的"completed"类型状态

Rate Limits

请求限制

  • 5,000 requests/hour per API key
  • 3,000,000 complexity points/hour
  • Use 
    first: N
    to limit results and reduce complexity cost
  • Monitor 
    X-RateLimit-Requests-Remaining
    response header
  • 每个API密钥每小时最多5000次请求
  • 每小时最多3000000复杂度点数
  • 使用
    first: N
    限制返回结果数量，降低复杂度消耗
  • 通过响应头
    X-RateLimit-Requests-Remaining
    监控剩余请求次数

Important Notes

重要注意事项

  • Always use 
    terminal
    tool with 
    curl
    for API calls — do NOT use 
    web_extract
    or 
    browser
  • Always check the 
    errors
    array in GraphQL responses — HTTP 200 can still contain errors
  • If 
    stateId
    is omitted when creating issues, Linear defaults to the first backlog state
  • The 
    description
    field supports Markdown
  • Use 
    python3 -m json.tool
    or 
    jq
    to format JSON responses for readability
  • 调用API时请始终使用
    terminal
    工具执行
    curl
    命令 — 不要使用
    web_extract
    或
    browser
  • 请始终检查GraphQL响应中的
    errors
    数组 — HTTP 200状态码仍可能包含错误信息
  • 创建任务时如果省略
    stateId
    ，Linear会默认将其设置为第一个待办状态
  • description
    字段支持Markdown格式
  • 使用
    python3 -m json.tool
    或
    jq
    格式化JSON响应，提升可读性