Notable changes to the AI Search API HTTP contract, newest first. For the broader product changelog — new surfaces, dashboard, and pricing — see the canonical product changelog at aisearchapi.dev/changelog.
​
2026-07-11
Auto Extract, Watches, MCP
Auto Extract (BETA)
  • POST /v1/search, the per-surface alias, and batch items now accept extract: true or extract: { targets: [...] } for answer-derived brand mention extraction.
  • evidence.mentions.items[] now reports brand, domain, mentioned, position, sentiment, linked, target, sourceIds, and snippet. Pinned targets remain visible when absent; no result is fabricated.
  • Auto Extract costs 0 credits during BETA. extraction_failed and extraction_skipped warnings report extraction-only degradation while the capture still completes normally.
Watches
  • Scheduled query subscriptions save a query, surfaces, regions, extraction settings, cadence, and optional webhook. Six endpoints cover create, list, get, update, soft-cancel, and cursor-paginated run history.
  • Plans enforce active-watch ceilings and minimum intervals. Three consecutive insufficient-credit skips automatically pause a watch; resuming clears the pause reason and schedules the next run from the current time.
  • Creating a watch is free. Each dispatched run bills per surface × region like a normal async search under the same success-only billing; skipped runs cost nothing.
MCP server
  • https://api.aisearchapi.dev/mcp provides stateless Streamable HTTP MCP with API-key authentication.
  • Ten tools cover search, jobs, surfaces, usage, watches, and watch run history with the same auth, credits, tenancy, and errors as the REST API.
​
2026-06-27
v1.0
Initial public release.The first public version of the AI Search API is here. Capture what the live AI apps actually show — browser-first — and parse every surface with one shape.Search
  • POST /v1/search — sync by default for a single surface with no webhook (one 200 with the finished result inline). Multi-surface requests, requests with a webhook, or ?mode=async fan out durably: 202 { jobId, status: "processing", children: [...] }, with one child per surface × region.
  • Force the inline path with ?mode=sync or the Prefer: wait=30 header; simplify the shape with ?view=flat.
  • Alias POST /v1/search/:surface (for example /v1/search/chatgpt) that accepts prompt (alias of query) and a flat country.
  • POST /v1/search/batch — up to 500 independent items, validated per item, with an atomic whole-batch credit reservation.
Surfaces
  • Live at launch: chatgpt, claude, perplexity, copilot, google_ai_overview, google_ai_mode, google_search, and google_news. The API always auto-routes each surface to its best available capture path.
  • gemini is in the enum but has no v1 capture path yet (submitting it returns a 422).
  • GET /v1/surfaces — live capability matrix: every surface and its current status.
One Envelope for every surface
  • The canonical Envelope normalizes every surface into the same four sections (job, provenance, answer, and evidence), so you write one parser and it works everywhere.
  • answer.markdown is always populated, alongside answer.text and answer.blocks[].
  • Provenance on every capture: model, webSearch, surfacePresent, region, and a single schemaVersion stamp — lane-free, with no internal driver or normalizer versions exposed.
  • Opt-in proof-of-page: request include.html: true on a consumer-UI (scrape) capture to get a top-level html URL, fetched via GET /v1/artifacts/:key. The verbatim upstream capture itself is internal and is not customer-fetchable.
Jobs
  • GET /v1/jobs/:id — poll a parent (rollup plus children) or fetch a child Envelope by its dotted three-segment id (for example job_8t2q.chatgpt.us).
  • GET /v1/jobs (list, cursor-paginated) and POST /v1/jobs/:id/cancel.
Webhooks
  • HMAC-SHA256-signed delivery (over the raw body bytes, X-AISearch-Signature header) via webhook: { url, secret }, with SSRF-guarded destinations. Omit secret to sign with your account’s managed whsec_ secret.
Regions
  • Per-request regions: [{ country, state?, city?, language? }] (ISO-3166 alpha-2 country; omitted means one untargeted GLOBAL capture; at most 10 regions per request).
  • provenance.region reports requested vs effective when a region can’t be honored exactly. GET /v1/regions for discovery.
Idempotency
  • Safe retries with an idempotencyKey body field — same key + same body replays the original job (Idempotent-Replayed: true); a different body returns 409.
DX & operations
  • One flat error envelope everywhere: { code, error, request_id, docs_url }, with X-Request-Id and X-AISearch-Version on every response and live X-RateLimit-* / X-Concurrency-* admission headers on submits.
  • GET /v1/usage (per-(surface, region) ledger + balance), GET /v1/health, and GET /v1/async/status for an inflight snapshot of your key.
  • Strict request validation. Unknown top-level fields on a search body are rejected with 400 VALIDATION_FAILED (named in the message), not silently dropped; query is capped at 2000 characters (422 QUERY_TOO_LONG).
  • Deep health probe. GET /v1/health?probe=deep runs live round-trips against Postgres, D1, and R2 and returns 503 degraded if any dependency is down. This is the endpoint uptime monitors should watch.
Billing
  • Credit-based billing, charged only on successful captures, with 500 free credits to start.