# AI Search API: full contract summary

> One API for every AI answer engine. It captures what a real person sees on consumer AI surfaces and returns the answer, with its citations inline, plus provenance as one stable, versioned JSON contract: the Envelope.

Site: https://aisearchapi.dev · Docs: https://docs.aisearchapi.dev · API base: https://api.aisearchapi.dev

## Authentication & modes

- Auth: `Authorization: Bearer <API_KEY>`.
- Async by default: submit a capture, receive `202` with a job id, then poll `GET /v1/jobs/:id`.
- Sync mode: append `?mode=sync` to receive an inline Envelope in the response.

## Surfaces

Live today: ChatGPT, Claude, Perplexity, Copilot, Google AI Overview, Google AI Mode, Google Search and Google News.
- Claude runs via the official Anthropic API. The others run browser-first on our own stealth-browser fleet.
- Browser capture currently uses guest (logged-out) sessions. An authenticated account pool for login-walled surfaces is phase-2 (not live).

Roadmap (phase-2, not live): Gemini (no v1 path today, so requests are honestly rejected), Meta AI, DeepSeek, Amazon Rufus, Grok, and the authenticated-browser lane. These are never returned as live.

## The Envelope (canonical response)

Every surface and method normalizes to the same Envelope, three sections:

1. `job` header: `id`, `query`, `surface`, `region`, `status` (`queued` | `running` | `completed` | `partial` | `failed`), `warnings[]`, `requestedAt`, `completedAt`, and `artifacts` (`rawKey`, the verbatim upstream capture in R2, rewritten to a fetchable `rawUrl`, not expired at 24h).
2. `provenance` records how the answer was obtained: `official` (vendor API vs real browser), `loginState`, requested-vs-effective `region`, whether the surface actually web-searched or answered from weights, `surfacePresent` (first-class absence), the observed model vs any inferred model id, and versioned provenance metadata. Never equates a UI label with an official model id.
3. `answer` carries `text`, always-populated normalized `markdown` (with any citations the surface showed preserved inline), and `blocks[]` (typed: paragraph | heading | list | code | quote).

## Data contract, enforced by the schema

- One canonical Envelope across every surface and acquisition method, the same shape for every engine.
- Observed vs inferred provenance is always distinguished, so you know which fields are ground truth.
- A quiet honesty guarantee rides inside the schema: absence is data (`provenance.surfacePresent: false` still completes with a `surface_absent` warning, never a coerced empty result) and an unavailable driver fails loud with `DRIVER_UNAVAILABLE` rather than a fabricated/mock answer.
- The verbatim raw capture is preserved on `job.artifacts.rawKey` (rewritten to a fetchable `rawUrl`) and kept durably in R2, not expired at 24h, so every capture stays reproducible.

## Pricing

Credit-based; every Envelope field included; credits are only spent on a successful capture. Machine-readable table at https://aisearchapi.dev/pricing.md. Full docs at https://docs.aisearchapi.dev.