Agent API

调用端点

用 provider、endpoint 和结构化输入调用任意端点。Pikeway 负责拼出 URL、查询参数和 body,经网关按正常计费流程执行,并把结果包装成一个 run 对象。默认同步;耗时任务可在后台运行。

POST/v1/run

鉴权

Authorization: Bearer pk-…。计费与 /gw 完全一致:只有上游成功(2xx)的响应才扣费。

Body

providerstring必填

API slug。

endpointstring必填

路径模板(/users/{id})、具体路径或 "POST /path"。匹配规则与 /v1/inspect 相同。

methodstring

可选;同一路径有多个方法时优先 GET。

inputobject

端点的输入,两种写法任选(见下文)。默认为 {}。

asyncboolean

在后台运行并立即返回 202。提供方标记为长任务的端点总是异步执行。

timeoutSecondsinteger

仅异步。默认 300,最大 900。

input 的两种写法

结构化:包含 pathParams、queryParams、body 中的任意几个,与 /v1/inspect 返回的 schema 对应。queryParams 中的数组值会变成重复参数。

json

{ "pathParams": { "id": "42" }, "queryParams": { "limit": 10 }, "body": { "...": "..." } }

扁平:一个普通对象。与路径占位符同名的键填入路径;其余键在 GET/DELETE/HEAD 时作为查询参数,其他方法时作为 JSON body。

json

{ "address": "So11111111111111111111111111111111111111112" }

会先检查必填的路径和查询参数;缺失时直接返回 400,带缺失列表和完整输入 schema,不会调用也不会扣费。

请求示例

bash

curl -X POST https://gw.pikeway.ai/v1/run \
  -H "Authorization: Bearer $PIKEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "birdeye",
    "endpoint": "/defi/price",
    "input": { "address": "So11111111111111111111111111111111111111112" }
  }'

响应

同步运行的 HTTP 状态码就是提供方的状态码。响应码低于 400 时 status 为 COMPLETED,否则为 FAILED;output 是提供方的 body(解析后的 JSON,或字符串)。

200 OK

{
  "runId": "0192f6b0-5e2a-7d40-b1c3-8f9e2a4d6c11",
  "provider": "birdeye",
  "endpoint": "/defi/price",
  "method": "GET",
  "status": "COMPLETED",
  "output": { "success": true, "data": { "value": 172.41, "updateUnixTime": 1761297120 } },
  "providerResponse": { "httpStatus": 200, "contentType": "application/json", "cache": "" },
  "price": { "type": "PER_CALL", "amount": { "value": 0.001, "currency": "USD" }, "notes": ["charged only when the upstream call succeeds (HTTP 2xx)"] },
  "cost": { "value": 0.001, "currency": "USD" },
  "durationMs": 214,
  "hints": { "get": "curl -s https://gw.pikeway.ai/v1/runs/0192f6b0-5e2a-7d40-b1c3-8f9e2a4d6c11 -H 'Authorization: Bearer $PIKEWAY_API_KEY'" }
}

字段

runIdstring

与底层调用的 X-Pikeway-Call-Id 相同,可用于 GET /v1/runs/{runId}。

statusCOMPLETED | FAILED

依据提供方的 HTTP 状态码。

outputany

提供方的响应 body。

providerResponseobject

httpStatus、contentType 以及 cache(HIT、MISS 或空)。

price · costobject

标价,以及实际扣费(未计费时为 0)。

durationMsinteger

本次运行的总耗时。

响应头 X-Pikeway-Call-Id、X-Pikeway-Cost、X-Pikeway-Cache 和 X-Pikeway-Byok 从底层调用复制过来。

如果网关在请求到达提供方之前就拒绝了(无 key、余额不足、限流……),就不会有 run 对象,而是原样返回网关的响应,例如 {"error": "insufficient balance", "statusCode": 402}。

异步运行

传 "async": true 会立即得到 202 Accepted。调用在后台按同样的网关流程执行;轮询 GET /v1/runs/{runId},直到 status 不再是 QUEUED 或 RUNNING。异步运行需要 key,保留 7 天;超时、被停止或失败都不扣费。

bash

curl -X POST https://gw.pikeway.ai/v1/run \
  -H "Authorization: Bearer $PIKEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "birdeye", "endpoint": "/defi/price", "input": {"address": "So111…"}, "async": true, "timeoutSeconds": 120}'

202 Accepted

{
  "runId": "run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87",
  "status": "QUEUED",
  "provider": "birdeye",
  "endpoint": "/defi/price",
  "method": "GET",
  "timeoutSeconds": 120,
  "price": { "type": "PER_CALL", "amount": { "value": 0.001, "currency": "USD" }, "notes": ["…"] },
  "pollUrl": "https://gw.pikeway.ai/v1/runs/run_5f0c2b7e9a4d4e1b8c3a6f2d1e0b9a87",
  "hints": {
    "get": "curl -s https://gw.pikeway.ai/v1/runs/run_5f0c… -H 'Authorization: Bearer $PIKEWAY_API_KEY'",
    "stop": "curl -s -X POST https://gw.pikeway.ai/v1/runs/run_5f0c…/stop -H 'Authorization: Bearer $PIKEWAY_API_KEY'"
  }
}

异步运行的 id 以 run_ 开头。最终状态:COMPLETED、FAILED、STOPPED、TIMED_OUT。输出最多保存 2 MB。

错误

400 missing required input (见下) · provider and endpoint are required (see POST /v1/discover) · body must be JSON
400 async runs need an API key (x402 pays per synchronous run)
401 missing API key (Authorization: Bearer pk-...) · invalid or revoked API key
403 自带 key 的 API 但你没有配置 key:{"code": 403, "message": "…", "byok": true, "signupUrl": "…"}
404 unknown provider: … · unknown endpoint … on … (带 available)
405 use POST
网关层拒绝(402、429、503……),格式见网关错误格式。

400 Bad Request

{
  "code": 400,
  "message": "missing required input",
  "missing": ["queryParams.address"],
  "input": { "queryParams": { "type": "object", "properties": { "address": { "type": "string" } }, "required": ["address"] } }
}