介绍
{ "text": "# Linear\n\n使用托管式 OAuth 身份验证访问 Linear API。通过 GraphQL 查询和管理事项、项目、团队、周期、标签和评论。\n\n## Quick Start\n\n```bash # Linear python <<'EOF' import urllib.request, os, json data = json.dumps({'query': '{ viewer { id name email } }'}).encode() req = urllib.request.Request('https://gateway.maton.ai/linear/graphql', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```\n\n## Base URL\n\n``` https://gateway.maton.ai/linear/graphql ```\n\n所有请求均使用 POST 方法发送至 GraphQL 端点。网关将请求代理至 `api.linear.app`，并自动注入您的 OAuth 令牌。\n\n## Authentication\n\n所有请求都需要在 Authorization 头中包含 Maton API 密钥：\n\n``` Authorization: Bearer $MATON_API_KEY ```\n\n**Environment Variable:** 将您的 API 密钥设置为 `MATON_API_KEY`：\n\n```bash export MATON_API_KEY="YOUR_API_KEY" ```\n\n### Getting Your API Key\n\n1. 在 [maton.ai](https://maton.ai) 登录或创建账户\n2. 访问 [maton.ai/settings](https://maton.ai/settings)\n3. 复制您的 API 密钥\n\n## Connection Management\n\n在 `https://ctrl.maton.ai` 管理您的 Linear OAuth 连接。\n\n### List Connections\n\n```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=linear&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```\n\n### Create Connection\n\n```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'linear'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```\n\n### Get Connection\n\n```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```\n\n**Response:**\n```json { "connection": { "connection_id": "fda4dabb-9d62-47e3-9503-a2f29d0995df", "status": "ACTIVE", "creation_time": "2026-02-04T23:03:22.676001Z", "last_updated_time": "2026-02-04T23:03:51.239577Z", "url": "https://connect.maton.ai/?session_token=...", "app": "linear", "metadata": {} } } ```\n\n在浏览器中打开返回的 `url` 以完成 OAuth 授权。\n\n### Delete Connection\n\n```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```\n\n### Specifying Connection\n\n如果您有多个 Linear 连接，请使用 `Maton-Connection` 头指定要使用的连接：\n\n```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'query': '{ viewer { id name } }'}).encode() req = urllib.request.Request('https://gateway.maton.ai/linear/graphql', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') req.add_header('Maton-Connection', 'fda4dabb-9d62-47e3-9503-a2f29d0995df') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```\n\n如果省略，网关将使用默认（最早）的活跃连接。\n\n## API Reference\n\nLinear 使用 GraphQL API。所有操作均作为 POST 请求发送，其 JSON 请求体包含 `query` 字段。\n\n### Viewer (Current User)\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ viewer { id name email } }"} ```\n\n**Response:**\n```json { "data": { "viewer": { "id": "4933b394-c42f-4623-904f-355fc40a4858", "name": "Byungkyu Park", "email": "[email protected]" } } } ```\n\n### Organization\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ organization { id name urlKey } }"} ```\n\n### Teams\n\n#### List Teams\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ teams { nodes { id name key } } }"} ```\n\n**Response:**\n```json { "data": { "teams": { "nodes": [ { "id": "70c49a0d-6973-4563-a743-8504f1a5171b", "name": "Maton", "key": "MTN" } ] } } } ```\n\n#### Get Team\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ team(id: \"TEAM_ID\") { id name key issues { nodes { id identifier title } } } }"} ```\n\n### Issues\n\n#### List Issues\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ issues(first: 10) { nodes { id identifier title state { name } priority createdAt } pageInfo { hasNextPage endCursor } } }"} ```\n\n**Response:**\n```json { "data": { "issues": { "nodes": [ { "id": "565e2ee9-2552-48d8-bbf9-a8b79ca1baec", "identifier": "MTN-527", "title": "Shopify app verification", "state": { "name": "In Progress" }, "priority": 0, "createdAt": "2026-02-03T07:49:31.675Z" } ], "pageInfo": { "hasNextPage": true, "endCursor": "4c7b33c8-dabf-47ce-9d30-7f286f9463be" } } } } ```\n\n#### Get Issue by ID or Identifier\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ issue(id: \"MTN-527\") { id identifier title description state { name } priority assignee { name } team { key name } createdAt updatedAt } }"} ```\n\n#### Filter Issues\n\n按状态类型筛选：\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ issues(first: 10, filter: { state: { type: { eq: \"started\" } } }) { nodes { id identifier title state { name type } } } }"} ```\n\n按标题筛选：\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ issues(first: 10, filter: { title: { containsIgnoreCase: \"bug\" } }) { nodes { id identifier title } } }"} ```\n\n#### Search Issues\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ searchIssues(first: 10, term: \"shopify\") { nodes { id identifier title } } }"} ```\n\n#### Create Issue\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "mutation { issueCreate(input: { teamId: \"TEAM_ID\", title: \"New issue title\", description: \"Issue description\" }) { success issue { id identifier title state { name } } } }"} ```\n\n**Response:**\n```json { "data": { "issueCreate": { "success": true, "issue": { "id": "9dff693f-27d2-4656-9b2d-baa4a828dc83", "identifier": "MTN-528", "title": "New issue title", "state": { "name": "Backlog" } } } } } ```\n\n#### Update Issue\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "mutation { issueUpdate(id: \"ISSUE_ID\", input: { title: \"Updated title\", priority: 2 }) { success issue { id identifier title priority } } }"} ```\n\n### Projects\n\n#### List Projects\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ projects(first: 10) { nodes { id name state createdAt } } }"} ```\n\n### Cycles\n\n#### List Cycles\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ cycles(first: 10) { nodes { id name number startsAt endsAt } } }"} ```\n\n### Labels\n\n#### List Labels\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ issueLabels(first: 20) { nodes { id name color } } }"} ```\n\n**Response:**\n```json { "data": { "issueLabels": { "nodes": [ { "id": "510edbdf-9f6e-43a0-80e5-c3b3bd82e26f", "name": "Blocked", "color": "#eb5757" }, { "id": "cb7a7ef2-d2d3-4da2-ad4e-7cea0f8a72c7", "name": "Feature", "color": "#BB87FC" }, { "id": "c795d04c-24d2-4d20-b3c1-9f9f1ce7b017", "name": "Improvement", "color": "#4EA7FC" }, { "id": "40ff69f9-4a93-40a2-b143-f3b94aa594b7", "name": "Bug", "color": "#EB5757" } ] } } } ```\n\n### Workflow States\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ workflowStates(first: 20) { nodes { id name type team { key } } } }"} ```\n\n**Response:**\n```json { "data": { "workflowStates": { "nodes": [ { "id": "f21dfa65-7951-4742-a202-00ceb0ff6e9f", "name": "Backlog", "type": "backlog", "team": { "key": "MTN" } }, { "id": "1ab9475f-eb91-4207-a5a3-1176e38b85be", "name": "Todo", "type": "unstarted", "team": { "key": "MTN" } }, { "id": "ee724a62-0212-4b53-af67-08297a5ae132", "name": "In Progress", "type": "started", "team": { "key": "MTN" } }, { "id": "427a9916-3849-4303-b982-f00f1d79c5ee", "name": "Done", "type": "completed", "team": { "key": "MTN" } }, { "id": "363df32a-f22d-4083-8efb-b3615c019925", "name": "Canceled", "type": "canceled", "team": { "key": "MTN" } } ] } } } ```\n\n### Users\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ users(first: 20) { nodes { id name email active } } }"} ```\n\n### Comments\n\n#### List Comments\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "{ comments(first: 10) { nodes { id body createdAt issue { identifier } user { name } } } }"} ```\n\n#### Create Comment\n\n```bash POST /linear/graphql Content-Type: application/json
{"query": "mutation { commentCreate(input: { issueId: \"ISSUE_ID\", body: \"Comment text here\" }) { success comment { id body } } }"} ```\n\n## Pagination\n\nLinear 使用 Relay 风格的基于游标的分页，参数包括 `first/after` 和 `last/before`。\n\n```bash # First page POST /linear/graphql {"query": "{ issues(first: 10) { nodes { id identifier title } pageInfo { hasNextPage endCursor } } }"}
# Next page using endCursor POST /linear/graphql {"query": "{ issues(first: 10, after: \"CURSOR_VALUE\") { nodes { id identifier title } pageInfo { hasNextPage endCursor } } }"} ```\n\n响应包含 `pageInfo`：\n\n```json { "data": { "issues": { "nodes": [...], "pageInfo": { "hasNextPage": true, "endCursor": "4c7b33c8-dabf-47ce-9d30-7f286f9463be" } } } } ```\n\n## Code Examples\n\n### JavaScript\n\n```javascript const response = await fetch('https://gateway.maton.ai/linear/graphql', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: `{ issues(first: 10) { nodes { id identifier title state { name } } } }` }) }); const data = await response.json(); ```\n\n### Python\n\n```python import os import requests
response = requests.post( 'https://gateway.maton.ai/linear/graphql', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }, json={ 'query': '{ issues(first: 10) { nodes { id identifier title state { name } } } }' } ) data = response.json() ```\n\n## Notes\n\n- Linear 专门使用 GraphQL（无 REST API）\n- 事项标识符（如 `MTN-527`）可以代替 UUID 用作 `id` 参数\n- 优先级值：0 = 无优先级, 1 = 紧急, 2 = 高, 3 = 中, 4 = 低\n- 工作流状态类型：`backlog`, `unstarted`, `started`, `completed`, `canceled`\n- GraphQL Schema 可以在 `https://api.linear.app/graphql` 进行内省\n- 使用 `searchIssues(term: \"...\\")` 对事项进行全文搜索\n- 某些变更操作（删除、创建标签/项目）可能需要额外的 OAuth 范围。如果您收到范围错误，请联系 Maton 支持团队 [email protected]，说明您需要的具体操作/API 以及您的用例\n\n## Error Handling\n\n| Status | Meaning |\n|--------|---------|\n| 400 | 缺少 Linear 连接或 GraphQL 验证错误 |\n| 401 | Maton API 密钥无效或缺失 |\n| 403 | 操作所需的 OAuth 范围不足 |\n| 429 | 请求被限流 |\n| 4xx/5xx | 来自 Linear API 的透传错误 |\n\nGraphQL 错误在 `errors` 数组中返回：\n\n```json { "errors": [ { "message": "Invalid scope: `write` required", "extensions": { "type": "forbidden", "code": "FORBIDDEN", "statusCode": 403 } } ] } ```\n\n### Troubleshooting: API Key Issues\n\n1. 检查是否设置了 `MATON_API_KEY` 环境变量：\n\n```bash echo $MATON_API_KEY ```\n\n2. 通过列出连接来验证 API 密钥是否有效：\n\n```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```\n\n### Troubleshooting: Invalid App Name\n\n1. 确保您的 URL 路径以 `linear` 开头。例如：\n\n- 正确：`https://gateway.maton.ai/linear/graphql`\n- 错误：`https://gateway.maton.ai/graphql`\n\n## Resources\n\n- [Linear API 概览](https://linear.app/developers)\n- [Linear GraphQL 入门](https://linear.app/developers/graphql)\n- [Linear GraphQL Schema (Apollo Studio)](https://studio.apollographql.com/public/Linear-API/schema/reference?variant=current)\n- [Linear API 和 Webhooks](https://linear.app/docs/api-and-webhooks)\n- [Maton 社区](https://discord.com/invite/dBfFAcefs2)\n- [Maton 支持](mailto:[email protected])" }