Overview

Base URL

https://gw.pikeway.ai

All paths in this reference are relative to the gateway base URL. The main route families:

• /gw/{slug}/{path} calls any marketplace API (any method), billed per successful call.
• /cap/{slug} one action served by several providers, with automatic failover.
• /ai/v1/… OpenAI- and Anthropic-compatible LLM endpoints, billed per token.
• /v1/… the Agent API: discover, inspect, run, runs, wallet.
• /mock/{slug}/{path} free example responses, no key, never hits the upstream.
• /ws/{slug}/{path} WebSocket proxy (key required; see the WebSocket guide).

Authentication

API key

Create a key in Console → Keys. Keys start with pk-. Send it as a Bearer token; the X-API-Key header is accepted as well.

curl https://gw.pikeway.ai/v1/auth/whoami \
  -H "Authorization: Bearer pk-..."

# equivalent
curl https://gw.pikeway.ai/v1/auth/whoami -H "X-API-Key: pk-..."

The gateway strips its own auth headers before forwarding, so your Pikeway key never reaches the upstream provider. Each key can carry its own restrictions, set in the console:

• Spend limit: once reached, paid calls return 402 api key spend limit reached.
• IP allowlist (CIDR): other IPs get 403 client IP not allowed for this API key.
• Expiry: an expired key behaves like a revoked one (401 invalid or revoked API key).

Browser keys

A browser key is a key with an origin allowlist. The gateway checks the Origin header (falling back to Referer) against the list; entries are hostnames and *.example.com matches subdomains. Requests with no Origin/Referer, such as server-side calls, are rejected with 403 request origin not allowed for this API key. See Browser keys.

Endpoints that need no key

POST /v1/discover, POST /v1/inspect, GET /v1/examples, GET /v1/rankings, GET /ai/v1/models and /mock/… are free and work without a key.

Billing and response headers

Paid calls are charged only when they succeed. On /gw that means the upstream answered 2xx (and, where the provider configured it, the body's business code says success). Upstream errors, network failures, timeouts and every gateway-side rejection are free. Before forwarding, the gateway holds the price on your balance and releases it if the call is not billed.

Browser code can read them through CORS, except X-Pikeway-Byok, X-Pikeway-Upstream-Attempts and X-Pikeway-Upstream-Error, which are not in the exposed list.

Requests and responses

• Pass-through. /gw and /cap return the provider's status code, headers and body unchanged (plus the headers above). Request bodies, query strings and headers are forwarded as-is, minus Pikeway's auth headers.
• Agent API. /v1/* takes and returns JSON. Prices and costs are objects like {"value": 0.001, "currency": "USD"}; timestamps are RFC 3339 in UTC.
• Idempotency. Send Idempotency-Key (up to 255 characters) on a paid /gw call and the gateway forwards and charges it at most once per key. Reusing the key returns 409.
• Errors. Gateway errors are JSON with error + statusCode; Agent API errors use code + message. See Errors.

Pagination

GET /v1/runs and GET /v1/wallet/activities use cursor pagination, newest first. Pass limit (default 20, max 100) and the cursor from the previous page. The response is {"items": [...], "cursor": "..."}; cursor is null on the last page. Cursors are opaque strings.

curl "https://gw.pikeway.ai/v1/runs?limit=50" -H "Authorization: Bearer pk-..."
curl "https://gw.pikeway.ai/v1/runs?limit=50&cursor=MjAyNi0xMC0yNFQwOToxMjo..." -H "Authorization: Bearer pk-..."

Endpoints

Gateway

AI gateway

Agent API

Other public endpoints