{ "openapi": "3.1.0", "info": { "title": "AIR Public API", "version": "1.0.0", "description": "The AIR Public API returns an **AIR score (1\u201310)** \u2014 a decile of AI visibility within\nthe active dataset version \u2014 for every domain, brand, and phrase we track, plus\nAI-files intelligence (llms.txt, robots.txt AI-agent directives, JSON-LD) per domain.\n\n## Score semantics\n`air_score` is an integer 1\u201310 (10 = most AI-visible), computed as a decile\n(`CEIL(CUME_DIST \u00d7 10)`) over eligible entities in the currently active dataset\nversion. **`0` means insufficient data** \u2014 the entity exists but hasn't cleared the\nminimum-occurrence gate yet, it is never part of the scored distribution.\n\n## Caching & ETags\nEvery response carries an `ETag` header and `Cache-Control: max-age=300`. Send the\nETag back as `If-None-Match` on your next request \u2014 a match returns `304 Not\nModified` with no body, saving bandwidth. **A `304` still counts against your\nper-minute rate limit the same as any other request** \u2014 the limiter is checked\nbefore revalidation, so a tight polling loop is throttled just like repeated `200`s.\nServer-side, cached data is only recomputed when the underlying scores actually\nchange, but that is not a promise about your own cache: respect the `max-age=300`\nheader rather than caching responses client-side indefinitely, since scores do\nchange on recompute.\n\n## Rate limits\nAll endpoints are public and unauthenticated. Anonymous callers are throttled by IP;\nmint a Sanctum bearer token to lift the limit. See `GET \/meta` for the current\nper-minute limits.\n\n## Dataset version\nEvery response's `meta.dataset_version` names the dataset the numbers come from.\nScores are never pooled across dataset versions.\n\n## Unknown entities\n`GET \/domains\/{hostname}` returns `200` even for a domain we've never seen\n(`tracked: false, air_score: 0`) \u2014 the same shape is used for tracked and untracked\ndomains so client code doesn't need a special case." }, "servers": [ { "url": "https:\/\/airanks.net\/api\/v1" } ], "paths": { "\/brands": { "get": { "operationId": "v1.brands.index", "summary": "Ranked brand list", "tags": [ "Brand" ], "parameters": [ { "name": "category", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "q", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "air_score", "occurrences", null ] } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] }, "pagination": { "type": "array", "items": {} } }, "required": [ "dataset_version", "pagination" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/brands\/{id}": { "get": { "operationId": "v1.brands.show", "summary": "Get a brand's AIR score and its top-ranked phrases", "tags": [ "Brand" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } } } } }, "\/cli\/auth": { "post": { "operationId": "v1.cli-auth.start", "tags": [ "CliAuth" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "code_challenge": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" } }, "required": [ "code_challenge" ] } } } }, "responses": { "201": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "nonce": { "type": "string" }, "browser_url": { "type": "string", "description": "The code-entry page, gh-style - deliberately carries NO nonce. Landing here proves\nnothing; typing the code (which only someone who can see this terminal has) is what\nproves possession and unlocks the approve\/deny screen for this specific request." }, "confirmation_code": { "type": "string" }, "interval": { "type": "integer", "const": 5 }, "expires_in": { "type": "integer", "const": 600 } }, "required": [ "nonce", "browser_url", "confirmation_code", "interval", "expires_in" ] }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/cli\/auth\/poll": { "post": { "operationId": "v1.cli-auth.poll", "tags": [ "CliAuth" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "nonce": { "type": "string", "minLength": 64, "maxLength": 64 }, "code_verifier": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" } }, "required": [ "nonce", "code_verifier" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "pending" }, "interval": { "type": "integer", "const": 5 } }, "required": [ "status", "interval" ] }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "token": { "type": "string" }, "expires_at": { "type": [ "string", "null" ] }, "user": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ] } }, "required": [ "status", "token", "expires_at", "user" ] }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "denied" } }, "required": [ "status" ] }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "expired" } }, "required": [ "status" ] }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "not_found" } }, "required": [ "status" ] }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "forbidden" } }, "required": [ "status" ] }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/domains": { "get": { "operationId": "v1.domains.index", "summary": "Ranked domain list", "tags": [ "Domain" ], "parameters": [ { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "air_score", "occurrences", null ] } }, { "name": "min_score", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] }, "pagination": { "type": "array", "items": {} } }, "required": [ "dataset_version", "pagination" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/domains\/lookup": { "post": { "operationId": "v1.domains.lookup", "description": "Response keys echo the caller's raw strings verbatim (so the toolbar can correlate\nresults back to the tabs it asked about); entries that don't parse to a valid hostname\nmap to `null` rather than being dropped.", "summary": "Batch domain lookup - up to `air.api.batch_max_hostnames` hostnames per request", "tags": [ "Domain" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "hostnames": { "type": "array", "items": { "type": "string", "maxLength": 2048 }, "minItems": 1, "maxItems": 100 } }, "required": [ "hostnames" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": [ "array", "null" ], "items": {} } }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/domains\/{hostname}": { "get": { "operationId": "v1.domains.show", "description": "Accepts a bare hostname or a pasted URL (normalized to its bare host). 200 even for\ndomains we've never measured - `tracked: false, air_score: 0` - so the toolbar never has\nto special-case a 404 on the page it's currently looking at.", "summary": "Get a domain's AIR score and ai-files intelligence", "tags": [ "Domain" ], "parameters": [ { "name": "hostname", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Invalid hostname." ] } }, "required": [ "message" ] } } } } } } }, "\/domains\/{hostname}\/ai-files": { "get": { "operationId": "v1.domains.ai-files", "summary": "Raw per-file AI-discoverability rows for a domain (llms.txt & friends, robots.txt AI\nverdicts, homepage JSON-LD). 404s for hostnames with no Domain row at all - unlike show(),\nthis endpoint has nothing useful to synthesize for a domain we've truly never seen", "tags": [ "Domain" ], "parameters": [ { "name": "hostname", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "description": "An error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "examples": [ "Invalid hostname." ] } }, "required": [ "message" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/meta": { "get": { "operationId": "v1.meta", "description": "The single always-safe first call for any integration - tells a caller which dataset\nversion is active, how to read the 1-10 AIR score, and where the generated OpenAPI spec\nlives. Never 404s: DatasetVersion::current() throws when there is no active version, so\nthat case is rescued to a null dataset_version rather than bubbling up as a 404.", "summary": "API metadata: dataset version, score legend, totals, rate limits, and doc links", "tags": [ "Meta" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "score": { "type": "object", "properties": { "scale": { "type": "string" }, "meaning": { "type": "string" }, "gates": { "type": "object", "properties": { "domain_min_occurrences": { "type": "integer" }, "brand_min_mentions": { "type": "integer" }, "phrase_min_observations": { "type": "integer" } }, "required": [ "domain_min_occurrences", "brand_min_mentions", "phrase_min_observations" ] } }, "required": [ "scale", "meaning", "gates" ] }, "totals": { "type": "object", "properties": { "domains_scored": { "type": "integer" }, "brands_scored": { "type": "integer" }, "phrases_scored": { "type": "integer" } }, "required": [ "domains_scored", "brands_scored", "phrases_scored" ] }, "rate_limits": { "type": "object", "properties": { "anonymous_per_minute": { "type": "integer" }, "token_per_minute": { "type": "integer" } }, "required": [ "anonymous_per_minute", "token_per_minute" ] }, "openapi": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "score", "totals", "rate_limits", "openapi", "docs" ] }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } } } } }, "\/phrases": { "get": { "operationId": "v1.phrases.index", "summary": "Ranked phrase list", "tags": [ "Phrase" ], "parameters": [ { "name": "category", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "q", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "array", "items": {} } }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] }, "pagination": { "type": "array", "items": {} } }, "required": [ "dataset_version", "pagination" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/phrases\/{phrase}": { "get": { "operationId": "v1.phrases.show", "description": "`{phrase:slug}` binds on the indexed slug column, not the numeric id.", "summary": "Get a phrase's AIR score, brand leaderboard, and top cited domains", "tags": [ "Phrase" ], "parameters": [ { "name": "phrase", "in": "path", "required": true, "description": "The phrase slug", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": {} }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" } } } }, "\/search": { "get": { "operationId": "v1.search", "summary": "Cross-entity lookup by name\/text - top 5 matching domains, brands, and phrases", "tags": [ "Search" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 100 } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "array", "items": {} } }, "brands": { "type": "array", "items": { "type": "array", "items": {} } }, "phrases": { "type": "array", "items": { "type": "array", "items": {} } } }, "required": [ "domains", "brands", "phrases" ] }, "meta": { "type": "object", "properties": { "dataset_version": { "type": [ "string", "null" ] } }, "required": [ "dataset_version" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } } }, "components": { "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }