እነዚህ የገንቢ ሰነዶች በአሁኑ ጊዜ በእንግሊዝኛ ብቻ ናቸው። ኮድ እና ኤፒአይ ባህሪ በሁሉም ክልሎች ተመሳሳይ ናቸው።

SEO & AI-Visibility API

Two related surfaces, both backed by module-SEO and keyed by brand_id:

SEO (/v1/seo/*) — rankings snapshot, audits, keyword intelligence, backlinks, competitor benchmarks, and content optimization.
AI-Visibility (/v1/ai-visibility/{brand_id}/*) — domain authority, backlinks, tracked keywords, keyword research, full site scans, and the flagship AI-visibility (how a brand shows up in LLM answers).

Authentication

Authorization: Bearer ai92_live_<key>     # production
Authorization: Bearer ai92_test_<key>     # sandbox

Mutating requests support Idempotency-Key and are brand-gated. Async operations return a job_id; poll it at GET /v1/jobs/{job_id}.

Credit costs at a glance

Endpoint	Cost
`GET /v1/seo/snapshot`	Free
`POST /v1/seo/audit`	20 cr (async)
`GET /v1/seo/keywords`	5 cr
`GET /v1/seo/backlinks`	10 cr
`GET /v1/seo/competitors`	30 cr
`POST /v1/seo/content-optimize`	8 cr
`GET /v1/ai-visibility/{brand_id}`	27 cr
`GET /v1/ai-visibility/{brand_id}/competitors`	27 cr
`GET /v1/ai-visibility/{brand_id}/authority`	3 cr
`GET /v1/ai-visibility/{brand_id}/backlinks`	5 cr
`GET /v1/ai-visibility/{brand_id}/keywords`	3 cr
`POST /v1/ai-visibility/{brand_id}/keywords/research`	8 cr
`POST /v1/ai-visibility/{brand_id}/scan`	20 cr (async)

SEO

GET /v1/seo/snapshot

Cost: Free

Free dashboard glance: current rankings + regional presence for a brand. The deep, actionable products stay metered.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	query	string	Yes	The brand to snapshot.

Request

bash

curl "https://api.ai92.ai/v1/seo/snapshot?brand_id=acme" \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "brand_id": "acme",
  "rankings": { "tracked": 120, "top10": 34, "avg_position": 18.2 },
  "regions": { "US": 0.62, "UK": 0.21, "DE": 0.17 }
}

POST /v1/seo/audit

Cost: 20 credits (async)

Kick off a module-SEO scan/audit. Returns a scan handle; poll the result.

Auth: Bearer

Field	Type	Required	Description
`brand_id`	string	Yes	The brand to audit.

Request

bash

curl https://api.ai92.ai/v1/seo/audit \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "acme"}'

Response 200 OK

json

{ "scan_id": "scan_9f2", "status": "queued" }

GET /v1/seo/keywords

Cost: 5 credits

Keyword intelligence for a brand.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	query	string	Yes	The brand.
`limit`	query	integer	No	Page size. Default `100`.
`offset`	query	integer	No	Page offset. Default `0`.

Request

bash

curl "https://api.ai92.ai/v1/seo/keywords?brand_id=acme&limit=50" \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "brand_id": "acme",
  "keywords": [
    { "keyword": "crm software", "position": 7, "volume": 40500, "difficulty": 68 }
  ]
}

GET /v1/seo/backlinks

Cost: 10 credits

Backlink profile for a brand.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	query	string	Yes	The brand.

Request

bash

curl "https://api.ai92.ai/v1/seo/backlinks?brand_id=acme" \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "brand_id": "acme",
  "total_backlinks": 18420,
  "referring_domains": 1290,
  "top_links": [ { "url": "https://techblog.example/acme", "authority": 74 } ]
}

GET /v1/seo/competitors

Cost: 30 credits

Competitor benchmark for a brand.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	query	string	Yes	The brand.
`include_untracked`	query	boolean	No	Include competitors not currently tracked. Default `false`.

Request

bash

curl "https://api.ai92.ai/v1/seo/competitors?brand_id=acme&include_untracked=true" \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "brand_id": "acme",
  "competitors": [
    { "domain": "rival.com", "shared_keywords": 312, "visibility_gap": -0.14 }
  ]
}

POST /v1/seo/content-optimize

Cost: 8 credits per page

Content optimization recommendations for a page / target keyword.

Sandbox note. This endpoint is not functional in the sandbox environment: calls return { "status": "pending", "results": null } with no job_id, so there is no poll path and the call never resolves. Do not build a polling loop against it in sandbox, and do not rely on sandbox responses to validate the request shape. Test it against production with real content.

Auth: Bearer

Field	Type	Required	Description
`brand_id`	string	Yes	The brand.
`page_url`	string / null	No	The page to optimize.
`target_keyword`	string / null	No	Keyword to optimize for.

Request

bash

curl https://api.ai92.ai/v1/seo/content-optimize \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"brand_id": "acme", "page_url": "https://acme.com/pricing", "target_keyword": "crm pricing"}'

Response 200 OK

json

{
  "brand_id": "acme",
  "page_url": "https://acme.com/pricing",
  "score": 71,
  "recommendations": [
    { "type": "heading", "message": "Add an H2 containing the target keyword." }
  ]
}

AI-Visibility

All AI-Visibility routes take brand_id as a path parameter.

GET /v1/ai-visibility/{brand_id}

Cost: 27 credits

AI-visibility overview — how the brand shows up in LLM answers.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	path	string	Yes	The brand.

Request

bash

curl https://api.ai92.ai/v1/ai-visibility/acme \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "brand_id": "acme",
  "ai_visibility_score": 63,
  "mention_rate": 0.41,
  "engines": { "chatgpt": 0.52, "perplexity": 0.38, "gemini": 0.33 }
}

GET /v1/ai-visibility/{brand_id}/competitors

Cost: 27 credits

AI-visibility competitor comparison over a time window.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	path	string	Yes	The brand.
`days`	query	integer	No	Look-back window. Default `30`.

Request

bash

curl "https://api.ai92.ai/v1/ai-visibility/acme/competitors?days=30" \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "brand_id": "acme",
  "window_days": 30,
  "competitors": [ { "brand": "rival", "ai_visibility_score": 71, "delta": 8 } ]
}

GET /v1/ai-visibility/{brand_id}/authority

Cost: 3 credits

Domain authority for a brand.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	path	string	Yes	The brand.

Request

bash

curl https://api.ai92.ai/v1/ai-visibility/acme/authority \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{ "brand_id": "acme", "domain_authority": 58, "page_authority": 49 }

GET /v1/ai-visibility/{brand_id}/backlinks

Cost: 5 credits

Backlink profile for a brand (AI-Visibility surface).

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	path	string	Yes	The brand.

Request

bash

curl https://api.ai92.ai/v1/ai-visibility/acme/backlinks \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{ "brand_id": "acme", "total_backlinks": 18420, "referring_domains": 1290 }

GET /v1/ai-visibility/{brand_id}/keywords

Cost: 3 credits

Tracked keywords for a brand.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	path	string	Yes	The brand.

Request

bash

curl https://api.ai92.ai/v1/ai-visibility/acme/keywords \
  -H "Authorization: Bearer ai92_test_51a9c0de…"

Response 200 OK

json

{
  "brand_id": "acme",
  "keywords": [ { "keyword": "crm software", "position": 7, "volume": 40500 } ]
}

POST /v1/ai-visibility/{brand_id}/keywords/research

Cost: 8 credits

Keyword research from seed keywords for a market and language.

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	path	string	Yes	The brand.
`seed_keywords`	body string[]	Yes	Seed keywords. Length `1`–`50`.
`market`	body string	No	Target market. Default `US`.
`language`	body string	No	Language code. Default `en`.

Request

bash

curl https://api.ai92.ai/v1/ai-visibility/acme/keywords/research \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"seed_keywords": ["crm", "sales automation"], "market": "US", "language": "en"}'

Response 200 OK

json

{
  "brand_id": "acme",
  "suggestions": [
    { "keyword": "best crm for startups", "volume": 8100, "difficulty": 52 }
  ]
}

POST /v1/ai-visibility/{brand_id}/scan

Cost: 20 credits (async)

Trigger a full site SEO scan. Credits are reserved now, consumed on success, and refunded on backend failure. Returns a pollable job; poll at GET /v1/jobs/{job_id}. The request body is optional — a no-body POST runs a default full-site scan; brand_id comes from the path (do not put it in the body).

Auth: Bearer

Parameter	In	Type	Required	Description
`brand_id`	path	string	Yes	The brand.
`url`	body string / null	No	Specific URL to scan.
`full`	body boolean	No	Full-site scan. Default `true`.

Request

bash

curl https://api.ai92.ai/v1/ai-visibility/acme/scan \
  -H "Authorization: Bearer ai92_test_51a9c0de…" \
  -H "Content-Type: application/json" \
  -d '{"full": true}'

Response 200 OK

json

{
  "job_id": "seo_b3d1c0a8…",
  "status": "queued",
  "service": "ai_visibility",
  "credits_reserved": 20
}

Errors

Status	Code	When
`402`	`INSUFFICIENT_CREDITS`	Balance below 20 credits.