Linear

2026-03-25 新闻来源：网淘吧围观:87

电脑广告

手机广告

Linear

通过托管的OAuth认证访问Linear API。使用GraphQL查询和管理问题、项目、团队、周期、标签和评论。

快速开始

# 获取当前用户信息
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

基础URL

https://gateway.maton.ai/linear/graphql

所有请求都使用POST方法发送到GraphQL端点。网关将请求代理到api.linear.app并自动注入您的OAuth令牌。

认证

所有请求都需要在Authorization头中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：将您的API密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

登录或创建账户，请访问maton.ai
前往maton.ai/settings
复制您的API密钥

连接管理

管理您的Linear OAuth连接，请访问https://ctrl.maton.ai。

列出连接

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

创建连接

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

获取连接

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

响应：

{
  "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": {}
  }
}

打开返回的网址在浏览器中完成 OAuth 授权。

删除连接

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

指定连接

如果您有多个 Linear 连接，请使用Maton-Connection请求头指定要使用的连接：

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

如果省略，网关将使用默认（最早创建的）活跃连接。

API 参考

Linear 使用 GraphQL API。所有操作都作为 POST 请求发送，请求体为 JSON，包含query字段。

查看者（当前用户）

POST /linear/graphql
Content-Type: application/json

{"query": "{ viewer { id name email } }"}

响应：

{
  "data": {
    "viewer": {
      "id": "4933b394-c42f-4623-904f-355fc40a4858",
      "name": "Byungkyu Park",
      "email": "byungkyujpark@gmail.com"
    }
  }
}

组织

POST /linear/graphql
Content-Type: application/json

{"query": "{ organization { id name urlKey } }"}

团队

列出团队

POST /linear/graphql
Content-Type: application/json

{"query": "{ teams { nodes { id name key } } }"}

响应：

{
  "data": {
    "teams": {
      "nodes": [
        {
          "id": "70c49a0d-6973-4563-a743-8504f1a5171b",
          "name": "Maton",
          "key": "MTN"
        }
      ]
    }
  }
}

获取团队

POST /linear/graphql
Content-Type: application/json

{"query": "{ team(id: \"TEAM_ID\") { id name key issues { nodes { id identifier title } } } }"}

事项

列出事项

POST /linear/graphql
Content-Type: application/json

{"query": "{ issues(first: 10) { nodes { id identifier title state { name } priority createdAt } pageInfo { hasNextPage endCursor } } }"}

响应：

{
  "data": {
    "issues": {
      "nodes": [
        {
          "id": "565e2ee9-2552-48d8-bbf9-a8b79ca1baec",
          "identifier": "MTN-527",
          "title": "Shopify 应用验证",
          "state": { "name": "进行中" },
          "priority": 0,
          "createdAt": "2026-02-03T07:49:31.675Z"
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "4c7b33c8-dabf-47ce-9d30-7f286f9463be"
      }
    }
  }
}

根据 ID 或标识符获取事项

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 } }"}

筛选事项

按状态类型筛选：

POST /linear/graphql
Content-Type: application/json

{"query": "{ issues(first: 10, filter: { state: { type: { eq: \"started\" } } }) { nodes { id identifier title state { name type } } } }"}

按标题筛选：

POST /linear/graphql
Content-Type: application/json

{"query": "{ issues(first: 10, filter: { title: { containsIgnoreCase: \"bug\" } }) { nodes { id identifier title } } }"}

搜索问题

POST /linear/graphql
Content-Type: application/json

{"query": "{ searchIssues(first: 10, term: \"shopify\") { nodes { id identifier title } } }"}

创建问题

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 } } } }"}

响应：

{
  "data": {
    "issueCreate": {
      "success": true,
      "issue": {
        "id": "9dff693f-27d2-4656-9b2d-baa4a828dc83",
        "identifier": "MTN-528",
        "title": "New issue title",
        "state": { "name": "Backlog" }
      }
    }
  }
}

更新问题

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 } } }"}

项目

列出项目

POST /linear/graphql
Content-Type: application/json

{"query": "{ projects(first: 10) { nodes { id name state createdAt } } }"}

周期

列出周期

POST /linear/graphql
Content-Type: application/json

{"query": "{ cycles(first: 10) { nodes { id name number startsAt endsAt } } }"}

{
  "data": {
    "issueLabels": {
      "nodes": [
        { "id": "510edbdf-9f6e-43a0-80e5-c3b3bd82e26f", "name": "已阻塞", "color": "#eb5757" },
        { "id": "cb7a7ef2-d2d3-4da2-ad4e-7cea0f8a72c7", "name": "功能", "color": "#BB87FC" },
        { "id": "c795d04c-24d2-4d20-b3c1-9f9f1ce7b017", "name": "改进", "color": "#4EA7FC" },
        { "id": "40ff69f9-4a93-40a2-b143-f3b94aa594b7", "name": "缺陷", "color": "#EB5757" }
      ]
    }
  }
}

工作流状态

POST /linear/graphql
Content-Type: application/json

{"query": "{ workflowStates(first: 20) { nodes { id name type team { key } } } }"}

响应：

{
  "data": {
    "workflowStates": {
      "nodes": [
        { "id": "f21dfa65-7951-4742-a202-00ceb0ff6e9f", "name": "待办列表", "type": "backlog", "team": { "key": "MTN" } },
        { "id": "1ab9475f-eb91-4207-a5a3-1176e38b85be", "name": "待处理", "type": "unstarted", "team": { "key": "MTN" } },
        { "id": "ee724a62-0212-4b53-af67-08297a5ae132", "name": "进行中", "type": "started", "team": { "key": "MTN" } },
        { "id": "427a9916-3849-4303-b982-f00f1d79c5ee", "name": "已完成", "type": "completed", "team": { "key": "MTN" } },
        { "id": "363df32a-f22d-4083-8efb-b3615c019925", "name": "已取消", "type": "canceled", "team": { "key": "MTN" } }
      ]
    }
  }
}

用户

POST /linear/graphql
Content-Type: application/json

{"query": "{ users(first: 20) { nodes { id name email active } } }"}

列出评论

POST /linear/graphql
Content-Type: application/json

{"query": "{ comments(first: 10) { nodes { id body createdAt issue { identifier } user { name } } } }"}

创建评论

POST /linear/graphql
Content-Type: application/json

{"query": "mutation { commentCreate(input: { issueId: \"ISSUE_ID\", body: \"评论内容写在这里\" }) { success comment { id body } } }"}

分页

Linear 采用 Relay 风格基于游标的分页机制，使用first/after和last/before参数。

# 第一页
POST /linear/graphql
{"query": "{ issues(first: 10) { nodes { id identifier title } pageInfo { hasNextPage endCursor } } }"}

# 使用 endCursor 获取下一页
POST /linear/graphql
{"query": "{ issues(first: 10, after: \"CURSOR_VALUE\") { nodes { id identifier title } pageInfo { hasNextPage endCursor } } }"}

响应包含pageInfo：

{
  "data": {
    "issues": {
      "nodes": [...],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "4c7b33c8-dabf-47ce-9d30-7f286f9463be"
      }
    }
  }
}

代码示例

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();

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()

注意事项

Linear 仅使用 GraphQL（无 REST API）
问题标识符如MTN-527可用于替代 UUID 作为id参数
优先级数值：0 = 无优先级，1 = 紧急，2 = 高，3 = 中，4 = 低
工作流状态类型：待办、未开始、已开始、已完成、已取消
GraphQL 架构可在以下地址内省：https://api.linear.app/graphql
使用searchIssues(term: "...")用于跨问题全文搜索
某些操作（删除、创建标签/项目）可能需要额外的OAuth权限范围。如果您收到权限范围错误，请联系Maton支持邮箱support@maton.ai并提供您需要的具体操作/API以及您的使用场景

错误处理

状态码	含义
400	缺少Linear连接或GraphQL验证错误
401	Maton API密钥无效或缺失
403	操作所需的OAuth权限不足
429	请求频率受限
4xx/5xx	来自Linear API的透传错误

GraphQL错误会在errors数组中返回：

{
  "errors": [
    {
      "message": "权限范围无效：需要`write`权限",
      "extensions": {
        "type": "forbidden",
        "code": "FORBIDDEN",
        "statusCode": 403
      }
    }
  ]
}

故障排除：API密钥问题

检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接来验证API密钥是否有效：

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

故障排除：无效的应用名称

确保您的URL路径以linear开头。例如：

正确：https://gateway.maton.ai/linear/graphql
错误：https://gateway.maton.ai/graphql

资源

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：Zoho CRM 下一篇：Fastest Browser Use

Linear

Linear

快速开始

基础URL

认证

获取您的API密钥

连接管理

列出连接

创建连接

获取连接

删除连接

指定连接

API 参考

查看者（当前用户）

组织

团队

列出团队

获取团队

事项

列出事项

根据 ID 或标识符获取事项

筛选事项

搜索问题

创建问题

更新问题

项目

列出项目

周期

列出周期

标签

列出标签

工作流状态

用户

评论

列出评论

创建评论

分页

代码示例

JavaScript

Python

注意事项

错误处理

故障排除：API密钥问题

故障排除：无效的应用名称

资源

相关文章

推荐文章

热门浏览

标签列表