{ "openapi": "3.1.0", "info": { "title": "Name.ai API \u2014 public REST API (OpenAPI 3.1)", "version": "1.1.0", "description": "Public, no-authentication-required endpoints for domain search/availability, WHOIS lookup, and TLD pricing/requirements. These are the same endpoints backing the name.ai MCP server (see /.well-known/mcp.json) \u2014 this spec documents them as plain REST for any client that isn't speaking MCP.\n\nVersioning: the unauthenticated endpoints below are the stable public surface and are additive-only (fields are added, never removed or renamed, without a new path). Keyed partner/developer endpoints are URL-path versioned under /api/v1/ (documented below). Deprecations are announced with Deprecation and Sunset response headers (RFC 9745 / RFC 8594) at least 90 days before removal, and in the changelog at https://name.ai/developers. Errors use one typed shape (see components.schemas.Error). List endpoints use offset pagination with a `page` object (limit, offset, total). Rate limits: every public endpoint returns IETF RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset / RateLimit-Policy headers, and 429s carry Retry-After. Retries: send an Idempotency-Key header on POST operations.", "contact": { "url": "https://name.ai/get-in-touch" } }, "servers": [ { "url": "https://name.ai" } ], "paths": { "/api/domain/search": { "post": { "operationId": "searchDomain", "summary": "Check a domain and its alternate-TLD siblings", "description": "Checks the given domain and, for a simple label.tld query, its common alternate TLDs (e.g. querying acme.com also returns acme.ai, acme.io, ...). Streams newline-delimited JSON (NDJSON): one 'header' event, then one 'row' event per domain, a 'primary_done' marker after the queried domain, and a final 'done' event. Buy-now/aftermarket prices are hidden unless the caller has a verified, signed-in session; new-registration pricing is always included.", "security": [ {}, { "oauth2": [ "pricing:read" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string", "description": "Domain to check, e.g. \"example.ai\".", "example": "example.ai" } } } } } }, "responses": { "200": { "description": "NDJSON stream of search events. Include a Bearer access token (scope pricing:read \u2014 see /AUTH.md) to unmask aftermarket/marketplace prices; omit it for the same response with those prices hidden. Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "content": { "application/x-ndjson": { "schema": { "type": "string", "description": "One JSON object per line. `kind` discriminates the event: \"header\" ({request_id, primary, domains, primary_index}), \"row\" ({domain, state, state_label, available, price, listing, whois_summary, cached, meta}), \"primary_done\" (marker, no other fields), or \"done\" ({duration_ms, count})." } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotency-Key": { "$ref": "#/components/headers/Idempotency-Key" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } }, "400": { "description": "q missing or not a valid domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP limit exceeded (60 requests/minute).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/tools/whois": { "post": { "operationId": "whoisLookup", "summary": "WHOIS/RDAP lookup for a domain", "description": "Looks up registrar, registrant, creation/expiration dates, and nameservers via RDAP (falling back to DomainIQ). Rate-limited to 10 lookups/day per caller IP for anonymous callers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "example.com" } } } } } }, "responses": { "201": { "description": "Lookup succeeded. Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "content": { "application/json": { "schema": { "type": "object", "properties": { "lookup": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "domain": { "type": "string" }, "result": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string" }, "registrar": { "type": "string" }, "registrant": { "type": "string" }, "creation_date": { "type": "string" }, "expiration_date": { "type": "string" }, "update_date": { "type": "string" }, "nameservers": { "type": "array", "items": { "type": "string" } }, "emails": { "type": "array", "items": { "type": "string" } }, "raw_source": { "type": "string", "enum": [ "RDAP", "DomainIQ" ] } } }, "created_at": { "type": "string", "format": "date-time" } } }, "used": { "type": "integer" }, "cap": { "type": "integer", "example": 10 }, "remaining": { "type": "integer" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Idempotency-Key": { "$ref": "#/components/headers/Idempotency-Key" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } }, "400": { "description": "Invalid domain name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "WHOIS data unavailable for this domain.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily lookup quota exceeded (10/day per IP for anonymous callers).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/api/pricing/tld": { "get": { "operationId": "tldRegistrationPrice", "summary": "Current price for a TLD lifecycle operation", "description": "New-registration pricing (not an aftermarket/marketplace price) \u2014 never gated by sign-in status.", "parameters": [ { "name": "tld", "in": "query", "required": true, "schema": { "type": "string" }, "example": "ai" }, { "name": "op", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "transfer", "register", "renew", "restore" ], "default": "transfer" } } ], "responses": { "200": { "description": "Price for the requested TLD/operation. Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "content": { "application/json": { "schema": { "type": "object", "properties": { "tld": { "type": "string" }, "op": { "type": "string" }, "priceCents": { "type": [ "integer", "null" ], "description": "USD cents. null if the TLD/op combination isn't supported." } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } }, "400": { "description": "tld missing, or op not one of transfer/register/renew/restore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyError" } } } }, "429": { "description": "Per-IP limit exceeded (120 requests/minute).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } } } }, "/api/tlds/{tld}/metadata": { "get": { "operationId": "tldRequirements", "summary": "Registration requirements for a TLD", "description": "Allowed registration period range, organization/nameserver requirements, and other registry policy, resolved from live registry data.", "parameters": [ { "name": "tld", "in": "path", "required": true, "schema": { "type": "string" }, "example": "ai" } ], "responses": { "200": { "description": "TLD metadata. Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "content": { "application/json": { "schema": { "type": "object", "properties": { "tld": { "type": "string" }, "provider": { "type": "string", "example": "Donuts" }, "periodsMonths": { "type": "array", "items": { "type": "integer" }, "description": "Allowed registration lengths, in months." }, "minPeriodMonths": { "type": "integer" }, "maxPeriodMonths": { "type": "integer" }, "allowedYears": { "type": "array", "items": { "type": "integer" } }, "minYears": { "type": "integer" }, "maxYears": { "type": "integer" }, "organizationRequired": { "type": "boolean" }, "organizationAllowed": { "type": "boolean" }, "allowedCountries": { "type": "array", "items": { "type": "string" }, "description": "Empty array means no country restriction." }, "minNameservers": { "type": "integer" }, "maxNameservers": { "type": "integer" }, "nameserversRequired": { "type": "boolean" }, "idnSupport": { "type": "boolean" }, "premiumSupport": { "type": "string", "example": "REGULAR" }, "transferRequiresAuthcode": { "type": "boolean" }, "featuresAvailable": { "type": "array", "items": { "type": "string", "enum": [ "CREATE", "RENEW", "TRANSFER", "UPDATE", "DELETE", "RESTORE", "PRIVACY_PROTECT" ] } }, "source": { "type": "string", "enum": [ "rtr" ] }, "lastSyncedAt": { "type": "string", "format": "date-time" }, "stale": { "type": "boolean" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } }, "404": { "description": "No metadata available for this TLD.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP limit exceeded (120 requests/minute).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } } } }, "/api/market/listings": { "get": { "operationId": "listMarketListings", "summary": "Browse marketplace (aftermarket) domain listings", "description": "Public. Offset-paginated. Buy-now/floor prices are null unless the caller sends a Bearer token with scope pricing:read (see /auth.md).", "security": [ {}, { "oauth2": [ "pricing:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 24 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "description": "Substring filter on the domain name.", "schema": { "type": "string" } }, { "name": "tld", "in": "query", "schema": { "type": "string" } }, { "name": "max", "in": "query", "description": "Maximum buy-now price, USD.", "schema": { "type": "number" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "newest", "price_asc", "price_desc" ], "default": "newest" } } ], "responses": { "200": { "description": "One page of listings. Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "page" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MarketListing" } }, "page": { "$ref": "#/components/schemas/Page" } } } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } } } } }, "/api/v1/domains/available": { "get": { "operationId": "v1DomainAvailable", "summary": "Marketplace availability for one domain (v1, API key)", "description": "URL-path versioned developer endpoint. Requires x-api-key + x-api-secret headers.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "example": "example.ai" } ], "responses": { "200": { "description": "Availability of the domain on the marketplace. Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "available": { "type": "boolean" }, "locked": { "type": "boolean" }, "bin_price": { "type": [ "number", "null" ] }, "floor_price": { "type": [ "number", "null" ] } } } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } }, "400": { "description": "domain query param required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyError" } } } }, "401": { "description": "Missing or invalid API key/secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyError" } } } } } } }, "/api/tools/{slug}": { "post": { "operationId": "runFreeTool", "summary": "Run a free tool; long-running tools return an async job ticket", "description": "Public. Runs one of the free tools listed at /tools. Fast tools answer 200 with the result inline. Long-running tools (e.g. slug \"seo-crawl\") answer 202 Accepted with a job id and a Location header pointing at the status endpoint to poll.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "seo-crawl" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Tool-specific input (e.g. {\"url\": \"https://example.com\"} for seo-crawl).", "additionalProperties": true } } } }, "responses": { "200": { "description": "Completed inline. Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "cached": { "type": "boolean" }, "result": { "type": "object", "additionalProperties": true } } } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } }, "202": { "description": "Accepted \u2014 the job is running. Poll the Location header (also given as result.status_url). Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "headers": { "Location": { "$ref": "#/components/headers/Location" }, "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "cached": { "type": "boolean", "enum": [ false ] }, "result": { "type": "object", "required": [ "mode", "jobId", "status_url" ], "properties": { "mode": { "type": "string", "enum": [ "async" ] }, "jobId": { "type": "string" }, "status_url": { "type": "string" } } } } } } } }, "400": { "description": "Invalid input for this tool.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown tool slug.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-IP tool quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } } } }, "/api/tools/{slug}/status/{jobId}": { "get": { "operationId": "getFreeToolJobStatus", "summary": "Poll an async tool job", "description": "Returns the current state of a job ticket issued by POST /api/tools/{slug} (202). Keep polling until status is a terminal value.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job state. Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "queued | running | done | failed" }, "result": { "type": "object", "additionalProperties": true }, "error": { "type": "string" } }, "additionalProperties": true } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } }, "400": { "description": "Invalid job id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown tool or job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/domains/bulk/{op}": { "post": { "operationId": "bulkDomainOperation", "summary": "Apply one operation to up to 1,000 domains in a single request", "description": "Requires a signed-in session and ownership of the domains. Free ops (lock, unlock, setNameservers, setFolder, setContacts) fan out asynchronously and return a bulkOpId to track; setAutoRenew updates locally; renew/restore add all items to the cart for one checkout.", "security": [ { "sessionCookie": [] } ], "parameters": [ { "name": "op", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "lock", "unlock", "setNameservers", "setFolder", "setContacts", "setAutoRenew", "renew", "restore" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string" } }, "payload": { "type": "object", "additionalProperties": true, "description": "Op-specific params, e.g. {\"nameservers\": [...]}, {\"years\": 1}, {\"reason\": \"...\"}." }, "options": { "type": "object", "properties": { "skip_on_error": { "type": "boolean", "default": true }, "dry_run": { "type": "boolean", "default": false } } } } } } } }, "responses": { "200": { "description": "Accepted for processing (free ops), applied (setAutoRenew), or added to cart (renew/restore). Deprecation/Sunset/Link headers appear only once the operation is deprecated (see x-deprecation-policy).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "bulkOpId", "total", "op" ], "properties": { "bulkOpId": { "type": "string" }, "total": { "type": "integer" }, "op": { "type": "string" } } }, { "type": "object", "required": [ "updated", "count" ], "properties": { "updated": { "type": "boolean" }, "count": { "type": "integer" } } }, { "type": "object", "required": [ "addedToCart" ], "properties": { "addedToCart": { "type": "boolean" }, "cartItemIds": { "type": "array", "items": { "type": "string" } }, "totalCents": { "type": "integer" }, "checkoutPath": { "type": "string" } } } ] } } }, "headers": { "Deprecation": { "$ref": "#/components/headers/Deprecation" }, "Sunset": { "$ref": "#/components/headers/Sunset" }, "Link": { "$ref": "#/components/headers/Link" } } }, "400": { "description": "Bad op, empty/oversized domains list, or invalid payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not signed in.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "oauth2": { "type": "oauth2", "description": "Optional \u2014 only /api/domain/search reads it, and only to unmask aftermarket prices. Every endpoint in this spec works with no auth at all. See /AUTH.md for the full flow (RFC 7591 dynamic client registration, PKCE required, no client secret).", "flows": { "authorizationCode": { "authorizationUrl": "https://name.ai/oauth/authorize", "tokenUrl": "https://name.ai/api/oauth/token", "scopes": { "pricing:read": "See real marketplace/aftermarket prices instead of the signed-out placeholder." } } } }, "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Developer/partner key. Send x-api-key and x-api-secret headers. Keys are issued self-serve at POST /api/v1/keys by a signed-in user." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "next-auth.session-token", "description": "A signed-in name.ai browser session." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string", "description": "Human-readable explanation." }, "code": { "type": "string", "description": "Machine-readable error code, e.g. bad_request, unauthorized, validation_error, lookup_failed, quota_exceeded, not_found, rate_limited, invalid_grant." } } } } }, "LegacyError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable message (older endpoint shape)." } } }, "Page": { "type": "object", "description": "Offset pagination. Request the next page with offset = offset + limit until offset >= total.", "required": [ "limit", "offset", "total" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "offset": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0, "description": "Total matching items across all pages." } } }, "MarketListing": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "domain": { "type": "string" }, "tld": { "type": "string" }, "price": { "type": "object", "properties": { "bin": { "type": [ "number", "null" ], "description": "Buy-now price in USD. null when the caller is not authenticated with pricing:read." }, "floor": { "type": [ "number", "null" ] }, "currency": { "type": "string", "example": "USD" } } }, "approved": { "type": "boolean" }, "marketplace_visible": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "headers": { "RateLimit-Limit": { "description": "Requests allowed in the current window (IETF RateLimit header fields).", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Quota policy, e.g. \"10;w=86400\".", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying (sent with 429).", "schema": { "type": "integer" } }, "Deprecation": { "description": "Present on deprecated operations (RFC 9745).", "schema": { "type": "string" } }, "Sunset": { "description": "Date after which a deprecated operation is removed (RFC 8594).", "schema": { "type": "string", "format": "date-time" } }, "Idempotency-Key": { "description": "Echo of the request Idempotency-Key.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "\"true\" when this response was replayed from a previous request with the same Idempotency-Key (no new lookup, no quota consumed).", "schema": { "type": "string", "enum": [ "true" ] } }, "Location": { "description": "Where to poll for the result of an accepted asynchronous job.", "schema": { "type": "string" } }, "Link": { "description": "On deprecated operations: ; rel=\"successor-version\" pointing at the replacement.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Malformed or invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-generated unique key (e.g. a UUID) for safe retries. Scoped to the caller. On /api/tools/whois a repeat within 24h replays the stored response without a second lookup or quota hit (Idempotent-Replayed: true); on /api/domain/search the operation is idempotent by nature and the key is echoed.", "schema": { "type": "string", "maxLength": 255 } } } }, "x-api-versioning": { "strategy": "url-path", "current": "v1", "deprecationSignal": [ "Deprecation", "Sunset" ], "minimumNoticeDays": 90 }, "x-deprecation-policy": { "signals": [ "Deprecation", "Sunset", "Link rel=\"deprecation\"" ], "minimumNoticeDays": 90, "changelog": "https://name.ai/developers", "summary": "A deprecated operation returns Deprecation: true and Sunset: on every response for at least 90 days before removal; the replacement is linked via Link: ; rel=\"successor-version\"." } }