Create a search

Submit a query to one or more AI search surfaces.

One surface, no webhook (the hello-world case) runs synchronously by default: the call returns the terminal Envelope in one 200.
Multiple surfaces, a webhook, or ?mode=async use the durable path: 202 immediately with a parent job and one child per surface × region. Poll GET /v1/jobs/:id or register a webhook.

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

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

Query parameters

mode

string

sync forces the bounded inline path; async forces the durable 202 + poll path. Omitted: a single-surface no-webhook request runs sync, everything else async. The header Prefer: wait=30 is equivalent to ?mode=sync.

view

string

flat projects each Envelope of a sync response to the compact flat shape (surface, status, text, markdown, sources). One child returns the flat object directly; several children return { "results": [...] }.

Body

query

string

required

The prompt to run. This is the exact text sent to each surface. prompt is accepted as an alias. Non-empty, up to 2000 characters — a longer value is rejected with 422 QUERY_TOO_LONG.

surfaces

string[]

required

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

regions

object[]

Where to run each surface — at most 10 per request. One child is created per surface × region. Omitted: one untargeted (GLOBAL) child per surface. A bare string like "US" is accepted as sugar for { "country": "US" }.

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 BCP-47 language hint for the surface.

webhook

object

Receive a signed POST on each child’s terminal state instead of polling. Setting a webhook forces the async path. Recommended for fan-out.

Show webhook object

url

string

required

Public http(s) endpoint to notify. SSRF-guarded — loopback/private/link-local/metadata targets are rejected at submission.

secret

string

Shared secret used to HMAC-sign the request body. Omit to sign with your account’s active managed secret. 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 (202 + Idempotent-Replayed: true); reusing it with a different body returns 409 IDEMPOTENCY_CONFLICT.

extract

boolean | object

Opt in to Auto Extract. true is identical to {}: extract brands the answer mentions without pinning targets. false, or omitting the field, disables extraction and leaves evidence.mentions as null. Auto Extract is BETA and adds 0 credits today; pricing will change at GA.

Show extract object

targets

string[]

Up to 10 brand names or bare domains, each non-empty and at most 100 characters. Pinned targets are reported whether present or absent.

Unknown top-level fields are rejected, not silently dropped. Sending a field this endpoint doesn’t accept (a typo, or a control it doesn’t support) returns 400 VALIDATION_FAILED naming the offender. Send only the fields above — the API fails loud so a field that looks like a control never no-ops in silence.

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" }]
  }'

const res = await fetch('https://api.aisearchapi.dev/v1/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'best crm for startups',
    surfaces: ['chatgpt', 'perplexity'],
    regions: [{ country: 'US' }],
  }),
});

const job = await res.json();
console.log(res.status, job); // 202 (two surfaces -> async)

import os
import requests

res = requests.post(
    "https://api.aisearchapi.dev/v1/search",
    headers={
        "Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "query": "best crm for startups",
        "surfaces": ["chatgpt", "perplexity"],
        "regions": [{"country": "US"}],
    },
)

print(res.status_code, res.json())  # 202 (two surfaces -> async)

Response `202 Accepted` (async)

The parent job id has no dots. Each entry in children is a dotted 3-segment child id — <jobId>.<surface>.<regionKey> — where the region key is the lowercased country[:city][:language] (or GLOBAL when untargeted).

{
  "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. Reading a child id returns its Envelope.

A poll loop should stop on any terminal state — prefer webhooks over polling for fan-out.

Response `200 OK` (sync)

A sync call returns the parent id, its rollup status, and the full Envelope per child:

{
  "jobId": "job_8t2q",
  "status": "completed",
  "children": [
    {
      "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": null,
          "observedLabel": "gpt-5-3",
          "inferred": true,
          "confidence": 0.6
        },
        "webSearch": { "enabled": true, "known": true },
        "triggerState": "search",
        "persona": "anonymous_default_model",
        "loginState": "logged_out",
        "surfacePresent": true,
        "region": { "requested": "US", "effective": "US" },
        "capturedAt": "2026-06-30T17:02:23Z",
        "callUuid": "call_e9e13810ec46f8bbb814497766d1d05c",
        "schemaVersion": "2026-06-27"
      },
      "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": "For startups...",
            "referenceIds": [0, 1]
          }
        ]
      },
      "evidence": {
        "sources": [
          {
            "id": 0,
            "url": "https://www.hubspot.com",
            "title": "HubSpot",
            "role": "cited",
            "cited": true,
            "charRanges": [[27, 34]]
          },
          {
            "id": 1,
            "url": "https://attio.com",
            "title": "Attio",
            "role": "cited",
            "cited": true,
            "charRanges": [[36, 41]]
          }
        ],
        "fanOut": {
          "provenance": "observed",
          "queries": ["best crm for startups 2026"]
        },
        "mentions": null,
        "shopping": null,
        "ads": null
      },
      "credits": { "creditsToCharge": 5, "creditsCharged": 5 }
    }
  ]
}

evidence.mentions populates only when the request sets extract. See Auto Extract for the full shape, pinned-target absence behavior, and examples.

With ?view=flat the same call returns just { surface, status, text, markdown, sources }.

Sync mode holds the connection open until the capture finishes and is subject to 429 CONCURRENCY_LIMIT_EXCEEDED. For more than one surface, prefer the async default.

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 — sync by default like any single-surface call. 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?view=flat" \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "best crm for startups",
    "country": "US"
  }'

const res = await fetch(
  'https://api.aisearchapi.dev/v1/search/chatgpt?view=flat',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ prompt: 'best crm for startups', country: 'US' }),
  },
);

const flat = await res.json();
console.log(res.status, flat.markdown); // 200

import os
import requests

res = requests.post(
    "https://api.aisearchapi.dev/v1/search/chatgpt?view=flat",
    headers={
        "Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"prompt": "best crm for startups", "country": "US"},
)

print(res.status_code, res.json()["markdown"])  # 200

Idempotency

Include idempotencyKey in the body to make retries safe.

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

curl -X POST "https://api.aisearchapi.dev/v1/search?mode=async" \
  -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 flat shape { "code", "error", "request_id", "docs_url", "details"? }. Validation messages name the offending field and the allowed values.

400

{
  "code": "UNSUPPORTED_SURFACE",
  "error": "surface 'grok' is not supported; valid surfaces: chatgpt, claude, perplexity, gemini, copilot, google_ai_overview, google_ai_mode, google_search, google_news",
  "request_id": "req_9f2c1a7e4b5d48f1a3c6e8d0b2a4f6c8",
  "docs_url": "https://docs.aisearchapi.dev/guides/errors#unsupported_surface"
}

Code	Status	When
`AUTH_INVALID`	401	Missing, bad, or revoked API key.
`VALIDATION_FAILED`	400	A field failed validation — the message names the field and allowed values.
`UNSUPPORTED_SURFACE`	400	A value in `surfaces` (or the alias `:surface`) isn’t a surface.
`INSUFFICIENT_CREDITS`	402	Not enough credits; nothing is spawned.
`IDEMPOTENCY_CONFLICT`	409	Same `idempotencyKey` reused with a different body.
`UNSUPPORTED_METHOD_FOR_SURFACE`	422	The surface has no live v1 capture path yet — the message names what IS supported.
`TOO_MANY_REGIONS`	422	More than 10 regions in one request.
`QUERY_TOO_LONG`	422	`query` (or `prompt`) is over 2000 characters.
`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.

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-Request-Id`	every response	Correlation id; matches `request_id` in error bodies. Send your own to thread it through.
`X-AISearch-Version`	every response	Envelope schema version that served the request.
`X-RateLimit-Limit` / `-Remaining` / `-Reset`	submits + 429	Live admission-bucket state for your key.
`Retry-After`	429	Seconds to wait before retrying.
`X-Concurrency-Limit` / `-Running` / `-Queued`	submits	Sync concurrency state for your key.
`Idempotent-Replayed`	replays	`true` when an idempotent re-submit replayed the original job.

Read a job

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

The Envelope

Every field in the canonical per-surface result.

Auto Extract

Extract brand mentions and pin targets for present-or-absent reporting.

Endpoints

Account & discovery

Watches

By surface

Query parameters

Body

Request

Response `202 Accepted` (async)

Response `200 OK` (sync)

Per-surface alias

Idempotency

Errors

Response headers

Read a job

The Envelope

Auto Extract

​Query parameters

​Body

​Request

​Response 202 Accepted (async)

​Response 200 OK (sync)

​Per-surface alias

​Idempotency

​Errors

​Response headers

Read a job

The Envelope

Auto Extract

Query parameters

Body

Request

Response `202 Accepted` (async)

Response `200 OK` (sync)

Per-surface alias

Idempotency

Errors

Response headers