Data model

Your organization owns one or more sites. Each site has one brand (you) and a list of competitors. The site’s prompts are asked on its engines every day, and each answer is stored once with the brands it named and the pages it cited. Reports group those answers by date, engine, prompt or prompt category. On the AI traffic side, the same site receives AI crawler hits and AI referral visits from its server logs, its Cloudflare Worker or its JavaScript snippet.

Entity reference

Entity	What it is
Organization	Your RankRaft account. API keys belong to it, not to a person. Holds the plan.
Site	One website you track, such as `misalifoods.com`. Every report call is scoped to one `site_id`.
Brand	The brand the site represents: its name, the domains that count as your own site, and any aliases (other names the engines use for you). One per site.
Competitor	A brand you are compared against, with its domains. Only confirmed competitors are ranked and counted in share of voice. Unconfirmed ones were found in answers and wait for someone to confirm them in the dashboard.
Prompt	A question asked every day, such as “best mixed pickle brand”. Each has a category: `Discovery`, `Comparison`, `Alternatives`, `How-to`, `Pricing` or `Brand`. Prompts are switched on and off, never deleted, so their history stays.
Engine (`platform`)	Where the answer came from: `chatgpt`, `ai_overviews`, `ai_mode`, `gemini`, `claude`, `perplexity`, `copilot`. Which ones a site runs depends on its plan.
Market	The location a site is measured from, such as “Multan, Pakistan”. Set per site in the dashboard; answers reflect what a searcher there would see.
Answer	One response from one engine to one prompt on one UTC day: its text, the brands it named in order, its citations, and the tone it used about you.
Citation	A link in an answer. Classified by owner (`own`, `competitor`, `third_party`) and source kind (forum, review, roundup, editorial, marketplace and so on).
Crawler hit	One request from an AI or search crawler, with its bot, provider, purpose, page and whether its IP address checks out.
Referral visit	One person arriving from an AI assistant, with the source and landing page.

What this means for queries

Every report takes one site_id. There are no cross-site queries; loop over your sites instead.
filter narrows which answers count. Answer reports filter by platform, prompt (ID or text) and category; the citations report adds domain, owner and source_kind.
group_by splits the result. Up to two of date, platform, prompt and category for answer reports (date, platform, prompt for citations); up to three dimensions for traffic reports.
brands chooses whose numbers you get in the visibility report: "owned" (default), "all" (you plus confirmed competitors, ranked), or a list of names.

Endpoints by entity

Entity	Endpoint
Your key and organization	`GET /v1/me`
Sites	`GET /v1/sites`, `GET /v1/sites/{site_id}`
Competitors	`GET /v1/sites/{site_id}/competitors`
Prompts	`GET /v1/sites/{site_id}/prompts`
Engines	`GET /v1/platforms`
Answers	`POST /v1/answers`
Actions	`GET /v1/sites/{site_id}/actions`

The brand’s own name is not a separate endpoint: it comes back on every visibility row as brand.name with owned: true. See Your brand, domains and competitors.

Get started

Metrics

Visibility

Citations

More recipes

Entity reference

What this means for queries

Endpoints by entity

​Entity reference

​What this means for queries

​Endpoints by entity

Entity reference

What this means for queries

Endpoints by entity