Brand radar, prompt explorer, and AI citation checks — /seo/ai/brand-lookup, /seo/ai/brand-lookup/:jobId/status, /seo/ai/prompt-explorer, /seo/citations.

How a brand shows up inside AI answer engines: whether it is mentioned, what those engines actually say, and whether they cite the site.

Entitlement-gated

Brand radar and prompt explorer require AI search to be enabled on the account — otherwise 403 AI_SEARCH_NOT_ENABLED. A billing problem on an entitled account returns 402 AI_SEARCH_BILLING_ISSUE. POST /seo/citations is not gated.

Start a brand lookup

POST/seo/ai/brand-lookup

Queues a brand-radar job. Returns immediately with a job handle — this is asynchronous work.

Request body

projectIdstringbodyrequired

Owning project.

querystringbodyrequired

The brand name or domain to look up.

locationCodenumberbodydefault: 2840

Numeric location code.

languageCodestringbodydefault: en

Two-letter language code.

competitorsstring[]body

Up to 50 competitor names or domains to compare against.

Response fields

jobIdstring

Poll this with the status endpoint.

lookupKeystring

Cache key identifying this lookup.

statusstring

Always queued on creation.

statusUrlstring

Ready-made URL for the status endpoint.

Request

curl -X POST https://api.misar.io/seo/ai/brand-lookup \
  -H "Authorization: Bearer $MISARSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "5b1c7d2e-…",
    "query": "acme.com",
    "competitors": ["competitor-a.com", "competitor-b.com"]
  }'

202 — Queued

{
  "jobId": "brl_9d3f2a10",
  "lookupKey": "acme.com:2840:en",
  "status": "queued",
  "statusUrl": "/api/seo/ai/brand-lookup/brl_9d3f2a10/status?projectId=5b1c7d2e-…"
}

Rate limit: 5 requests per 60 s.

There is no GET on this path

/seo/ai/brand-lookup accepts POST only. Results are read from the status endpoint below.

Poll a brand lookup

GET/seo/ai/brand-lookup/:jobId/status

Not rate limited — safe to poll.

Path parameters

jobIdstringpathrequired

From the queue response.

Query parameters

projectIdstringqueryrequired

Owning project.

Response fields

statusstring

One of queued, running, complete, errored, unknown.

resultobject

The brand-radar payload. Present only when status is complete.

errorobject

{ message }. Present only when status is errored.

progressnumber | null

Present while the job is not terminal.

Request

curl "https://api.misar.io/seo/ai/brand-lookup/brl_9d3f2a10/status?projectId=5b1c7d2e-…" \
  -H "Authorization: Bearer $MISARSEO_API_KEY"

200 — Running

{ "status": "running", "progress": 0.4 }

200 — Complete

{ "status": "complete", "result": { "mentions": 12, "sentiment": "positive" } }

200 — Errored

{ "status": "errored", "error": { "message": "provider timeout" } }

Reading a completed result is free

The completed payload is served from cache. Polling after completion is idempotent and never re-charges. A job belonging to another organization returns 404, not 403.

Prompt explorer

POST/seo/ai/prompt-explorer

Runs one prompt against up to four AI models and returns what each says — synchronously.

Request body

projectIdstringbodyrequired

Owning project.

promptstringbodyrequired

The prompt to run.

modelsstring[]bodyrequired

Between 1 and 4 entries, each one of chat_gpt, claude, gemini, perplexity. An unrecognised value rejects the whole request.

highlightBrandstringbody

A brand to highlight in the returned answers.

webSearchbooleanbodydefault: true

Whether models may search the web while answering.

webSearchCountryCodestringbody

Two-letter country code scoping the web search. Validated against the supported list.

Response fields

resultobject

Per-model answers.

Request

curl -X POST https://api.misar.io/seo/ai/prompt-explorer \
  -H "Authorization: Bearer $MISARSEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "5b1c7d2e-…",
    "prompt": "What is the best SEO audit tool?",
    "models": ["chat_gpt", "perplexity"],
    "highlightBrand": "Acme",
    "webSearch": true
  }'

400 — Bad model

{
  "error": "Unknown model(s): gpt4. Valid values: chat_gpt, claude, gemini, perplexity",
  "code": "VALIDATION_ERROR"
}

Rate limit: 10 requests per 60 s.

Citation check

POST/seo/citations

Checks whether a domain is cited in grounded AI answers for a set of queries.

This endpoint is unauthenticated

It resolves no caller, takes no projectId, and is not rate limited. Treat it as a public utility and send nothing sensitive.

Request body

domainstringbodyrequired

The domain to look for in the answers.

queriesstring[]bodyrequired

Queries to run. Only the first 10 are used; the rest are ignored silently.

Response fields

domainstring

Echo of the requested domain.

checkednumber

How many queries were actually run.

citationsArray<{query, url, title?}>

One entry per query where the domain was cited.

summaryobject

{ queries, cited } — how many were run and how many produced a citation.

Request

curl -X POST https://api.misar.io/seo/citations \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acme.com",
    "queries": ["best seo audit tool", "acme seo review"]
  }'

200 — OK

{
  "domain": "acme.com",
  "checked": 2,
  "citations": [
    { "query": "best seo audit tool", "url": "https://acme.com/audit", "title": "Acme Site Audit" }
  ],
  "summary": { "queries": 2, "cited": 1 }
}

422 — Missing input

{ "error": "domain and queries[] required" }

An empty result is ambiguous

If the grounded model is unavailable, this endpoint degrades to 200 with citations: [] rather than failing. An empty array means "not cited or the check could not run" — do not treat it as proof of absence.

Status codes

Code	Meaning
`200`	Result returned
`202`	Brand lookup queued
`400`	`VALIDATION_ERROR` — bad model list, missing fields, too many `competitors`
`401`	`UNAUTHENTICATED` (not applicable to `/seo/citations`)
`402`	`AI_SEARCH_BILLING_ISSUE`
`403`	`AI_SEARCH_NOT_ENABLED`
`404`	`NOT_FOUND` — project or job not found
`422`	`/seo/citations` only — `domain and queries[] required`
`429`	`RATE_LIMITED`
`502`	`/seo/citations` only — citation detection unavailable

AI Search

Start a brand lookup

Poll a brand lookup

Prompt explorer

Citation check

Status codes

On this page