# apifare — integrator contract v1 (2026-09-19)

Canonical: https://apifare.com/integrators (this file is its markdown twin)

## The integration unit
Optional provider inside YOUR abstraction (router slot / provider module /
extension). Never a hard dependency; never replaces BYOK. EXPLICIT-ONLY
selection: chosen by the user or operator, never auto-picked because
credentials exist. Your selection logic stays authoritative.

## Wire contract
POST /v1/call/{slug} (JSON body, Authorization: Bearer <token>).
search "dataforseo": {"q","count"?<=100,"country"?,"language"?} ->
  result.results[] = {title,url,description,position}
fetch "scrape": {"url"} -> result.{url,status,markdown}
Discovery: GET /v1/search?q=… (route + exact price per result).
Indexes: /openapi.json · /agents.json · /llms.txt. MCP: apifare-mcp (npm).
Env names APIPAY_TOKEN and APIFARE_TOKEN both supported indefinitely.
Deprecation: 12 months' notice on the canonical page, both forms
supported throughout.

## Pricing
1 credit = $0.01, flat per call: search 0.3 · fetch 0.3 · weather 0.1.
Marketplace: reserve 5cr, settle to true cost (ceiling 20cr; headers
x-apipay-reserved / x-apipay-credits-charged). Listed price IS billed
price (CI-enforced). Failed provider calls auto-refund (refunded:true +
refund_credits in the body). Trial: 500 credits, 14-day expiry;
purchased credits never expire. Zero search results = delivered, billed.

## The payment moment (402) — conformance
RELAY: surface human_readable + topup_url verbatim; retry the same call
after payment (live rehearsal: resume 44s after payment).
GRACEFUL: fall back WITH a visible notice; keep a way back to apifare.
Silent fallback is non-conformant. Never present fallback results as
apifare results. Never route around HTTP 403 policy denials or killed
agent tokens — that is the owner's governance, not an outage.

## Error classes to handle (fixtures on the canonical page)
200 success · 402 PAYMENT_REQUIRED (topup_url, human_readable,
auto_refill) · 403 ADAPTER_DENIED / AGENT_KILLED · 429 RATE_LIMITED
(60 requests/min per token) · 502 PROVIDER_ERROR (refunded:true, refund_credits).

## Nested budgets
POST /v1/agents mints per-user/session tokens under one account, each
with per-call/daily/monthly caps, allow/deny lists, individual kill —
enforced before dispatch.

## Latency (measured 2026-09-19, end-to-end, public internet, n=5/route)
open-meteo p50 354ms (344–507) — bounds apifare overhead ~100–250ms ·
scrape p50 803ms (609–1996) · dataforseo live SERP p50 3.9s (2.3–13.5s).
Measure us adversarially; trial accounts are free.

## Privacy & retention per component
Bodies: NEVER stored or logged (memory passthrough). Metadata + ledger +
audit: life of the account, append-only. Search-miss text: kept as
demand signal, removable on request. Vaulted keys: encrypted until the
user deletes them; never returned by any endpoint. IP rate counters:
expire <=24h. Full policy: https://apifare.com/privacy

## Maintenance commitment
Claims CI-pinned or dated-measured; external conformance test run on
request with pasted output; breaking changes only via the deprecation
policy; integration bugs answered same-week (track record: same-day);
we write the adapter PR to your conventions on request.