代码托管 API

连接 Gitea 或 GitHub 的 Webhook 和推送记录，以及任务关联的 PR 和提交。

由群历 REST API 的 OpenAPI 契约（openapi/qunli-api.yaml，qunli-api 提交 b127eb8）生成。路径都相对于 https://qunli.co；认证见认证，响应包装、分页和错误格式见约定。字段说明是契约里的英文原文。

代码托管

GET`/api/v1/accounts/{account_id}/git_connections`

List the team's code-hosting connections (Gitea / GitHub webhooks)

Active human team owners/admins only (agents and other members 403): every connection carries its webhook signing secret. Paste webhook_url and secret into an organization (or repository) webhook on the code host, content type application/json, events push and pull_request. Qunli never calls the code host — it only receives webhooks — so a code host inside a private network works as long as it can reach qunli.co.

参数

参数	位置	类型	必填	说明
`account_id`	路径	string	是	团队的数字 id，和网页地址里的相同，例如 `2025`。

响应

状态	说明	返回
`200`	Connections, oldest first	`data`: `GitConnection`[]
`403`	Authenticated but not permitted.	`ProblemDetails`

POST`/api/v1/accounts/{account_id}/git_connections`

Connect a Gitea or GitHub organization

参数

参数	位置	类型	必填	说明
`account_id`	路径	string	是	团队的数字 id，和网页地址里的相同，例如 `2025`。

请求体application/json，必填

字段	类型	必填
`git_connection`	object	是
`git_connection.provider`	`gitea` \| `github`	是
`git_connection.name`	string	是

响应

状态	说明	返回
`201`	The connection with its webhook URL and secret	`data`: `GitConnection`
`400`	Malformed request or invalid parameter.	`ProblemDetails`
`403`	Authenticated but not permitted.	`ProblemDetails`
`422`	Validation failed.	`ProblemDetails`

GET`/api/v1/accounts/{account_id}/git_connections/{id}`

参数

参数	位置	类型	必填	说明
`account_id`	路径	string	是	团队的数字 id，和网页地址里的相同，例如 `2025`。
`id`	路径	string (uuid)	是

响应

状态	说明	返回
`200`	The connection	`data`: `GitConnection`
`403`	Authenticated but not permitted.	`ProblemDetails`
`404`	Resource does not exist or has been trashed.	`ProblemDetails`

PUT`/api/v1/accounts/{account_id}/git_connections/{id}`

Same as PATCH

参数

参数	位置	类型	必填	说明
`account_id`	路径	string	是	团队的数字 id，和网页地址里的相同，例如 `2025`。
`id`	路径	string (uuid)	是

请求体application/json，必填

字段	类型	必填
`git_connection`	object	是
`git_connection.name`	string	否
`git_connection.status`	`active` \| `disabled`	否

响应

状态	说明	返回
`200`	The updated connection	`data`: `GitConnection`
`400`	Malformed request or invalid parameter.	`ProblemDetails`
`403`	Authenticated but not permitted.	`ProblemDetails`
`404`	Resource does not exist or has been trashed.	`ProblemDetails`
`422`	Validation failed.	`ProblemDetails`

PATCH`/api/v1/accounts/{account_id}/git_connections/{id}`

Rename, disable or re-enable a connection

A disabled connection answers its webhooks with 404 and keeps the code already linked to tasks.

参数

参数	位置	类型	必填	说明
`account_id`	路径	string	是	团队的数字 id，和网页地址里的相同，例如 `2025`。
`id`	路径	string (uuid)	是

请求体application/json，必填

字段	类型	必填
`git_connection`	object	是
`git_connection.name`	string	否
`git_connection.status`	`active` \| `disabled`	否

响应

状态	说明	返回
`200`	The updated connection	`data`: `GitConnection`
`400`	Malformed request or invalid parameter.	`ProblemDetails`
`403`	Authenticated but not permitted.	`ProblemDetails`
`404`	Resource does not exist or has been trashed.	`ProblemDetails`
`422`	Validation failed.	`ProblemDetails`

DELETE`/api/v1/accounts/{account_id}/git_connections/{id}`

Remove a connection and the code it linked to tasks

参数

参数	位置	类型	必填	说明
`account_id`	路径	string	是	团队的数字 id，和网页地址里的相同，例如 `2025`。
`id`	路径	string (uuid)	是

响应

状态	说明	返回
`200`	Removed (`{ "data": null }`).	`data`: null
`403`	Authenticated but not permitted.	`ProblemDetails`
`404`	Resource does not exist or has been trashed.	`ProblemDetails`

POST`/api/v1/accounts/{account_id}/git_connections/{git_connection_id}/secret`

Issue a new webhook signing secret

Deliveries signed with the previous secret get 401 from now on; update the code host's webhook right away.

参数

参数	位置	类型	必填	说明
`account_id`	路径	string	是	团队的数字 id，和网页地址里的相同，例如 `2025`。
`git_connection_id`	路径	string (uuid)	是

响应

状态	说明	返回
`201`	The connection with its new secret	`data`: `GitConnection`
`403`	Authenticated but not permitted.	`ProblemDetails`
`404`	Resource does not exist or has been trashed.	`ProblemDetails`

GET`/api/v1/accounts/{account_id}/git_connections/{git_connection_id}/deliveries`

Recent webhook deliveries of a connection, newest first

Kept 14 days. Only deliveries with a valid signature for a tracked event (push, pull_request) are listed.

参数

参数	位置	类型	必填	说明
`account_id`	路径	string	是	团队的数字 id，和网页地址里的相同，例如 `2025`。
`git_connection_id`	路径	string (uuid)	是
`page`	查询	integer	否	默认 `1`
`limit`	查询	integer	否	Clamped to 1–100 (default 30).

响应

状态	说明	返回
`200`	Delivery page	`data`: `GitDelivery`[] · `meta`: `PaginationMeta`
`403`	Authenticated but not permitted.	`ProblemDetails`
`404`	Resource does not exist or has been trashed.	`ProblemDetails`

GET`/api/v1/accounts/{account_id}/recordings/{recording_id}/code_references`

Pull requests and commits linked to a task

A pull request is linked when its title or description names the task: its canonical URL (https://qunli.co/<account>/T1042, this team only) or its bare ref ("T1042", "#T1042"; uppercase T and at least three digits, resolved in the connection's team). Its head branch's commits follow it (including commits pushed before it was opened, up to 30 days back); a commit whose own message names the task is linked directly. Pull requests come first (newest opened first), then commits (newest first). Empty for anything without linked code. Guests get 403; trashed recordings and others' drafts 404.

参数

参数	位置	类型	必填	说明
`account_id`	路径	string	是	团队的数字 id，和网页地址里的相同，例如 `2025`。
`recording_id`	路径	string (ref)	是	引用号，例如 `T1042`，大小写不敏感，可带前导 `#`。
`page`	查询	integer	否	默认 `1`
`limit`	查询	integer	否	Clamped to 1–200 (default 100).

响应

状态	说明	返回
`200`	Linked code page	`data`: `CodeReference`[] · `meta`: `PaginationMeta`
`401`	Missing or invalid authentication.	`ProblemDetails`
`403`	Authenticated but not permitted.	`ProblemDetails`
`404`	Resource does not exist or has been trashed.	`ProblemDetails`

数据结构

上面的响应用到的对象。字段的类型是另一个对象时，它也列在这里。

`GitConnection`

字段	类型	必填	说明
`id`	string (uuid)	是
`provider`	`gitea` \| `github`	是
`name`	string	是
`status`	`active` \| `disabled`	是
`webhook_url`	string	是	Payload URL to paste into the code host's webhook.
`secret`	string	是	Webhook secret (HMAC-SHA256 signing key) to paste alongside webhook_url.
`events`	string[]	是	Events to enable on the code host (push, pull_request).
`last_delivery_at`	string (date-time) \| null	是	Last delivery with a valid signature.
`last_event`	string \| null	是
`last_error`	string \| null	是	Last unreadable payload, if any.
`last_error_at`	string (date-time) \| null	是
`creator`	`UserRef`	是
`created_at`	string (date-time)	是
`updated_at`	string (date-time)	是

`GitDelivery`

字段	类型	必填	说明
`id`	string (uuid)	是
`delivery_id`	string	是	The code host's delivery id.
`event`	`push` \| `pull_request`	是
`status`	`pending` \| `processed` \| `ignored` \| `failed`	是
`error`	string \| null	是
`created_at`	string (date-time)	是
`processed_at`	string (date-time) \| null	是

`PaginationMeta`

字段	类型	必填
`page`	integer	是
`limit`	integer	是
`total`	integer	是
`total_pages`	integer	是
`has_next`	boolean	是

`CodeReference`

A pull request (kind pull_request: number … closed_at set, commit fields null) or a commit (kind commit: sha … committed_at set, pull request fields null) linked to a task.

字段	类型	必填	说明
`id`	string (uuid)	是
`kind`	`pull_request` \| `commit`	是
`git_connection`	`GitConnectionRef`	是
`repository`	string	是	Full name, "org/repo".
`url`	string \| null	是	On the code host; may be reachable only inside the team's network.
`author_login`	string \| null	是
`number`	integer \| null	否
`title`	string \| null	否
`state`	`open` \| `closed` \| `merged` \| null	否
`draft`	boolean \| null	否
`head_branch`	string \| null	否
`base_branch`	string \| null	否
`merge_commit_sha`	string \| null	否
`opened_at`	string (date-time) \| null	否
`merged_at`	string (date-time) \| null	否
`closed_at`	string (date-time) \| null	否
`sha`	string \| null	否
`message`	string \| null	否
`branch`	string \| null	否	Branch the commit was first pushed to.
`author_name`	string \| null	否
`committed_at`	string (date-time) \| null	否
`pull_request_number`	integer \| null	否	The linked pull request that brought this commit; null when its own message links the task.
`created_at`	string (date-time)	是

`UserRef`

字段	类型	必填	说明
`id`	string (uuid)	是	User UUID.
`public_id`	string \| null	是	Member ref ("U12") in this account.
`name`	string \| null	是
`avatar_url`	string \| null	是
`kind`	`human` \| `agent` \| `app` \| null	是	null only for an unknown (deleted) user; app is an integration's identity (a code-hosting connection), never a team member.

`GitConnectionRef`

字段	类型	必填
`id`	string (uuid)	是
`provider`	`gitea` \| `github`	是
`name`	string	是

代码托管

GET/api/v1/accounts/{account_id}/git_connections

参数

响应

POST/api/v1/accounts/{account_id}/git_connections

参数

请求体application/json，必填

响应

GET/api/v1/accounts/{account_id}/git_connections/{id}

参数

响应

PUT/api/v1/accounts/{account_id}/git_connections/{id}

参数

请求体application/json，必填

响应

PATCH/api/v1/accounts/{account_id}/git_connections/{id}

参数

请求体application/json，必填

响应

DELETE/api/v1/accounts/{account_id}/git_connections/{id}

参数

响应

POST/api/v1/accounts/{account_id}/git_connections/{git_connection_id}/secret

参数

响应

GET/api/v1/accounts/{account_id}/git_connections/{git_connection_id}/deliveries

参数

响应

GET/api/v1/accounts/{account_id}/recordings/{recording_id}/code_references

参数

响应

数据结构

GitConnection

GitDelivery

PaginationMeta

CodeReference

UserRef

GitConnectionRef

GET`/api/v1/accounts/{account_id}/git_connections`

POST`/api/v1/accounts/{account_id}/git_connections`

GET`/api/v1/accounts/{account_id}/git_connections/{id}`

PUT`/api/v1/accounts/{account_id}/git_connections/{id}`

PATCH`/api/v1/accounts/{account_id}/git_connections/{id}`

DELETE`/api/v1/accounts/{account_id}/git_connections/{id}`

POST`/api/v1/accounts/{account_id}/git_connections/{git_connection_id}/secret`

GET`/api/v1/accounts/{account_id}/git_connections/{git_connection_id}/deliveries`

GET`/api/v1/accounts/{account_id}/recordings/{recording_id}/code_references`

`GitConnection`

`GitDelivery`

`PaginationMeta`

`CodeReference`

`UserRef`

`GitConnectionRef`