Create a search - AI Search API

Submit a query to one or more AI search surfaces. By default the request is asynchronous: it returns 202 immediately with a parent job and one child per surface × region. Poll GET /v1/jobs/:id or register a webhook to receive each child’s Envelope on completion.

POST https://api.aisearchapi.dev/v1/search

Every request needs Authorization: Bearer <API_KEY> and Content-Type: application/json.

Body

query

string

required

The prompt to run, 1–10000 characters. This is the exact text sent to each surface.

surfaces

string[]

required

One or more surfaces to capture. At least one is required. Each surface produces one child job per region.Allowed values: chatgpt, claude, perplexity, gemini, copilot, google_ai_overview, google_ai_mode.

regions

object[]

default:"[{ \"country\": \"US\" }]"

Where to run each surface. One child is created per surface × region.

Show region object

country

string

required

ISO-3166 alpha-2 country code, e.g. US, GB, DE.

city

string

Optional city to localize the capture.

language

string

Optional language hint for the surface.

priority

number

default:"5"

Queue priority, 1–10. Higher values are scheduled ahead of lower ones within your account.

webhook

object

Receive a signed POST on each child’s terminal state instead of polling. Recommended for fan-out.

Show webhook object

url

string

required

HTTPS endpoint to notify. SSRF-guarded.

secret

string

required

Shared secret used to HMAC-sign the request body. See Webhooks.

idempotencyKey

string

Safe-retry key. This is a body field, not a header. Reusing the same key with the same body replays the original job; reusing it with a different body returns 409 IDEMPOTENCY_CONFLICT.

Request

curl -X POST https://api.aisearchapi.dev/v1/search \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best crm for startups",
    "surfaces": ["chatgpt", "perplexity"],
    "regions": [{ "country": "US" }],
    "priority": 5
  }'

Response `202 Accepted`

The parent job id has no dots. Each entry in children is a dotted child id you can read individually.

{
  "jobId": "job_8t2q",
  "status": "processing",
  "children": [
    "job_8t2q.chatgpt.us",
    "job_8t2q.perplexity.us"
  ]
}

jobId

string

The parent job id (dotless). Read it with GET /v1/jobs/job_8t2q to see the roll-up status and per-child state.

status

string

Always processing on submit. Terminal states are completed, partial, failed, canceled, expired.

children

string[]

One dotted child id per surface × region, e.g. job_8t2q.chatgpt.us. Reading a child id returns its Envelope.

The Location response header points at the parent job. A poll loop should stop on any terminal state — prefer webhooks over polling for fan-out.

Sync variant

For a single surface you can get the Envelope inline with 200 instead of polling. Add ?mode=sync to the URL or send the header Prefer: wait.

Sync mode is for one surface at a time. It holds the connection open until the capture finishes and is subject to CONCURRENCY_LIMIT_EXCEEDED (429) and SURFACE_TIMEOUT (504).

curl -X POST "https://api.aisearchapi.dev/v1/search?mode=sync" \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best crm for startups",
    "surfaces": ["chatgpt"],
    "regions": [{ "country": "US" }]
  }'

Response `200 OK`

Returns the full Envelope for the single surface. See The Envelope for every field.

{
  "job": {
    "id": "job_8t2q.chatgpt.us",
    "query": "best crm for startups",
    "surface": "chatgpt",
    "region": "US",
    "status": "completed",
    "warnings": [],
    "requestedAt": "2026-06-30T17:02:11Z",
    "completedAt": "2026-06-30T17:02:23Z"
  },
  "provenance": {
    "model": { "providerId": "openai", "observedLabel": "GPT-5", "inferred": false, "confidence": 0.98 },
    "webSearch": { "enabled": true, "known": true },
    "region": { "requested": "US", "effective": "US" },
    "surfacePresent": true
  },
  "answer": {
    "text": "For startups, the top CRMs are HubSpot, Attio and Pipedrive...",
    "markdown": "For startups, the top CRMs are **HubSpot**, **Attio** and **Pipedrive**...",
    "blocks": [{ "type": "paragraph", "text": "...", "referenceIds": [1] }]
  },
  "evidence": {
    "sources": [
      { "id": 1, "url": "https://...", "title": "Best CRMs for startups", "role": "cited", "cited": true, "charRanges": [[0, 58]], "quote": "..." }
    ],
    "fanOut": { "queries": ["best crm for startups 2026", "hubspot vs attio"] },
    "mentions": ["HubSpot", "Attio", "Pipedrive"],
    "shopping": [],
    "ads": []
  }
}

If a surface returns nothing, the job still completes: provenance.surfacePresent is false, job.warnings carries a surface_absent warning, and answer is empty. An empty capture costs no credits.

Per-surface alias

POST /v1/search/:surface targets one surface and is sync by default — no ?mode=sync needed. It accepts two convenience fields:

prompt — alias of query.
country — flat sugar for regions: [{ "country": "..." }].

curl -X POST https://api.aisearchapi.dev/v1/search/chatgpt \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "best crm for startups",
    "country": "US"
  }'

Returns 200 with the Envelope, exactly like the sync variant above.

Idempotency

Include idempotencyKey in the body to make retries safe.

Scenario	Result
First request with a key	`202` — a new job is created.
Same key + same body	`200` with header `Idempotent-Replayed: true` — the original job is replayed, no new work.
Same key + different body	`409 IDEMPOTENCY_CONFLICT`.

curl -X POST https://api.aisearchapi.dev/v1/search \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best crm for startups",
    "surfaces": ["chatgpt"],
    "idempotencyKey": "crm-report-2026-06-30"
  }'

Errors

Every error uses the shape { "error": { "code", "message", "status", "details"? } }.

Code	Status	When
`AUTH_MISSING`	401	No `Authorization` header.
`AUTH_INVALID`	401	Bad or revoked API key.
`VALIDATION_FAILED`	400	Body failed validation; see `details[]`.
`UNSUPPORTED_SURFACE`	400	A value in `surfaces` (or the alias `:surface`) is not requestable.
`IDEMPOTENCY_CONFLICT`	409	Same `idempotencyKey` reused with a different body.
`RATE_LIMIT_EXCEEDED`	429	Account request rate exceeded.
`CONCURRENCY_LIMIT_EXCEEDED`	429	Too many in-flight sync requests.
`QUEUE_CAPACITY_EXCEEDED`	429	Async queue is full.
`SURFACE_TIMEOUT`	504	A sync capture did not finish in time.

429 responses carry Retry-After alongside X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. See Errors for the full catalog.

Response headers

Header	On	Meaning
`X-AISearch-Version`	every response	API version that served the request.
`Location`	`202`	URL of the created parent job.
`Idempotent-Replayed`	replays	`true` when an idempotent request replayed an existing job.
`X-RateLimit-Limit`	rate-limited	Request ceiling for the current window.
`X-RateLimit-Remaining`	rate-limited	Requests left in the current window.
`X-RateLimit-Reset`	rate-limited	When the window resets.
`Retry-After`	429	Seconds to wait before retrying.

Read a job

Poll a parent or fetch a single child’s Envelope.

The Envelope

Every field in the canonical per-surface result.

​Body

​Request

​Response 202 Accepted

​Sync variant

​Response 200 OK

​Per-surface alias

​Idempotency

​Errors

​Response headers

Read a job

The Envelope

Body

Request

Response `202 Accepted`

Sync variant

Response `200 OK`

Per-surface alias

Idempotency

Errors

Response headers