调用 Agentic API 操作
签发 OAuth 访问令牌，在公开目录中找到操作，并通过 POST /api/v1/actions/<id> 调用它。
使用场景这项任务
您希望一个自动调用方（智能体或脚本）使用 Trustvice 的某项功能。每项功能都是一个已注册的操作，具有固定的 ID、带类型的输入和相同的响应信封，因此一种请求格式即可覆盖全部操作。
开始之前的准备
- 所需的凭据
- 您还需要准备
- 为您的工作区注册的 OAuth 客户端（
tvc_…ID 及其密钥） curl
- 为您的工作区注册的 OAuth 客户端（
代码从环境变量中读取密钥。请将其保存在 shell 或密钥存储中，切勿写入要提交的文件。操作调用还需要发送 X-Workspace-Id。
步骤
签发访问令牌
使用
client_credentials将 OAuth 客户端的 ID 和密钥换成访问令牌。令牌有效期为一小时（expires_in: 3600），并带有该客户端的权限范围。将其导出为TRUSTVICE_TOKEN。curl -sS -X POST https://api.trustvice.com/api/v1/oauth/token \ -H "Content-Type: application/json" \ -d "{\"grant_type\":\"client_credentials\",\"client_id\":\"tvc_…\",\"client_secret\":\"$TRUSTVICE_CLIENT_SECRET\"}"POST /api/v1/oauth/token { "grant_type": "client_credentials", "client_id": "tvc_…", "client_secret": "…" }找到操作
已注册操作的公开目录位于
GET /api/v1/actions，无需凭据。操作 ID 是分层的：<domain>.<noun>.<verb>。API 参考列出了每个操作的输入架构和权限。curlcurl -sS https://api.trustvice.com/api/v1/actions调用操作
将操作的输入以 JSON 发送到
POST /api/v1/actions/<action-id>，并附上访问令牌和工作区 ID。这里会有意拒绝工作区 API 密钥：API 密钥授予的是工作区访问权限，而不是智能体的意图。curl -sS -X POST https://api.trustvice.com/api/v1/actions/<action-id> \ -H "Authorization: Bearer $TRUSTVICE_TOKEN" \ -H "X-Workspace-Id: ws_…" \ -H "Content-Type: application/json" \ -d '{ … }'POST /api/v1/actions/<action-id> Authorization: Bearer <oauth-access-token> X-Workspace-Id: ws_… Content-Type: application/json { …input fields… }读取信封
先读取
ok。成功时输出在data中；失败时error包含机器可读的code和一句供人阅读的说明。业务层面的404或422是产品给出的答复，而不是传输错误。
内容复制自: /docs/actions
返回的那些内容
每个操作都以相同的信封响应：ok: true 加 data，或 ok: false 加 error 中的代码和消息。
{ "ok": true, "data": { …action output… } }
{ "ok": false, "error": { "code": "not_found", "message": "No such export in this workspace." } }您可以依赖什么
可以依赖
- 错误或缺失的凭据会得到明确的
401 unauthenticated，绝不会出现半认证的请求。 - 缺少权限时返回
403 permission_denied，并准确指出所需的权限。 - 同一个操作通过 REST、MCP 和智能体技能传输调用时，行为完全相同。
不要假定
- 重试是安全的：只有标记为幂等的操作才接受
Idempotency-Key请求头。 - 每个操作在第一次调用时都会执行：破坏性操作和计费操作会先返回
412 confirmation_required。
以上每一条说明都来自本页链接的 Trustvice 文档。如果文档页面写得更详细，以文档为准。
后续步骤
相关的其他示例
确认破坏性操作
处理 412 confirmation_required：签发确认令牌，并带上 X-Trustvice-Confirmation 重新调用。
连接 MCP 客户端
将位于 https://mcp.trustvice.com/mcp 的 Trustvice MCP 服务器添加到 Claude Code、Cursor 或 VS Code。
在浏览器中验证回执
将 Trustvice 签名回执粘贴到 /verify，在您自己的浏览器中检查其 Ed25519 签名。
通过邮件接收新的示例
当我们向实用示例中添加新示例时，会发送一封简短的邮件。不会发送其他任何邮件，而且您可以从任意一封邮件中退订。
从 Agentic API 开始。
每个已注册的操作对应一个 POST 端点，通过 REST 和 MCP 调用时行为相同。文档列出了每个操作的输入和权限。
