AgentWifi API 文档

从 Workspace Key 开始

Endpoint 占位符

示例中的 https://api.example.com 仅为占位 origin。请替换成 Console 显示的部署 endpoint，并保持文档中的 /v1 路径不变。

curl --fail-with-body --silent --show-error 'https://api.example.com/v1/catalog?availableOnly=true&category=web&limit=5' \
  --header 'Authorization: Bearer <YOUR_WORKSPACE_API_KEY>'

只接受 Bearer，不接受 URL 或 Cookie 鉴权

每个 MCP 与 REST 请求都需要 Authorization: Bearer YOUR_WORKSPACE_API_KEY。Session Cookie 仅用于 Console，数据面会拒绝它；query 参数中的 Key 同样会被拒绝。

明文 Key 只在创建时返回一次。不要把它放进 URL、Prompt、聊天、截图、源码、shell history 或日志；一旦可能泄露，立即撤销。

远程 Streamable HTTP MCP

MCP endpoint 接受 POST，支持 initialize、tools/list 与 tools/call。首版 transport 无状态。

初始化连接

curl --fail-with-body --silent --show-error 'https://api.example.com/v1/mcp' \
  --header 'Authorization: Bearer <YOUR_WORKSPACE_API_KEY>' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2025-03-26' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"agentwifi-docs-smoke","version":"1.0.0"}}}'

五个已发布 MCP tools

Tool	服务端能力	输入合同
`list_tools` List published tools from the current catalog snapshot	`catalog:read`	`prefix, query, category, provider, source, availability, availableOnly, maxCreditsPerCall, cursor, limit`
`find_tools` Find published tools using semantic and keyword search	`catalog:read`	`query, limit`
`describe_tool` Return the published contract for one canonical tool	`catalog:read`	`canonicalName, version`
`execute_tool` Execute one published canonical tool contract	`tools:execute`	`canonicalName, version, params, maxCredits, idempotencyKey`
`account` Return the current workspace balance and provider health	`account:read`	`verificationCode`

tools/list JSON-RPC payload

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

REST endpoints

REST 是 MCP 共用 Catalog、Account、Execute application service 的 HTTP adapter。未知或重复 query 参数以及 execute body 多余字段都会校验失败。

方法与路径	服务端能力	用途	参数
`GET /v1/catalog`	`catalog:read`	List the complete published catalog with stable pagination and facets.	`prefix` — Canonical-name prefix. `query` — Full-text catalog filter. `category` — Exact category filter. `provider` — Exact provider slug filter. `source` — Exact data-source filter. `availability` — available, unavailable, or deprecated. `availableOnly` — true returns only entries with a published executable route. `maxCreditsPerCall` — Maximum per-call cost as canonical decimal credits. `cursor` — Opaque cursor returned by the previous page. `limit` — 1-100; defaults to 20.
`GET /v1/catalog/search`	`catalog:read`	Find published tools using semantic search with keyword fallback.	`query` * — Search text, 1-500 characters. `limit` — 1-50; defaults to 10.
`GET /v1/catalog/:canonicalName`	`catalog:read`	Describe one published canonical tool contract.	`version` — Exact published version.
`GET /v1/account`	`account:read`	Read the authenticated Workspace balance and provider-health summary.	无
`POST /v1/execute`	`tools:execute`	Execute one available published tool through the shared data plane.	`canonicalName, version, params, maxCredits, idempotencyKey`

已做合同校验的示例

查找工具

curl --fail-with-body --silent --show-error 'https://api.example.com/v1/catalog/search?query=latest%20AI%20news&limit=3' \
  --header 'Authorization: Bearer <YOUR_WORKSPACE_API_KEY>'

使用重放 Key 执行

curl --fail-with-body --silent --show-error 'https://api.example.com/v1/execute' \
  --header 'Authorization: Bearer <YOUR_WORKSPACE_API_KEY>' \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{"canonicalName":"web.search","params":{"query":"latest AI news"},"maxCredits":"1","idempotencyKey":"docs-web-search-001"}'

目录事实稳定，并默认 fail closed

Catalog 返回完整已发布 snapshot。availability 描述版本化产品状态；executionAvailable 还要求至少一条已启用发布路由。只有两者均可用的条目才能执行。

把 nextCursor 当成不透明值。它绑定 snapshot 及包括 availableOnly 在内的全部 filter；换 filter 重放会被拒绝。cursor 为空表示最后一页。

需要立即可执行的条目时使用 availableOnly=true。Provider health 不会改写 Catalog availability；即使绕过 UI，unavailable 或 deprecated 条目仍不可执行。

Account 读取不可变 Ledger 余额

GET /v1/account 与 MCP account tool 返回 API Key 所属 Workspace 和余额。availableCredits 可用于预留，reservedCredits 表示当前占用，totalCredits 是两者之和。Credits 始终使用规范十进制字符串，不使用浮点数。

执行先预留上限，再按真实使用结算或释放预留。Ledger 是唯一余额事实；Provider 输出或客户端统计不能创建或改写 Credits。

安全重放，明确取消

幂等

execute 的 idempotencyKey 长度为 8-255，只能为同一个逻辑请求复用。它跨 MCP/REST 共用：从任一传输重试都会返回同一执行事实，不会重复调用 Provider 或扣费。

Deadline 与取消

每次 execute 在最多两个 Provider attempt 之间共用一个服务端 deadline。客户端断开或 AbortSignal 会取消工作；能返回响应时 REST 用 HTTP 499 + CANCELLED，deadline 到期用 HTTP 504。终态都会释放 permit 与活动预留。

速率与并发

全部已鉴权请求消耗 per-key 与 per-Workspace rate capacity。Execute 还使用 per-key/per-Workspace concurrency 及 Provider bulkhead。饱和时返回 HTTP 429、RATE_LIMITED、retryAfterMs、scope 与整数秒 Retry-After。Retry-After 只是退避提示，不是排队承诺。

当前 rate、concurrency 与 Provider bulkhead backend 均在内存中，只保证单个 API 进程内原子。多实例部署前必须替换共享原子 backend，才能声称全局限制。

稳定错误与请求关联

路由、鉴权、校验、可用性和 admission 失败使用下方 envelope，并在 X-Request-Id 返回相同 requestId。Execute 失败返回 status=failed 的类型化 ExecutionResult，并包含相同稳定错误元数据。

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request rate limit exceeded",
    "retryAfterMs": 1000,
    "scope": "api_key_rate"
  },
  "requestId": "req_example_01"
}

错误码	HTTP	重试
`VALIDATION_ERROR`	400	不可盲目重试
`UNAUTHENTICATED`	401	不可盲目重试
`INSUFFICIENT_CREDITS`	402	不可盲目重试
`FORBIDDEN`	403	不可盲目重试
`NOT_FOUND`	404	不可盲目重试
`TOOL_UNAVAILABLE`	409	不可盲目重试
`RATE_LIMITED`	429	按策略重试
`CANCELLED`	499	按策略重试
`UPSTREAM_UNAVAILABLE`	502	按策略重试
`CATALOG_UNAVAILABLE`	503	按策略重试
`DEADLINE_EXCEEDED`	504	按策略重试
`UPSTREAM_TIMEOUT`	504	按策略重试
`INTERNAL_ERROR`	500	不可盲目重试

真实 verified targets，不是愿望清单

此矩阵由版本化 client registry 生成。Available 只表示至少一个精确 target/method 有 PASS 证据，不覆盖未列出的系统、架构、方式或未来客户端版本。

Windows 已延期且不可用。Cursor、OpenClaw、Qoder、WorkBuddy 没有 verified target。Prompt install 仅验证了 registry 固定版本下的 Codex macOS arm64，不得复用到其他组合。

Agent	状态	已验证 target 与方式
Codex `codex`	仅列出范围可用	`macos/arm64` — 脚本 + Prompt `macos/x64` — 脚本 `linux/arm64` — 脚本 `linux/x64` — 脚本
Claude Code `claude-code`	仅列出范围可用	`macos/arm64` — 脚本 `macos/x64` — 脚本 `linux/arm64` — 脚本 `linux/x64` — 脚本
Cursor `cursor`	不可用 / 已延期	没有 verified target
Gemini CLI `gemini-cli`	仅列出范围可用	`macos/arm64` — 脚本 `macos/x64` — 脚本 `linux/arm64` — 脚本 `linux/x64` — 脚本
OpenCode `opencode`	仅列出范围可用	`macos/arm64` — 脚本 `macos/x64` — 脚本 `linux/arm64` — 脚本 `linux/x64` — 脚本
OpenClaw `openclaw`	不可用 / 已延期	没有 verified target
Hermes `hermes`	仅列出范围可用	`macos/arm64` — 脚本 `macos/x64` — 脚本 `linux/arm64` — 脚本 `linux/x64` — 脚本
Qoder `qoder`	不可用 / 已延期	没有 verified target
WorkBuddy `workbuddy`	不可用 / 已延期	没有 verified target
Kimi CLI `kimi-cli`	仅列出范围可用	`macos/arm64` — 脚本 `macos/x64` — 脚本 `linux/arm64` — 脚本 `linux/x64` — 脚本

安装命令与 authenticated account probe 请使用 Console Quick Start；它只暴露当前 target 已验证的方式。

一套目录、一套账户、一条执行数据面