# Apiosk Gateway

> Apiosk is the comparison layer for agentic commerce. Listings are grouped by the job they perform, so an agent that needs a task done gets every provider that can do it in one call, priced side by side, with an input mapping that makes the offers substitutable. Three chained endpoints do the comparing, and none of them charges anything: GET /v1/discover (what can perform this task, with stable candidate ids), GET /v1/compare (how those candidates perform against your requirements, scored 0-100 with the weights and per-dimension contributions that produced the number, so it can be recomputed rather than trusted) and GET /v1/decide (one provider back, the rule that picked it, every rejection with the constraint that caused it, and the runners-up in order). Browse the jobs with GET /v1/capabilities; get the candidates for one, cheapest first, with GET /v1/capabilities/{slug}. The call you pick is paid per request over x402 (HTTP 402 + USDC), with no accounts, API keys or SDKs. Describe a need in plain words at GET /v1/search and get the providers ranked. Price, settlement rail and input compatibility are compared for every offer; measured latency and success rate are published for the listings Apiosk has proxied enough calls of, and explicitly absent for the rest. Result quality is not measured anywhere.

The gateway is a transparent reverse proxy. Every listed API is reachable at https://gateway.apiosk.com/{api_slug}/{path}. Free endpoints forward immediately; paid endpoints return `402 Payment Required` (x402 v2) with a base64 `PAYMENT-REQUIRED` header plus a JSON body until a valid payment proof is supplied.

## The comparison layer: discover, compare, decide

A provider's own API can tell you its price. It cannot tell you how it compares to the four alternatives, and it has no reason to. These three endpoints answer that, they chain, and none of them charges anything:

1. `GET https://gateway.apiosk.com/v1/discover?q=read+a+web+page` - what can perform this task, anywhere? Returns a candidate set, each with a stable `candidate_id`, AND a separate `external_candidates` block: the wider x402 ecosystem searched live under several phrasings of the same need. The external hits are unreviewed, unmeasured and not settleable here, so they carry no `candidate_id` and cannot be compared — they are returned anyway, because an agent that needs the job done would rather hear "nobody reviewed this, here it is" than "no results". `include_external=false` returns the reviewed catalogue alone.
2. `GET https://gateway.apiosk.com/v1/compare?candidates=<id>,<id>` - how do they perform against your requirements? Price, measured latency, measured success rate and input compatibility side by side, each scored 0-100.
3. `GET https://gateway.apiosk.com/v1/decide?candidates=<id>,<id>` - which one should you use? One provider back, plus the rule that picked it, every rejected candidate with the exact constraint that removed it, and the runners-up in order so you can overrule it in one read.

State your requirements once and pass the same ones down the chain: `max_price`, `max_latency_ms`, `min_reliability` (0..1 or 0..100), `settlement=apiosk|direct`, `require_all_inputs`, `optimize_for=price|latency|reliability|balanced`. Any step also accepts `q=` or `capability=` directly if you want to skip ahead.

Carrying the candidate ids forward is what makes the set you compared provably the set you discovered. Without them each step re-derives the match, and the decision cannot be attributed to a menu.

On the score: it is 0-100 relative to the candidates in THAT comparison - the cheapest scores 1 on price, the dearest 0 - so it is meaningful within a set and meaningless across sets. It is never returned alone. Every response carries the weights that produced it and each candidate's contribution per dimension, because a score you can recompute is an argument and one you cannot is an advertisement. Dimensions Apiosk has not measured for a candidate are dropped from the weighting and named in `not_scored`, never scored zero: zero would rank a provider Apiosk has never proxied below one it has measured badly, which says more about our coverage than about them. Asking for `optimize_for=latency` or `reliability` sorts measured candidates above unmeasured ones; setting a hard `max_latency_ms` or `min_reliability` rejects unmeasured ones outright, because a floor cannot be met by a claim.

The decision is recorded end to end - discovered, considered, filtered, ranked, selected, rejected - and the response carries an outcome URL to report back to. A vendor sees only the transactions it wins. This sees the choice.

## Discovery

- API catalog (JSON): https://gateway.apiosk.com/v1/apis - every active, verified listing. Each item is already complete: provider identity, category, pricing, listing_metadata, operations[] and endpoints[] (method, path, full_url, price_usd, payment_required, request/response schemas and examples, query_params, headers, per-parameter pricing_rules, documentation_markdown, external docs + OpenAPI links).
- Catalog filters: search, category, tag, listing_type, min_price, max_price, created_after, created_before, include_test, sort (name|price|newest), order (asc|desc), limit (1..500, default 500), offset.
- One API in full: https://gateway.apiosk.com/v1/apis/{slug} - the same shape plus long_description, example_usage, authentication notes and, for federated listings, the provider's own x402 resources.
- Compare before you buy: https://gateway.apiosk.com/v1/discover -> /v1/compare -> /v1/decide, the comparison layer described above. Use this when more than one provider can do the job, which is most of the time.
- Let Apiosk choose: https://gateway.apiosk.com/v1/select?q=read+a+web+page&max_price=0.05 - one provider back, with the rule that picked it, every rejected candidate and the constraint that removed it, and the runners-up in order so you can overrule it in one read. Hard constraints: max_price, max_latency_ms, min_success_rate, settlement=apiosk|direct, require_all_inputs, include_unreliable. A latency or reliability floor rejects unmeasured providers rather than assuming they meet it, and a listing measured below 50% success is held back whether or not you set a floor - named in the rejections, and reachable with include_unreliable=true.
- Start here if you have a need but no slug: https://gateway.apiosk.com/v1/search?q=financial+investor+news - describe the job in plain words and get the matching capabilities with their providers ranked. prefer=cheapest (default), fastest or most_reliable; max_price binds a budget; include_external=1 also searches the wider x402 ecosystem. Latency and success rate are real measurements where Apiosk has proxied enough calls, and explicitly absent where it has not.
- Capabilities (JSON): https://gateway.apiosk.com/v1/capabilities - the same catalog grouped by the task to be done instead of by seller. One capability lists every provider that can perform it, with price, call target and an input mapping that makes the offers substitutable. Compared: price, settlement rail, input compatibility. NOT measured yet: latency, reliability, result quality, provider terms.
- Candidates for one task: https://gateway.apiosk.com/v1/capabilities/{capability_slug} - ordered by price ascending by default (no managed-first preference on this surface); pass sort=managed_first for the catalog's ordering, max_price to bind a budget.
- Report a decision: POST https://gateway.apiosk.com/v1/decisions with {"comparison_id", "capability", "chosen_api_slug", optional "reason", "policy", "rejected"}. Free and unauthenticated. The comparison_id comes from the capability response; quoting it ties your choice to the menu it was made from.
- Report an outcome: POST https://gateway.apiosk.com/v1/decisions/{decision_id}/outcome with {"status": "success|error|timeout|abandoned", optional "latency_ms", "http_status", "satisfied"}. This is the only place any result-quality signal exists.
- Providers: https://gateway.apiosk.com/v1/providers - everyone publishing here, most listings first (name, username, avatar, bio, sector, api_count). Supports search.
- One provider's listings: https://gateway.apiosk.com/v1/providers/{username} - supports search, sort, order, limit, offset.
- Browse by type: https://gateway.apiosk.com/types - api, dataset, service, connector, skill, product. One type: https://gateway.apiosk.com/types/{listing_type}/v1
- Per-API metadata: https://gateway.apiosk.com/{api_slug}/metadata - agent-native, MCP-style manifest for one API (operations, input/output schemas, pricing, tool annotations).
- Gateway health: https://gateway.apiosk.com/health

## Where a listing runs (read this before calling)

Every listing runs through the gateway. Call it at its `gateway_url`, i.e.
https://gateway.apiosk.com/{api_slug}/{path}, or POST /{api_slug}/execute. Pay
the gateway's 402; the gateway verifies, forwards and settles to the provider.

There is no second path. `hosted_externally` is false on every listing and
`external_resources` is empty — provider origins and payment addresses are not
published.

## Calling an API

- Uniform execution: POST https://gateway.apiosk.com/{api_slug}/execute with body {"operation": "<id | /path | METHOD /path>", "input": { ... }}. Returns {status, result, cost, latency, operation, api, upstream_status}.
- Transparent proxy: ANY https://gateway.apiosk.com/{api_slug}/{path} - forwards your request to the upstream API.

## Payment (x402)

- Protocol: x402 over HTTP 402 (v1 body + v2 header). Settlement asset: USDC on Base.
- A paid request without payment returns 402 with BOTH dialects: a base64 PAYMENT-REQUIRED header (decoded: {x402Version:2, resource, accepts:[{scheme, network (CAIP-2 e.g. eip155:8453), amount (atomic units), asset, payTo, maxTimeoutSeconds, extra}]}) AND a JSON body carrying x402 v1 accepts[] ({scheme, network (bare name e.g. "base"), maxAmountRequired, resource, description, mimeType, payTo, maxTimeoutSeconds, asset, extra}) for x402-fetch SDK clients, plus X-Payment-Amount, X-Payment-Currency: USDC, X-Payment-Protocol: x402.
- Supply the signed payment proof via the PAYMENT-SIGNATURE header (the legacy X-Payment header is still accepted for x402 v1 clients).
- Check spend for a wallet: https://gateway.apiosk.com/v1/balance?address=0x...

## Publishing an API

- Register: POST https://gateway.apiosk.com/v1/apis/register (wallet-signed). See the root discovery document for required fields and the wallet-auth header format.

## Machine-readable manifests

- Well-known index: https://gateway.apiosk.com/.well-known/
- x402 discovery document (all payable resources + payment requirements): https://gateway.apiosk.com/.well-known/x402
- Plugin manifest: https://gateway.apiosk.com/.well-known/ai-plugin.json
- A2A agent card: https://gateway.apiosk.com/.well-known/agent.json
- MCP discovery: https://gateway.apiosk.com/.well-known/mcp.json
- OpenAPI: https://gateway.apiosk.com/openapi.json
- Root discovery JSON: https://gateway.apiosk.com/ (send `Accept: application/json`)