开发者

API：基础

VentionDesk API 与界面使用的是同一个 API。用于自动化——Claude、自己的脚本、CI——时，使用 API 密钥 登录。所有 URL 以 https://api.ventiondesk.com 开头；所有请求体和响应均为 UTF-8 编码的 JSON。

使用 API 密钥登录

所有者在 设置 › API 密钥 › “新密钥” 中创建密钥。密钥只以明文显示一次。

每个请求都以 Bearer 令牌的形式携带它：

curl https://api.ventiondesk.com/v1/tasks?status=todo \
  -H "Authorization: Bearer vd_live_…"

没有单独的兑换端点：VentionDesk 通过前缀识别密钥，在每个请求中检查它（是否已撤销？是否已过期？），然后以该密钥所属账户的会话进行处理。因此，适用于人员的数据库规则同样适用于密钥——它只能看到其权限范围允许的内容。

前缀	类型	用途
`vd_live_`	代理	领取任务并反馈、读取项目、撰写笔记、MCP
`vd_intake_`	入口	仅提交工单（`POST /v1/intake/tickets`），参见工单入口
`vd_pub_`	公开项目密钥	不是登录密钥：它位于表单和 Web 应用中，只能向一个项目发送报告

除密钥外，通过 OAuth 连接的 AI 应用的登录凭据也可以作为 Bearer 令牌使用。它视同代理密钥，具有该人员在授权时选择的权限和项目——绝不具有该人员自身的权限——并在断开连接后立即失效。

代理密钥是一个独立的账户，角色为代理。它适用于在 API 参考中标有权限范围的端点，以及 GET /v1/me 和代理运行。要求“所有者”或“所有者和员工”的端点由 Web 界面以已登录人员的会话调用；对 API 密钥返回 403。

代理密钥可以做什么，由其权限范围决定：

权限范围只出现在真正使用它的端点上——API 参考为每个端点注明了权限范围。deployments:read 不出现在任何端点上：它通过镜像的提交、拉取请求和部署的数据库规则生效。

密钥适用于 所有项目 或 部分项目。绑定的密钥只能看到其项目的数据——并且有意 看不到任何没有项目的数据，例如尚未分配给项目的工单。对于其项目之外的数据行，API 返回 404 或 403。入口密钥始终只绑定一个项目。

更改范围无需新密钥。 所有者可在密钥列表中的“权限”下调整权限范围和项目；下一次请求即按新的范围处理。已撤销 或已过期的密钥在下一次请求时即被拒绝。

每个错误响应的结构都相同：

{ "ok": false, "error": "Diese Aufgabe gibt es nicht.", "code": "not_found" }

error 是面向人阅读的句子（语言取自 Accept-Language，未提供该请求头时为德语），code 是面向程序的稳定英文值。常见响应：

状态	`code`	含义
400	`validation_error`	查询参数或路径参数无效
401	`unauthorized`	没有密钥或密钥无效
403	`forbidden`	角色、权限范围或项目不满足要求
404	`not_found`	不存在——或对该密钥不存在
409	`conflict`	状态不匹配，例如任务已被认领
413	`payload_too_large`	请求体超过 1 MB
422	`validation_error`	请求体无效；`error` 以 `字段: 消息` 的形式指出第一个问题字段
423	`betrieb_gesperrt`	工作区已停用，例如因为没有正在生效的付费订阅
429	`rate_limited`	请求过多，请稍候
500	`internal_error`	VentionDesk 端出错

每个响应都在 x-request-id 响应头中带有一个 ID。如果自己发送一个（最多 128 个字符），则使用该 ID。出现问题时，请将它提供给支持人员。

按分钟计数，按密钥或 IP 地址统计：

超过限制时，API 返回 429 和 rate_limited；RateLimit 和 RateLimit-Policy 响应头给出当前计数和限制。

列表端点通过查询参数筛选，并用 limit 限制数量；没有基于游标或偏移量的分页。示例：

GET /v1/tasks?projectSlug=shop&status=todo&claimable=true&limit=20——当前可以领取的任务。
GET /v1/projects?status=active——活跃的项目。

端点支持哪些参数、返回哪些字段，列在 API 参考中——读取自 VentionDesk 用于检查请求的同一份合约。

GET /v1/tasks?claimable=true——有什么要做？
POST /v1/tasks/:id/claim——以原子方式认领任务。两次运行绝不会拿到同一个任务。
工作；期间以 "state": "arbeitet" 调用 POST /v1/tasks/:id/result，作为存活信号。
以 kontrolle、frage、master、blockiert 或 erledigt 调用 POST /v1/tasks/:id/result——使用 kontrolle 和 erledigt 时，在 evidence 中附上证据。

不想自己实现这些的话，请使用 Claude 与 MCP。