参考
API 参考
基础 URL 为 https://api.commandagi.com。所有请求都携带一个 bearer API 密钥；所有请求体和响应都是 JSON。
会话与机器
一个会话就是一次运行。一个智能体会话（POST /threads）由一个 AI 驱动；一台机器（POST /device-threads）没有智能体——由你驾驶。两者接入的是同一批设备。
POST
/app/threads创建一个智能体会话（由一个 AI 驱动）。POST
/embodiment-threads创建一台无智能体的机器（由你驾驶——机器人、仿真、计算机）。GET
/me/embodiment-threads你正在运行的机器。POST
/app/threads/:id/computers接入一台平台计算机（云端 Ubuntu 桌面）。POST
/app/threads/:id/robots接入一个 3D 仿真或一台物理机器人。POST
/app/threads/:id/connect-embodiment连接你自己的机器（免费，自带设备；kind: computer|robot|simulation）。POST
/app/threads/:id/rent-embodiment把一台已挂牌的设备租入该会话。POST
/app/threads/:id/embodiments/:embodimentId/snapshot为一台设备的状态拍摄快照，以便之后分叉。POST
/app/threads/:id/exec暂停或恢复该会话（会话永不结束；设备会在闲置时释放）。实时——数据流与控制（WebSocket）
连接到一个会话的实时通道以接收传感器帧并发送控制动作——机器人/仿真使用摄像头通道（cam-head，JPEG），计算机使用屏幕通道（screen，PNG）。完整流程 + Python SDK 见机器人与仿真。
websocket
// wss://api.commandagi.com/rt/thread/{threadId}?role=owner&token={cagi_key}
// Control needs &token=<your API key> (you must own the thread); public threads are view-only without one.
// There is no claim to make first — send a control op and it lands.
← { "t": "frame", "embodimentId": "…", "channelId": "cam-head", "url": "data:image/jpeg;base64,…" }
→ { "t": "control", "embodimentId": "…", "action": "move", "payload": { "speed": 0.8 } }机器人/仿真动作：move、back、turn、stop、reset。计算机动作：click、type、key、move、scroll。
商品、容量与积分
GET
/offerings面向用户的商品目录，带价格。GET
/capacity每个资源池的可用性 + 商品信息。GET
/me/credits你当前的积分余额。GET
/me/credits/history只追加的支出/授予账本。市场——挂牌与购买
GET
/listings浏览活跃的挂牌（按类型/类别过滤）。POST
/listings创建一份挂牌。GET
/listings/:id挂牌详情。PATCH
/listings/:id更新 / 激活 / 下架。POST
/listings/:id/purchase购买访问权（预付费；需要 Idempotency-Key）。GET
/me/purchases你的购买记录。托管与租用
POST
/rental-embodiments注册你的硬件；获取待机命令。GET
/me/rental-embodiments你已注册的设备 + 在线状态。GET
/rental-embodiments/:id/poll待机运行时轮询（心跳 + 命令）。收益与打款
GET
/me/earnings可支付余额、历史记录、账户状态。POST
/me/payouts请求提现已释放的收益。预订
GET
/listings/:id/availability时间窗口 + 现有预订。POST
/listings/:id/reservations预订一个未来的时间窗口（保证金已锁定）。DELETE
/reservations/:id取消（按政策退款）。撮合市场
GET
/market/:resourceClass实时订单簿、成交记录、图表、信号。POST
/market/:resourceClass/orders发布一笔出价或要价（geo、job、convenience 均为可选）。POST
/market/:resourceClass/orders/:orderId/accept供给方一键接受一笔定位出价。DELETE
/market/:resourceClass/orders/:orderId取消一笔订单。定位工作与在场状态
GET
/jobs/nearby某个位置附近的定位工作（已锚定的出价）：?lat=&lng=&radiusM=&class=®ion=。GET
/me/presence你的供给方在场状态。POST
/me/presence上线：位置、服务半径、类别、是否通知。DELETE
/me/presence下线。GET
/me/push-tokens你已注册的推送令牌。POST
/me/push-tokens注册一个推送令牌，以便在附近出现工作时唤醒你。DELETE
/me/push-tokens/:id移除一个推送令牌。智能体经济互操作性（A2A · x402 · AP2）
通过开放标准发现、支付并授权仲裁/预言机原语——无需定制集成。评估器以一个 A2A 智能体的形式发布；仲裁通过 x402 按次计价（在 Solana 上以 USDC 计）；支出可以用一份 AP2 Cart Mandate 来授权。
GET
/.well-known/agent-card.jsonA2A AgentCard——该评估器/预言机的仲裁技能 + 支付端点。POST
/arbitratex402 按次付费。请求体 {spec, deliverable} → 裁决 + 证据根 + 承诺。在 X-PAYMENT 结算之前返回带 PaymentRequirements 的 402。POST
/ap2/cart-mandate构建一份已签名的 AP2 Cart Mandate，用以授权一笔仲裁/托管支出。GET
/reserves公开的储备金证明——积分锚定关系，是被证明的而非被宣称的（汇总数据，不含个人身份信息）。