Agent API

Run an endpoint

Call any endpoint by provider, endpoint and structured input. Pikeway builds the URL, query and body, runs it through the gateway with normal billing, and wraps the result in a run object. Synchronous by default; long jobs can run in the background.

POST/v1/run

Authentication

Authorization: Bearer pk-…. The call is billed exactly like /gw: only successful (2xx) upstream responses are charged.

Body

providerstringrequired

API slug.

endpointstringrequired

Path template (/users/{id}), a concrete path, or "POST /path". Same matching as /v1/inspect.

methodstring

Optional; GET is preferred when a path has several methods.

inputobject

The endpoint's input, in one of two forms (see below). Defaults to {}.

asyncboolean

Run in the background and return 202 immediately. Endpoints the provider marked as long-running tasks are always async.

timeoutSecondsinteger

Async only. Default 300, max 900.

Input formats

Structured: any of pathParams, queryParams, body, matching the schemas from /v1/inspect. Array values in queryParams become repeated parameters.

json

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

Flat: a single object. Keys that match path placeholders go into the path; the rest become query parameters for GET/DELETE/HEAD, or the JSON body for other methods.

json

{ "address": "So11111111111111111111111111111111111111112" }

Required path and query parameters are checked first; if any is missing you get 400 with the list and the full input schema, before anything is called or charged.

Request

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" }
  }'

Response

The HTTP status of a synchronous run is the provider's status. status is COMPLETED for responses below 400 and FAILED otherwise; output is the provider's body (parsed JSON, or a string).

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'" }
}

Fields

runIdstring

Same as the X-Pikeway-Call-Id of the underlying call. Use it with GET /v1/runs/{runId}.

statusCOMPLETED | FAILED

Based on the provider's HTTP status.

outputany

The provider's response body.

providerResponseobject

httpStatus, contentType, and cache (HIT, MISS or empty).

price · costobject

The list price, and what you were actually charged (0 when not billed).

durationMsinteger

Total time of the run.

Response headers X-Pikeway-Call-Id, X-Pikeway-Cost, X-Pikeway-Cache and X-Pikeway-Byok are copied from the underlying call.

If the gateway rejects the call before it reaches the provider (no key, insufficient balance, rate limit…), there is no run object: the gateway's response is returned unchanged, e.g. {"error": "insufficient balance", "statusCode": 402}.

Async runs

Send "async": true to get 202 Accepted right away. The call runs in the background through the same gateway flow; poll GET /v1/runs/{runId} until status is no longer QUEUED or RUNNING. Async runs need a key, are kept for 7 days, and are not charged if they time out, are stopped or fail.

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'"
  }
}

Async run ids start with run_. Final statuses: COMPLETED, FAILED, STOPPED, TIMED_OUT. Output is stored up to 2 MB.

Errors

400 missing required input (see below) · 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 bring-your-own-key API without your key: {"code": 403, "message": "…", "byok": true, "signupUrl": "…"}
404 unknown provider: … · unknown endpoint … on … (with available)
405 use POST
Gateway rejections (402, 429, 503…) in the gateway shape.

400 Bad Request

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