{"openapi": "3.1.0", "info": {"title": "AI92 API Integration Portal", "description": "Credit-metered REST API gateway exposing AI92's 8 services (Contact Finder, Promote, SEO, Markets, Build Campaign, Cloud, Reviews, Who-Is-Searching) to external developers.", "version": "1.0.0"}, "paths": {"/v1/health": {"get": {"tags": ["health", "health"], "summary": "Health", "description": "Gateway health check.", "operationId": "health_v1_health_get", "parameters": [{"name": "backends", "in": "query", "required": false, "schema": {"type": "integer", "description": "Set to 1 to additionally probe every backend module's /health endpoint with a 1s timeout. Default 0 to keep the LB probe fast.", "default": 0, "title": "Backends"}, "description": "Set to 1 to additionally probe every backend module's /health endpoint with a 1s timeout. Default 0 to keep the LB probe fast."}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Health V1 Health Get"}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}}, "security": []}}, "/v1/ready": {"get": {"tags": ["health", "health"], "summary": "Ready", "description": "Readiness probe \u2014 same as light health (no backend probe).", "operationId": "ready_v1_ready_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Ready V1 Ready Get"}}}}}, "security": []}}, "/v1/.well-known/jwks.json": {"get": {"tags": ["oauth"], "summary": "OAuth signing keys (JWKS)", "operationId": "jwks_v1__well_known_jwks_json_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Jwks V1  Well Known Jwks Json Get"}}}}}, "security": []}}, "/v1/.well-known/openid-configuration": {"get": {"tags": ["oauth"], "summary": "OIDC discovery document", "operationId": "openid_configuration_v1__well_known_openid_configuration_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Openid Configuration V1  Well Known Openid Configuration Get"}}}}}, "security": []}}, "/v1/oauth/authorize": {"get": {"tags": ["oauth"], "summary": "OAuth Authorization Code flow consent screen", "operationId": "authorize_v1_oauth_authorize_get", "parameters": [{"name": "client_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Client Id"}}, {"name": "redirect_uri", "in": "query", "required": true, "schema": {"type": "string", "title": "Redirect Uri"}}, {"name": "response_type", "in": "query", "required": false, "schema": {"type": "string", "default": "code", "title": "Response Type"}}, {"name": "scope", "in": "query", "required": false, "schema": {"type": "string", "default": "", "title": "Scope"}}, {"name": "state", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "State"}}, {"name": "code_challenge", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Code Challenge"}}, {"name": "code_challenge_method", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Code Challenge Method"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Authorize V1 Oauth Authorize Get"}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}}, "security": []}}, "/v1/oauth/consent": {"post": {"tags": ["oauth"], "summary": "User consent submission", "operationId": "consent_submit_v1_oauth_consent_post", "parameters": [{"name": "client_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Client Id"}}, {"name": "redirect_uri", "in": "query", "required": true, "schema": {"type": "string", "title": "Redirect Uri"}}, {"name": "scope", "in": "query", "required": true, "schema": {"type": "string", "title": "Scope"}}, {"name": "state", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "State"}}, {"name": "code_challenge", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Code Challenge"}}, {"name": "code_challenge_method", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Code Challenge Method"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Consent Submit V1 Oauth Consent Post"}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}}, "security": []}}, "/v1/oauth/token": {"post": {"tags": ["oauth"], "summary": "OAuth token endpoint", "operationId": "token_v1_oauth_token_post", "requestBody": {"content": {"application/x-www-form-urlencoded": {"schema": {"$ref": "#/components/schemas/Body_token_v1_oauth_token_post"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Token V1 Oauth Token Post"}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}}, "security": []}}, "/v1/oauth/revoke": {"post": {"tags": ["oauth"], "summary": "Revoke an OAuth token", "description": "RFC 7009: returns 200 regardless of whether the token existed (prevents enumeration).", "operationId": "revoke_v1_oauth_revoke_post", "requestBody": {"content": {"application/x-www-form-urlencoded": {"schema": {"$ref": "#/components/schemas/Body_revoke_v1_oauth_revoke_post"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Revoke V1 Oauth Revoke Post"}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}}, "security": []}}, "/v1/oauth/introspect": {"post": {"tags": ["oauth"], "summary": "Token introspection", "operationId": "introspect_v1_oauth_introspect_post", "requestBody": {"content": {"application/x-www-form-urlencoded": {"schema": {"$ref": "#/components/schemas/Body_introspect_v1_oauth_introspect_post"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Introspect V1 Oauth Introspect Post"}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}}, "security": []}}, "/v1/oauth/userinfo": {"get": {"tags": ["oauth"], "summary": "OIDC userinfo", "description": "Returns user info scoped to the granted OAuth scopes.\n\nTenant API keys (non-OAuth) don't have a \"user\" in the OAuth sense, so they\nget the account-level claims only.", "operationId": "userinfo_v1_oauth_userinfo_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Userinfo V1 Oauth Userinfo Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/oauth/apps": {"get": {"tags": ["oauth"], "summary": "List the account's OAuth apps", "operationId": "list_apps_v1_oauth_apps_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response List Apps V1 Oauth Apps Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}, "post": {"tags": ["oauth"], "summary": "Register a new OAuth app", "operationId": "create_app_v1_oauth_apps_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateOAuthAppRequest"}}}, "required": true}, "responses": {"201": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Create App V1 Oauth Apps Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/oauth/apps/{client_id}": {"delete": {"tags": ["oauth"], "summary": "Revoke (suspend) an OAuth app", "operationId": "revoke_app_v1_oauth_apps__client_id__delete", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "client_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Client Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Revoke App V1 Oauth Apps  Client Id  Delete"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/account": {"get": {"tags": ["account"], "summary": "Account info + balance", "operationId": "get_account_v1_account_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Get Account V1 Account Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/credits": {"get": {"tags": ["account"], "summary": "Current credit balance", "operationId": "get_credits_v1_account_credits_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Get Credits V1 Account Credits Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/overview": {"get": {"tags": ["account"], "summary": "Dashboard overview: account + usage + subscription + addons", "description": "Single call that powers the My-API dashboard header. Reads are free.\n\nHeavier signals that need other subsystems (webhook delivery rate, full\nStripe subscription period) are returned null/baseline for now and can be\nenriched later without changing the contract.", "operationId": "get_overview_v1_account_overview_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Get Overview V1 Account Overview Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/billing": {"get": {"tags": ["account"], "summary": "Billing snapshot (balance + packages + auto-recharge + recent activity)", "description": "One-shot read powering the My-API billing page: current balance + MTD\nusage, the credit-package catalog, the account's auto-recharge config, and\nthe most recent ledger entries. Invoices are served by /v1/billing/invoices\n(proxied to an internal service); this summary returns an empty list for them so the\npage renders without a cross-module round-trip.", "operationId": "get_billing_v1_account_billing_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Get Billing V1 Account Billing Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/addons": {"get": {"tags": ["account"], "summary": "Add-on entitlements snapshot (Mass Mail + Rank Tracking)", "operationId": "get_addons_v1_account_addons_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Get Addons V1 Account Addons Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/sandbox": {"get": {"tags": ["account"], "summary": "Sandbox key + usage snapshot", "operationId": "get_sandbox_v1_account_sandbox_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Get Sandbox V1 Account Sandbox Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/sandbox/reset": {"post": {"tags": ["account"], "summary": "Rotate the sandbox API key", "description": "Rotate (regenerate) the account's sandbox API key. Revokes the existing\nsandbox key(s) and issues a fresh ``ai92_test_\u2026`` key, returning the\nplaintext ONCE alongside the refreshed ``SandboxState``.\n\nTop-company semantics: a clean key rotation + isolation \u2014 NOT a destructive\nschema wipe. The new plaintext is shown a single time; only its prefix/last4\nare retrievable afterwards.\n\nResponse shape (an internal service ``resetAI92Sandbox``)::\n\n    { state: SandboxState{key_prefix,key_last4,created_at,requests_today,\n                          requests_this_month,success_rate},\n      plaintext: str }", "operationId": "reset_sandbox_v1_account_sandbox_reset_post", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Reset Sandbox V1 Account Sandbox Reset Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/auto-recharge": {"patch": {"tags": ["account"], "summary": "Update auto-recharge config", "operationId": "patch_auto_recharge_v1_account_auto_recharge_patch", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/_AutoRechargePatch"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Patch Auto Recharge V1 Account Auto Recharge Patch"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/addons/rank-tracking/keywords": {"get": {"tags": ["account"], "summary": "List tracked keywords", "operationId": "list_rank_keywords_v1_account_addons_rank_tracking_keywords_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response List Rank Keywords V1 Account Addons Rank Tracking Keywords Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}, "post": {"tags": ["account"], "summary": "Add a tracked keyword", "operationId": "add_rank_keyword_v1_account_addons_rank_tracking_keywords_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/_AddKeywordRequest"}}}, "required": true}, "responses": {"201": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Add Rank Keyword V1 Account Addons Rank Tracking Keywords Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/addons/rank-tracking/keywords/{keyword_id}": {"delete": {"tags": ["account"], "summary": "Remove a tracked keyword", "operationId": "remove_rank_keyword_v1_account_addons_rank_tracking_keywords__keyword_id__delete", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "keyword_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Keyword Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Remove Rank Keyword V1 Account Addons Rank Tracking Keywords  Keyword Id  Delete"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/account/audit/export": {"get": {"tags": ["account"], "summary": "List audit-log export jobs", "operationId": "list_audit_exports_v1_account_audit_export_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"items": {}, "type": "array", "title": "Response List Audit Exports V1 Account Audit Export Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}, "post": {"tags": ["account"], "summary": "Trigger an audit-log CSV export", "description": "Create an audit-log export job. Poll via the\nreturned ``poll_url``; the finished job exposes a signed ``result_url``.", "operationId": "create_audit_export_v1_account_audit_export_post", "requestBody": {"content": {"application/json": {"schema": {"anyOf": [{"$ref": "#/components/schemas/_AuditExportBody"}, {"type": "null"}], "title": "Body"}}}}, "responses": {"202": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Create Audit Export V1 Account Audit Export Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/audit/export/{job_id}/re-export": {"post": {"tags": ["account"], "summary": "Re-run an audit export with the same filters", "operationId": "reexport_audit_v1_account_audit_export__job_id__re_export_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Job Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Reexport Audit V1 Account Audit Export  Job Id  Re Export Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/account/subscription/cancel": {"post": {"tags": ["account"], "summary": "Cancel hybrid subscription at period end", "operationId": "cancel_subscription_v1_account_subscription_cancel_post", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Cancel Subscription V1 Account Subscription Cancel Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/subscription/resume": {"post": {"tags": ["account"], "summary": "Resume a subscription scheduled to cancel", "operationId": "resume_subscription_v1_account_subscription_resume_post", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Resume Subscription V1 Account Subscription Resume Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/addons/mass-mail/cancel": {"post": {"tags": ["account"], "summary": "Cancel the Mass Mail add-on at period end", "operationId": "cancel_mass_mail_v1_account_addons_mass_mail_cancel_post", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Cancel Mass Mail V1 Account Addons Mass Mail Cancel Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/keys": {"get": {"tags": ["account-keys"], "summary": "List API keys", "operationId": "list_keys_v1_account_keys_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"$ref": "#/components/schemas/KeyListResponse"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}, "post": {"tags": ["account-keys"], "summary": "Generate new API key", "operationId": "create_key_v1_account_keys_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeyCreateRequest"}}}, "required": true}, "responses": {"201": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Create Key V1 Account Keys Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/keys/{key_id}": {"get": {"tags": ["account-keys"], "summary": "Get one API key", "operationId": "get_key_v1_account_keys__key_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "key_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Key Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Get Key V1 Account Keys  Key Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}, "patch": {"tags": ["account-keys"], "summary": "Edit key (limits, allowlist)", "operationId": "patch_key_v1_account_keys__key_id__patch", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "key_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Key Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeyPatchRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Patch Key V1 Account Keys  Key Id  Patch"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}, "delete": {"tags": ["account-keys"], "summary": "Revoke API key", "operationId": "revoke_key_v1_account_keys__key_id__delete", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "key_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Key Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/account/usage": {"get": {"tags": ["usage"], "summary": "Usage history + time series (UsageSnapshot)", "description": "Returns the ``UsageSnapshot`` shape the usage panel consumes 1:1, plus\nthe original ``daily_series`` / ``service_breakdown`` fields (kept for\nbackward compatibility with existing callers).\n\nFrontend contract (an internal service ``UsageSnapshot``)::\n\n    { today_credits, today_vs_yesterday_pct, month_credits, balance,\n      avg_response_ms, p95_response_ms,\n      daily_credits_30d:[{day,credits,requests}],\n      by_service:[{service,credits,requests}],\n      recent_requests:[{id,timestamp,method,endpoint,service,status_code,\n                        credits,latency_ms,trace_id}] }", "operationId": "get_usage_v1_account_usage_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "range_days", "in": "query", "required": false, "schema": {"type": "integer", "default": 30, "title": "Range Days"}}, {"name": "service", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Service"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Get Usage V1 Account Usage Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/account/usage/log": {"get": {"tags": ["usage"], "summary": "Activity log (paginated)", "operationId": "get_activity_log_v1_account_usage_log_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "cursor", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Cursor"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "default": 50, "title": "Limit"}}, {"name": "service", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Service"}}, {"name": "status_class", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Status Class"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Get Activity Log V1 Account Usage Log Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/account/usage/export": {"post": {"tags": ["usage"], "summary": "Trigger audit log CSV export", "operationId": "trigger_export_v1_account_usage_export_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ExportRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Trigger Export V1 Account Usage Export Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/account/usage/export/{job_id}": {"get": {"tags": ["usage"], "summary": "Poll audit export job", "operationId": "get_export_status_v1_account_usage_export__job_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Job Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Get Export Status V1 Account Usage Export  Job Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/account/usage/export/{job_id}/download": {"get": {"tags": ["usage"], "summary": "Download an audit export (signed link)", "description": "Token-authenticated export download. The dashboard navigates a\nbrowser straight here, so there's no API key \u2014 a short-lived HMAC token over\n(job_id, exp) is the auth. The CSV is regenerated on demand.", "operationId": "download_export_v1_account_usage_export__job_id__download_get", "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Job Id"}}, {"name": "token", "in": "query", "required": true, "schema": {"type": "string", "title": "Token"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}}, "security": []}}, "/v1/account/provision": {"post": {"tags": ["provision"], "summary": "Provision/fetch the API account for the dashboard user; optionally transfer a brand", "operationId": "provision_account_v1_account_provision_post", "requestBody": {"content": {"application/json": {"schema": {"anyOf": [{"$ref": "#/components/schemas/ProvisionRequest"}, {"type": "null"}], "title": "Body"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Provision Account V1 Account Provision Post"}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}}, "security": []}}, "/v1/webhooks": {"get": {"tags": ["webhooks"], "summary": "List webhook endpoints", "operationId": "list_webhooks_v1_webhooks_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response List Webhooks V1 Webhooks Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}, "post": {"tags": ["webhooks"], "summary": "Create webhook endpoint", "operationId": "create_webhook_v1_webhooks_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookCreateRequest"}}}, "required": true}, "responses": {"201": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Create Webhook V1 Webhooks Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/webhooks/events": {"get": {"tags": ["webhooks"], "summary": "List the webhook event types this gateway emits", "description": "The catalog of event type strings accepted by ``POST /v1/webhooks``. Use\nthese exact values in a webhook's ``events`` array; any other value is\nrejected 422. Declared BEFORE ``/{endpoint_id}`` so it is not captured as an\nendpoint id.", "operationId": "list_webhook_events_v1_webhooks_events_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response List Webhook Events V1 Webhooks Events Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/webhooks/{endpoint_id}": {"get": {"tags": ["webhooks"], "summary": "Get one webhook endpoint", "operationId": "get_webhook_v1_webhooks__endpoint_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "endpoint_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Endpoint Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Get Webhook V1 Webhooks  Endpoint Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}, "delete": {"tags": ["webhooks"], "summary": "Delete webhook endpoint", "operationId": "delete_webhook_v1_webhooks__endpoint_id__delete", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "endpoint_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Endpoint Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}, "patch": {"tags": ["webhooks"], "summary": "Update a webhook endpoint", "description": "Update an existing webhook endpoint's ``url`` / ``description`` / ``events``\n/ ``active`` state. Only fields SENT in the body change (partial PATCH);\nunsent fields are untouched. Scoped to the caller's account.", "operationId": "update_webhook_v1_webhooks__endpoint_id__patch", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "endpoint_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Endpoint Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookUpdateRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Update Webhook V1 Webhooks  Endpoint Id  Patch"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/webhooks/{endpoint_id}/replay": {"post": {"tags": ["webhooks"], "summary": "Replay events to endpoint", "operationId": "replay_endpoint_v1_webhooks__endpoint_id__replay_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "endpoint_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Endpoint Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReplayRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Replay Endpoint V1 Webhooks  Endpoint Id  Replay Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/webhooks/{endpoint_id}/dlq": {"get": {"tags": ["webhooks"], "summary": "List dead-letter deliveries", "operationId": "list_dlq_v1_webhooks__endpoint_id__dlq_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "endpoint_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Endpoint Id"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "default": 50, "title": "Limit"}}, {"name": "cursor", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Cursor"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response List Dlq V1 Webhooks  Endpoint Id  Dlq Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/webhooks/{endpoint_id}/dlq/redrive": {"post": {"tags": ["webhooks"], "summary": "Re-dispatch dead-letter deliveries", "description": "Redrive (resend) deliveries that hit DLQ.\n\nUnlike ``/replay``, this re-tries the **same** delivery rows, so\ncustomer webhook handlers see the same ``X-AI92-Delivery-Id`` and\ncan dedupe naturally. Use ``/replay`` when you want fresh\ndeliveries for a date range.\n\nAuthorization: caller must own the endpoint (account match).", "operationId": "redrive_dlq_endpoint_v1_webhooks__endpoint_id__dlq_redrive_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "endpoint_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Endpoint Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DlqRedriveRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Redrive Dlq Endpoint V1 Webhooks  Endpoint Id  Dlq Redrive Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/billing/checkout": {"post": {"tags": ["billing"], "summary": "Start a credit-package purchase via Stripe", "operationId": "create_checkout_v1_billing_checkout_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CheckoutRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Create Checkout V1 Billing Checkout Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/billing/checkout-custom": {"post": {"tags": ["billing"], "summary": "Pay-as-you-go: buy a custom credit amount", "description": "Start a Stripe Checkout for an arbitrary (PAYG) credit amount. An internal service\nprices it at the floor pack tier and builds a Stripe price_data line item;\non payment its webhook calls the internal_stripe custom-credit receiver.", "operationId": "create_custom_checkout_v1_billing_checkout_custom_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CustomCheckoutRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Create Custom Checkout V1 Billing Checkout Custom Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/billing/invoices": {"get": {"tags": ["billing"], "summary": "List invoices (proxied to an internal service)", "operationId": "list_invoices_v1_billing_invoices_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "cursor", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Cursor"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "default": 50, "title": "Limit"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response List Invoices V1 Billing Invoices Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/billing/invoices/{invoice_id}/pdf": {"get": {"tags": ["billing"], "summary": "Download invoice PDF", "operationId": "get_invoice_pdf_v1_billing_invoices__invoice_id__pdf_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "invoice_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Invoice Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Get Invoice Pdf V1 Billing Invoices  Invoice Id  Pdf Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/billing/subscription": {"get": {"tags": ["billing"], "summary": "Current subscription + tier catalog", "description": "Returns the ``SubscriptionSnapshot`` shape the subscription panel\nconsumes 1:1: ``{ current: CurrentSubscription, available_tiers:\nSubscriptionTierCatalogRow[] }``. ``current`` is composed from the account's\nmost-recent ``Subscription`` row (null-ish when none); ``available_tiers``\nis the static hybrid catalog.", "operationId": "get_subscription_v1_billing_subscription_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Get Subscription V1 Billing Subscription Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}, "post": {"tags": ["billing"], "summary": "Subscribe to hybrid tier", "description": "Start a Stripe Checkout for a hybrid subscription. On payment, an internal service's\nwebhook grants the bundled credits via the internal_stripe receiver.", "operationId": "subscribe_v1_billing_subscription_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/SubscribeRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Subscribe V1 Billing Subscription Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/billing/addons/{kind}": {"post": {"tags": ["billing"], "summary": "Enable subscription add-on", "description": "Start a Stripe Checkout for a monthly add-on (Mass Mail / Rank Tracking).\nOn payment, an internal service's webhook activates the add-on entitlement.", "operationId": "enable_addon_v1_billing_addons__kind__post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "kind", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/SubscriptionAddonKind"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AddonCheckoutRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Enable Addon V1 Billing Addons  Kind  Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/contacts/search": {"get": {"tags": ["contacts"], "summary": "Search contacts (free)", "description": "0 credits \u2014 free warehouse search via an internal service ``internal/search``.\nReturns ``{total, limit, offset, contacts: [...]}``. Each contact carries the\n``person_id`` (use with POST /v1/contacts/reveal and /enrich) and\n``company_id`` (use with GET /v1/contacts/{company_id}) \u2014 this search is where\nthose IDs come from.", "operationId": "search_contacts_v1_contacts_search_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}, {"name": "tags", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Tags"}}, {"name": "email", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Email"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "default": 50, "title": "Limit"}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "default": 0, "title": "Offset"}}, {"name": "title", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Title"}}, {"name": "industry", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Industry"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Search Contacts V1 Contacts Search Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/contacts/reveal": {"post": {"tags": ["contacts"], "summary": "Reveal contact fields (email 3 cr / email+phone 5 cr)", "description": "Reveal a contact's PII by person_id (an internal service S2S).\n\nThe fields to unlock are taken from ``fields`` (e.g. ``[\"email\", \"phone\"]``)\nor, for back-compat, ``mode``/``include_phone``. Requesting ``phone`` unlocks\nemail+phone (5 cr); email-only is 3 cr. A field that the warehouse HAS but the\ncaller did NOT pay to unlock is reported under ``locked_fields`` rather than\nsilently returned empty, so \"exists but gated\" is distinguishable from\n\"absent\".", "operationId": "reveal_contact_v1_contacts_reveal_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/RevealRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Reveal Contact V1 Contacts Reveal Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/contacts/verify": {"post": {"tags": ["contacts"], "summary": "Verify email (1 credit; free if inconclusive)", "description": "Email deliverability via an internal service (a third-party email-verification provider). Charged 1 cr only for a\ndefinitive verdict; an inconclusive ``status='unknown'`` is not charged.", "operationId": "verify_email_v1_contacts_verify_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifyEmailRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Verify Email V1 Contacts Verify Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/contacts/enrich": {"post": {"tags": ["contacts"], "summary": "Full enrichment (5 credits)", "description": "Full contact enrichment (email + phone + firmographics) via an internal service S2S.", "operationId": "enrich_v1_contacts_enrich_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/EnrichRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Enrich V1 Contacts Enrich Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/contacts/bulk": {"post": {"tags": ["contacts"], "summary": "Bulk contact discovery (300 cr per 100)", "description": "Bulk contact discovery via an internal service ``/discover`` (paid). ``filters``\nmust include the discovery keys the backend requires (e.g. ``vertical``,\n``geography``). Cost scales at 300 cr per 100 requested.", "operationId": "bulk_search_v1_contacts_bulk_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BulkSearchRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Bulk Search V1 Contacts Bulk Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/contacts/bulk/{scan_id}": {"get": {"tags": ["contacts"], "summary": "Poll a bulk discovery scan (free)", "description": "Poll a bulk contact discovery job by ``scan_id`` (returned by POST\n/v1/contacts/bulk). Free. Terminal ``status`` = COMPLETED / PARTIAL / FAILED.\nOnce COMPLETED, the discovered contacts are in the warehouse \u2014 retrieve them\nwith GET /v1/contacts/search.", "operationId": "bulk_status_v1_contacts_bulk__scan_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "scan_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Scan Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Bulk Status V1 Contacts Bulk  Scan Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/contacts/{company_id}": {"get": {"tags": ["contacts"], "summary": "Company lookup (2 credits)", "description": "Company by id via an internal service warehouse.", "operationId": "company_lookup_v1_contacts__company_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "company_id", "in": "path", "required": true, "schema": {"type": "string", "description": "Company UUID. Get it from GET /v1/contacts/search \u2014 each contact carries `company_id` (and `company_name`).", "title": "Company Id"}, "description": "Company UUID. Get it from GET /v1/contacts/search \u2014 each contact carries `company_id` (and `company_name`)."}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Company Lookup V1 Contacts  Company Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/campaigns": {"post": {"tags": ["campaigns"], "summary": "Create campaign (free)", "description": "0 credits \u2014 creation is free; credits charge on send.\n\nCarries the customer-typed ``subject`` / ``content`` / ``recipients`` (the\ncomposer payload) through to an internal service so the campaign stores what the\nuser actually wrote. These are best-effort forwarded \u2014 see\n``ModuleBDEClient.create_campaign`` for the BDE-side contract note.", "operationId": "create_campaign_v1_campaigns_post", "security": [{"ApiKeyBearer": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CampaignCreateRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Create Campaign V1 Campaigns Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}, "get": {"tags": ["campaigns"], "summary": "List campaigns for a brand (free)", "description": "0 credits \u2014 enumerate a brand's campaigns, newest first. Fixes the VPE\ngap (no list endpoint \u2192 a lost campaign_id was unrecoverable).", "operationId": "list_campaigns_v1_campaigns_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "default": 50, "title": "Limit"}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "default": 0, "title": "Offset"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response List Campaigns V1 Campaigns Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/campaigns/{campaign_id}": {"patch": {"tags": ["campaigns"], "summary": "Update a campaign \u2014 name / channels (free)", "description": "0 credits \u2014 correct a campaign's name and/or channels. Fixes the VPE gap\n(PATCH /campaigns/{id} was 405 \u2192 campaign state uncorrectable).", "operationId": "patch_campaign_v1_campaigns__campaign_id__patch", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "campaign_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Campaign Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CampaignPatchRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Patch Campaign V1 Campaigns  Campaign Id  Patch"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}, "get": {"tags": ["campaigns"], "summary": "Get campaign (free)", "operationId": "get_campaign_v1_campaigns__campaign_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "campaign_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Campaign Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Get Campaign V1 Campaigns  Campaign Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/campaigns/{campaign_id}/preview": {"get": {"tags": ["campaigns"], "summary": "Preview campaign (free)", "operationId": "preview_campaign_v1_campaigns__campaign_id__preview_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "campaign_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Campaign Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Preview Campaign V1 Campaigns  Campaign Id  Preview Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/campaigns/{campaign_id}/send": {"post": {"tags": ["campaigns"], "summary": "Send campaign (per-channel pricing)", "description": "Cost varies per channel:\n\n  - email     1 credit / message\n  - whatsapp  2 credits / message\n  - sms       3 credits / message\n  - voice     6 credits / message\n\nTwo billing paths:\n\n1. **Reservation (preferred)** \u2014 caller provides ``recipient_ids``:\n   credits are reserved upfront (atomic Redis Lua); backend dispatch\n   runs; on success the actual ``sent_count`` from the backend is\n   reconciled against the reservation and any over-reservation is\n   refunded. Backend 5xx triggers a full refund.\n\n2. **Broadcast (legacy)** \u2014 caller omits ``recipient_ids``: backend\n   broadcasts to the full campaign list. We deduct post-flight using\n   the backend-reported ``sent_count``. Risk: a customer with low\n   balance may end up negative; the reservation path is preferred\n   for that reason.\n\nReturns the backend response augmented with ``channel``, ``cost_per_msg``,\n``credits_charged``, and (reservation path only) ``credits_reserved``\nand ``credits_refunded`` so callers can verify the billing.", "operationId": "dispatch_campaign_v1_campaigns__campaign_id__send_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "campaign_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Campaign Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DispatchRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Dispatch Campaign V1 Campaigns  Campaign Id  Send Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/campaigns/upload-list": {"post": {"tags": ["campaigns"], "summary": "Upload contact list (2 credits per 1K records, rounded up)", "description": "SRS v3.0 \u00a717 \u2014 Upload contact list \u2014 2 cr per 1K records.\n\nCost rounds UP per 1K pack. Includes validation when ``validate_emails=True``\n(the default \u2014 validation is bundled, no extra charge).", "operationId": "upload_list_v1_campaigns_upload_list_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/UploadListRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Upload List V1 Campaigns Upload List Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/seo/snapshot": {"get": {"tags": ["seo"], "summary": "SEO dashboard snapshot for a brand (free)", "description": "0 credits \u2014 free dashboard glance composed into the exact\n``AI92SeoSnapshot`` shape the SEO panel renders (best_rank,\nkeywords_tracked, ai_visibility_pct, audit_score, keywords[], ai_engines[],\ncompetitors[]). Built only from an internal service's FREE reads\n(rankings/regions/ai-visibility/keywords) \u2014 0 credits. The deep, actionable\nproducts (keyword research, backlinks, competitor benchmark, audits) stay\nmetered as the paid actions; this is the free view.\n\nEvery field is always present; any field with no free backend source falls\nback to a safe default (0 / []) so the UI never sees a missing key.", "operationId": "seo_snapshot_v1_seo_snapshot_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Seo Snapshot V1 Seo Snapshot Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/seo/audit": {"post": {"tags": ["seo"], "summary": "Trigger SEO scan/audit for a brand (20 credits)", "description": "Kick off an internal service scan (async). Returns ``{scan_id, ...}``.", "operationId": "seo_audit_v1_seo_audit_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuditRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Seo Audit V1 Seo Audit Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/seo/audit/{scan_id}": {"get": {"tags": ["seo"], "summary": "Poll an SEO audit scan + findings (free)", "description": "Poll status + findings for a scan started by ``POST /audit``. Free (0 cr) so\nthe dashboard can poll to completion and render the results panel instead of a\nstuck 'pending'. The brand is resolved from the gated active\nbrand; an internal service is keyed by ``{brand_id}:{scan_id}``.", "operationId": "seo_audit_status_v1_seo_audit__scan_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "scan_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Scan Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Seo Audit Status V1 Seo Audit  Scan Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/seo/keywords": {"get": {"tags": ["seo"], "summary": "Keyword intelligence for a brand (5 credits)", "operationId": "keywords_v1_seo_keywords_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "default": 100, "title": "Limit"}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "default": 0, "title": "Offset"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Keywords V1 Seo Keywords Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/seo/backlinks": {"get": {"tags": ["seo"], "summary": "Backlink profile for a brand (10 credits)", "operationId": "backlinks_v1_seo_backlinks_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Backlinks V1 Seo Backlinks Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/seo/competitors": {"get": {"tags": ["seo"], "summary": "Competitor benchmark for a brand (30 credits)", "operationId": "competitors_v1_seo_competitors_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}, {"name": "include_untracked", "in": "query", "required": false, "schema": {"type": "boolean", "default": false, "title": "Include Untracked"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Competitors V1 Seo Competitors Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/seo/content-optimize": {"post": {"tags": ["seo"], "summary": "Content optimization (8 credits per page)", "operationId": "content_optimize_v1_seo_content_optimize_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ContentOptimizeRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Content Optimize V1 Seo Content Optimize Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/ai-visibility/{brand_id}": {"get": {"tags": ["ai-visibility"], "summary": "AI-visibility overview (27 credits)", "operationId": "ai_visibility_overview_v1_ai_visibility__brand_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Ai Visibility Overview V1 Ai Visibility  Brand Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/ai-visibility/{brand_id}/competitors": {"get": {"tags": ["ai-visibility"], "summary": "AI-visibility competitors (27 credits)", "operationId": "ai_visibility_competitors_v1_ai_visibility__brand_id__competitors_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}, {"name": "days", "in": "query", "required": false, "schema": {"type": "integer", "default": 30, "title": "Days"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Ai Visibility Competitors V1 Ai Visibility  Brand Id  Competitors Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/ai-visibility/{brand_id}/authority": {"get": {"tags": ["ai-visibility"], "summary": "Domain authority (3 credits)", "operationId": "domain_authority_v1_ai_visibility__brand_id__authority_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Domain Authority V1 Ai Visibility  Brand Id  Authority Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/ai-visibility/{brand_id}/backlinks": {"get": {"tags": ["ai-visibility"], "summary": "Backlink profile (5 credits)", "operationId": "backlinks_v1_ai_visibility__brand_id__backlinks_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Backlinks V1 Ai Visibility  Brand Id  Backlinks Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/ai-visibility/{brand_id}/keywords": {"get": {"tags": ["ai-visibility"], "summary": "Tracked keywords (3 credits)", "operationId": "keywords_v1_ai_visibility__brand_id__keywords_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Keywords V1 Ai Visibility  Brand Id  Keywords Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/ai-visibility/{brand_id}/keywords/research": {"post": {"tags": ["ai-visibility"], "summary": "Keyword research (8 credits)", "operationId": "keyword_research_v1_ai_visibility__brand_id__keywords_research_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KeywordResearchRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Keyword Research V1 Ai Visibility  Brand Id  Keywords Research Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/ai-visibility/{brand_id}/scan": {"post": {"tags": ["ai-visibility"], "summary": "Full site SEO scan (20 credits, async)", "description": "Reserve credits, kick off the scan, and return a pollable job_id.\n\nCredits are *consumed* on success and *refunded* on backend failure\n(JobService). Poll the result at ``/v1/jobs/{job_id}``.", "operationId": "trigger_scan_v1_ai_visibility__brand_id__scan_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "requestBody": {"content": {"application/json": {"schema": {"anyOf": [{"$ref": "#/components/schemas/ScanRequest"}, {"type": "null"}], "title": "Body"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Trigger Scan V1 Ai Visibility  Brand Id  Scan Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/creative/generate": {"post": {"tags": ["creative"], "summary": "Generate creative assets \u2014 image (50 cr) or video (400 cr/8s, +50 cr/s) \u2014 async", "description": "Kick off a prompt-driven render; poll the result at ``/v1/jobs/{job_id}``.\n\nAn internal service renders on Vertex (Imagen 4 Ultra / Veo) which takes ~60-120s, so\nthis returns a ``job_id`` immediately (prefix ``f``) rather than blocking.\nCredits are *reserved* now, *consumed* when the asset renders, and *refunded*\non backend/enqueue failure \u2014 never charge for a non-delivered render.\n\nPrice: image = 50 cr; video = 50 cr/s with an 8s floor (400 cr).", "operationId": "generate_v1_creative_generate_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerateRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Generate V1 Creative Generate Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/creative/assets": {"get": {"tags": ["creative"], "summary": "List generated creative assets (free)", "description": "The account's generated creative assets \u2014 sourced from the completed\ncreative jobs (async_job.result carries the rendered asset URL). An internal service\nstores assets in S3 without a queryable per-brand index, so the gallery is\nbuilt from the job ledger; this survives reloads and is brand-scoped.", "operationId": "list_assets_v1_creative_assets_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response List Assets V1 Creative Assets Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/creative/newsletter": {"post": {"tags": ["creative"], "summary": "Generate newsletter banner (15 credits, async)", "description": "Kick off async banner generation; poll the result at ``/v1/jobs/{job_id}``.\n\nCredits are *consumed* on success and *refunded* on backend failure.", "operationId": "newsletter_v1_creative_newsletter_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/NewsletterRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Newsletter V1 Creative Newsletter Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/creative/campaigns": {"post": {"tags": ["creative"], "summary": "Generate a full creative campaign \u2014 image/video \u2014 for a brand (async, 25 credits)", "description": "Pattern C \u2014 the \"single key, single call\" creative pipeline. Submit one request and poll the returned job at ``GET /v1/jobs/{job_id}`` (job id prefix ``bde``). Credits are reserved on submit, consumed on success, and refunded on any failure.", "operationId": "generate_campaign_v1_creative_campaigns_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CampaignGenerateRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Generate Campaign V1 Creative Campaigns Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/brands": {"get": {"tags": ["brands"], "summary": "List brands (free)", "operationId": "list_brands_v1_brands_get", "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response List Brands V1 Brands Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}, "post": {"tags": ["brands"], "summary": "Register a brand (first free; each extra sub-brand costs credits)", "operationId": "create_brand_v1_brands_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateBrandRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Create Brand V1 Brands Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/brands/{brand_id}/grounding": {"get": {"tags": ["brands"], "summary": "Brand provisioning + grounding status (free)", "description": "0 credits. Tracks a brand from creation to grounded-in-an internal service so the UI\ncan show progress and gate brand-scoped actions until the study completes.\n\nStages: provisioning (no canonical id yet) -> grounding (created, an internal service\nstudy running) -> ready (an internal service intel populated). ``failed`` if an internal service provisioning failed. The grounding probe is best-effort + 0 credits\n(a plain an internal service read, not the metered intel action).", "operationId": "brand_grounding_v1_brands__brand_id__grounding_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Brand Grounding V1 Brands  Brand Id  Grounding Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/brands/{brand_id}": {"get": {"tags": ["brands"], "summary": "Get a brand (free)", "operationId": "get_brand_v1_brands__brand_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Get Brand V1 Brands  Brand Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}, "patch": {"tags": ["brands"], "summary": "Update a brand (free)", "description": "Update safe brand fields. Only fields SENT in the body change (partial\nPATCH via ``model_fields_set``); everything else is untouched. Returns the\nsame serialization as ``GET /v1/brands/{id}``.", "operationId": "update_brand_v1_brands__brand_id__patch", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/UpdateBrandRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Update Brand V1 Brands  Brand Id  Patch"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}, "delete": {"tags": ["brands"], "summary": "Delete a brand (free, idempotent)", "description": "Soft-delete a brand: it disappears from list/get and its scoped products\nstop resolving, but the row is retained (agency brands are account assets\nreferenced across the fleet, so they are never hard-deleted). Idempotent \u2014\ndeleting an already-deleted or unknown brand returns the same confirmation,\nnever a 404, so retries are safe. The upstream an internal service brand is left intact;\nthis only detaches it from the gateway account.", "operationId": "delete_brand_v1_brands__brand_id__delete", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Delete Brand V1 Brands  Brand Id  Delete"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/brands/{brand_id}/readiness": {"get": {"tags": ["brands"], "summary": "Per-product readiness + what's missing (free)", "operationId": "brand_readiness_v1_brands__brand_id__readiness_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Brand Readiness V1 Brands  Brand Id  Readiness Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/brands/{brand_id}/icp": {"post": {"tags": ["brands"], "summary": "Set ICP \u2014 enables Contact Finder (free)", "operationId": "set_icp_v1_brands__brand_id__icp_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/IcpRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Set Icp V1 Brands  Brand Id  Icp Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/brands/{brand_id}/seo": {"post": {"tags": ["brands"], "summary": "Set SEO context \u2014 enables SEO/AI-visibility/markets (free)", "operationId": "set_seo_v1_brands__brand_id__seo_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SeoRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Set Seo V1 Brands  Brand Id  Seo Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/brands/{brand_id}/tracking": {"post": {"tags": ["brands"], "summary": "Get the tracking pixel \u2014 enables Who-Is-Searching (free)", "operationId": "set_tracking_v1_brands__brand_id__tracking_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Set Tracking V1 Brands  Brand Id  Tracking Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/brands/{brand_id}/connections/gbp": {"post": {"tags": ["brands"], "summary": "Start Google Business Profile connection \u2014 enables Reviews (free)", "operationId": "connect_gbp_v1_brands__brand_id__connections_gbp_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/GbpRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Connect Gbp V1 Brands  Brand Id  Connections Gbp Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/brands/{brand_id}/products": {"post": {"tags": ["brands"], "summary": "Add a product (OPTIONAL \u2014 enables creative image\u2192image) (free)", "operationId": "add_product_v1_brands__brand_id__products_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProductRequest"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Add Product V1 Brands  Brand Id  Products Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/markets/snapshot": {"get": {"tags": ["markets"], "summary": "Markets overview (free) \u2014 premium product state + actions", "description": "0 credits. Market reports are generated, premium artifacts (not passively\ncollected data like SEO rankings), so there is no free market *data* here:\nthis returns the panel's CTA/empty state \u2014 the available paid analyses + their\ncredit cost. The customer's last generated report is rendered by the panel\nfrom its last paid call; run an action to (re)generate. (Decision: markets =\npremium product, no free snapshot \u2014 Abel 2026-06-20.)", "operationId": "markets_snapshot_v1_markets_snapshot_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Markets Snapshot V1 Markets Snapshot Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/markets/analyze": {"post": {"tags": ["markets"], "summary": "Comprehensive market report (45 credits)", "operationId": "analyze_v1_markets_analyze_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/AnalyzeRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Analyze V1 Markets Analyze Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/markets/validate": {"post": {"tags": ["markets"], "summary": "Market validation report (15 credits)", "description": "Market-readiness validation for a brand (AI92 is brand-scoped \u2014 no\ncampaign). Backed by an internal service brand-market-validation.", "operationId": "validate_v1_markets_validate_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ValidateRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Validate V1 Markets Validate Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/markets/competitor-intel": {"post": {"tags": ["markets"], "summary": "Competitor intelligence report (25 credits)", "description": "SRS v3.0 \u00a717 \u2014 Competitor intelligence report \u2014 25 cr.\n\nAd spend, channels, strategies, share-of-voice estimates.", "operationId": "competitor_intel_v1_markets_competitor_intel_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CompetitorIntelRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Competitor Intel V1 Markets Competitor Intel Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/markets/predictive": {"post": {"tags": ["markets"], "summary": "Predictive analytics model (40 credits)", "description": "SRS v3.0 \u00a717 \u2014 Predictive analytics model \u2014 40 cr.\n\nAI-driven forecast for the requested metric over the horizon.", "operationId": "predictive_model_v1_markets_predictive_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/PredictiveRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Predictive Model V1 Markets Predictive Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/visitors/identify": {"get": {"tags": ["intent"], "summary": "Brand intent & engagement signals (45 credits per 100)", "description": "Real engagement/intent signals for a brand, from an internal service's click &\nattribution analytics: per-post opens/clicks/engagement (attribution) +\nclick totals, country breakdown and timeline (trial-clicks), keyed by\n``brand_id``.\n\nHonest scoping: this is brand-level engagement, NOT company-level visitor\nde-anonymization (which no backend currently provides). Pass the CANONICAL\nbrand id (slug) so an internal service's attribution resolves (it matches\n``brand_id::text OR canonical_brand_id``).", "operationId": "identify_visitors_v1_visitors_identify_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}, {"name": "campaign_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Campaign Id"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "default": 100, "title": "Limit"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Identify Visitors V1 Visitors Identify Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/intel/brand/{brand_id}": {"get": {"tags": ["intent"], "summary": "Brand intelligence profile (5 credits)", "description": "An internal service brand profile/intel for ``brand_id``.", "operationId": "brand_intel_v1_intel_brand__brand_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Brand Intel V1 Intel Brand  Brand Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/intel/competitor/{brand_id}": {"get": {"tags": ["intent"], "summary": "Competitor intelligence (10 credits)", "description": "An internal service competitor intel for ``brand_id``.", "operationId": "competitor_intel_v1_intel_competitor__brand_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}, {"name": "include_pricing", "in": "query", "required": false, "schema": {"type": "boolean", "default": false, "title": "Include Pricing"}}, {"name": "anonymize", "in": "query", "required": false, "schema": {"type": "boolean", "default": false, "title": "Anonymize"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Competitor Intel V1 Intel Competitor  Brand Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/intel/keywords/{brand_id}": {"get": {"tags": ["intent"], "summary": "Keyword intelligence (5 credits)", "description": "An internal service keyword intel for ``brand_id``.", "operationId": "keyword_intel_v1_intel_keywords__brand_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}, {"name": "start_date", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Start Date"}}, {"name": "end_date", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "End Date"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Keyword Intel V1 Intel Keywords  Brand Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/intel/market/{brand_id}": {"get": {"tags": ["intent"], "summary": "Market intelligence (5 credits)", "description": "An internal service market intel for ``brand_id``.", "operationId": "market_intel_v1_intel_market__brand_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Market Intel V1 Intel Market  Brand Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/intent/signals": {"post": {"tags": ["intent"], "summary": "Intent signal report (5 credits)", "description": "Brand-scoped (or industry-scoped) intent signals from an internal service\n``/public/market-intel``, mapped into the ``AI92IntentSignal[]`` shape the Intent panel renders.\n\nAccepts either ``{brand_id}`` (industry + keywords resolved from the brand's\nICP, the way Hunter/Clearbit infer from context) or an explicit\n``{industry, keywords}``. When a ``brand_id`` is given but the brand has no\nusable context, returns an empty list (not a 422). Charges 5 credits\npost-success (per the decorator).", "operationId": "intent_signals_v1_intent_signals_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntentSignalRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Intent Signals V1 Intent Signals Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/alerts": {"post": {"tags": ["intent"], "summary": "Prospect/industry alert scan (3 credits)", "description": "Scan a business for industry alerts (an internal service /industry-alerts/{id}/scan).", "operationId": "configure_alert_v1_alerts_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProspectAlertRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Configure Alert V1 Alerts Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/intent/enrich": {"post": {"tags": ["intent"], "summary": "Intent-based enrichment (12 credits)", "description": "Enrich via an internal service business-scan for the target brand.", "operationId": "enrich_intent_v1_intent_enrich_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/IntentEnrichRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Enrich Intent V1 Intent Enrich Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/cloud/storage": {"get": {"tags": ["cloud"], "summary": "Data storage (5 credits per GB-month)", "description": "List stored assets. Storage billed at month-end based on observed peak usage.\n\nAn internal service keeps no queryable per-brand asset index, so (like /creative/assets)\nthe listing is built from the account's completed creative jobs.\n\nNOTE: this lists EVERY stored asset for the brand across flows\n(``kind`` = creative / newsletter / gbp / \u2026), whereas the /creative/assets\ngallery filters to ``kind == \"creative\"`` \u2014 so storage can show more than the\ncreative gallery. The ``kind`` field distinguishes them.", "operationId": "list_storage_v1_cloud_storage_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response List Storage V1 Cloud Storage Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/cloud/generate": {"post": {"tags": ["cloud"], "summary": "Generate creative asset", "description": "Prompt-driven rendering is served by POST /v1/creative/generate (async,\nwith reserve->render->refund money-safety + per-key spend caps; poll the\nresult at /v1/jobs/{job_id}). /cloud/generate is retained for compatibility\nand does not itself render \u2014 it points callers at the canonical endpoint\n. No credits are charged here.", "operationId": "generate_asset_v1_cloud_generate_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerateAssetRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Generate Asset V1 Cloud Generate Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/cloud/clean": {"post": {"tags": ["cloud"], "summary": "AI data cleaning (10 credits per 5K)", "operationId": "clean_data_v1_cloud_clean_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CleanRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Clean Data V1 Cloud Clean Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/cloud/sync-import": {"post": {"tags": ["cloud"], "summary": "Data sync/import (3 credits per 1K records, rounded up)", "description": "SRS v3.0 \u00a717 \u2014 Data sync/import \u2014 3 cr per 1K records.\n\nCost rounds UP per 1K pack (mirrors /bulk and /clean conventions).", "operationId": "sync_import_v1_cloud_sync_import_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/SyncImportRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Sync Import V1 Cloud Sync Import Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/cloud/export": {"post": {"tags": ["cloud"], "summary": "Export a brand's data (contacts; SEO/analytics coming)", "description": "Async cross-module data export. Behind CLOUD_EXPORT_ENABLED (OFF until\nverified) \u2014 when off, returns a no-charge 503. Charges per dataset; the job\nis polled at GET /v1/cloud/export/{id} and downloaded via a signed link.", "operationId": "data_export_v1_cloud_export_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/DataExportRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Data Export V1 Cloud Export Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/cloud/export/{export_id}": {"get": {"tags": ["cloud"], "summary": "Poll a data export", "operationId": "get_data_export_v1_cloud_export__export_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "export_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Export Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Get Data Export V1 Cloud Export  Export Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/cloud/segments": {"post": {"tags": ["cloud"], "summary": "Custom audience segment (5 credits)", "description": "SRS v3.0 \u00a717 \u2014 Custom audience segment \u2014 5 cr.\n\nCreates a dynamic or static audience segment from rules.\nDistinct from the existing /generate endpoint (which creates\nAI-generated creative assets \u2014 kept as-is per VPE default).", "operationId": "create_segment_v1_cloud_segments_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/SegmentRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Create Segment V1 Cloud Segments Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/cloud/export/{export_id}/download": {"get": {"tags": ["cloud"], "summary": "Download an export (signed link)", "description": "Token-authenticated download (browser navigates here; no API key). HMAC over\n(export_id, dataset, exp). Payload was produced by the worker + cached in Redis.", "operationId": "download_data_export_v1_cloud_export__export_id__download_get", "parameters": [{"name": "export_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Export Id"}}, {"name": "dataset", "in": "query", "required": true, "schema": {"type": "string", "title": "Dataset"}}, {"name": "token", "in": "query", "required": true, "schema": {"type": "string", "title": "Token"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}}, "security": []}}, "/v1/reviews": {"get": {"tags": ["reviews"], "summary": "List reviews for a brand (free)", "description": "0 credits \u2014 reviews for a brand via an internal service-M ``/api/reviews/brand``.", "operationId": "list_reviews_v1_reviews_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "platform_brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Platform Brand Id"}}, {"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}, {"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "default": 50, "title": "Limit"}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "default": 0, "title": "Offset"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response List Reviews V1 Reviews Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/reviews/testimonials": {"get": {"tags": ["reviews"], "summary": "Testimonials for a brand (free)", "description": "0 credits \u2014 testimonials for a brand the caller owns. Now it\nrequires platform_brand_id and is scoped to the authenticated account.", "operationId": "testimonials_v1_reviews_testimonials_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "platform_brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Platform Brand Id"}}, {"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Testimonials V1 Reviews Testimonials Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/reviews/reply": {"post": {"tags": ["reviews"], "summary": "AI review reply (1 credit)", "operationId": "reply_to_review_v1_reviews_reply_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReplyRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Reply To Review V1 Reviews Reply Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/reviews/request": {"post": {"tags": ["reviews"], "summary": "Review request sent (2 credits)", "operationId": "request_review_v1_reviews_request_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/RequestReviewRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Request Review V1 Reviews Request Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/reviews/analytics": {"get": {"tags": ["reviews"], "summary": "Reputation pulse for a brand (free)", "description": "0 credits \u2014 reputation pulse (rating distribution, 30-day trend, low-rating\n+ unreplied counts, 0-100 score) via an internal service-M\n``GET /api/internal/gbp/reputation/{platform_brand_id}``.", "operationId": "reputation_analytics_v1_reviews_analytics_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "platform_brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Platform Brand Id"}}, {"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Reputation Analytics V1 Reviews Analytics Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/outreach/data": {"get": {"tags": ["outreach"], "summary": "Outreach data for a brand (free)", "description": "0 credits \u2014 the brand's My-Outreach payload (contacts, funnel, variants,\nfeature flags) via an internal service's S2S internal outreach read. ``limit``/``offset``\npaginate the contacts list (integrator audit: the full payload was multiple MB\nand the params were silently ignored).", "operationId": "outreach_data_v1_outreach_data_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}, {"name": "limit", "in": "query", "required": false, "schema": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Limit"}}, {"name": "offset", "in": "query", "required": false, "schema": {"type": "integer", "default": 0, "title": "Offset"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Outreach Data V1 Outreach Data Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/outreach/conversations": {"get": {"tags": ["outreach"], "summary": "List inbound reply conversations for a brand (free)", "description": "0 credits \u2014 the brand's inbound reply conversations, flattened from the\nMy-Outreach payload so a caller can DISCOVER the ``conversation_id`` values to\nuse with ``POST /v1/outreach/reply/suggest|send/{conversation_id}`` (VPE\nfrontend item 7: the reply endpoints took a conversation_id but nothing listed\nthem). A conversation appears once a recipient replies to an outreach email, so\nthe list is empty until there is inbound activity.", "operationId": "outreach_conversations_v1_outreach_conversations_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Outreach Conversations V1 Outreach Conversations Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/outreach/decision/{lead_id}": {"post": {"tags": ["outreach"], "summary": "Approve/reject an outreach draft (free)", "description": "0 credits \u2014 workflow approve/reject of an outreach draft.", "operationId": "outreach_decision_v1_outreach_decision__lead_id__post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "lead_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Lead Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OutreachDecisionBody"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Outreach Decision V1 Outreach Decision  Lead Id  Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/outreach/reply/suggest/{conversation_id}": {"post": {"tags": ["outreach"], "summary": "AI reply suggestion (2 credits)", "description": "2 credits \u2014 brand-grounded AI reply draft. Charged post-success.", "operationId": "outreach_reply_suggest_v1_outreach_reply_suggest__conversation_id__post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "conversation_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Conversation Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OutreachReplySuggestBody"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Outreach Reply Suggest V1 Outreach Reply Suggest  Conversation Id  Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/outreach/reply/send/{conversation_id}": {"post": {"tags": ["outreach"], "summary": "Send an outreach reply (1 credit)", "description": "1 credit (email send). Charged post-success.", "operationId": "outreach_reply_send_v1_outreach_reply_send__conversation_id__post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "conversation_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Conversation Id"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OutreachReplySendBody"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Outreach Reply Send V1 Outreach Reply Send  Conversation Id  Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/outreach/send-mode": {"patch": {"tags": ["outreach"], "summary": "Set outreach send mode (free)", "description": "0 credits \u2014 flip the brand's send mode (AUTO_SEND / REQUIRES_APPROVAL).", "operationId": "outreach_send_mode_v1_outreach_send_mode_patch", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/OutreachSendModeBody"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Outreach Send Mode V1 Outreach Send Mode Patch"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/outreach/generate": {"post": {"tags": ["outreach"], "summary": "AI compose an outreach message (2 credits)", "description": "2 credits \u2014 brand-grounded AI draft for a channel via an internal service K-RAG (the\nsame composer the campaign product uses). Charged post-success; raises 502\n(NOT charged) when K-RAG returns no brand-relevant content.", "operationId": "outreach_generate_v1_outreach_generate_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/OutreachGenerateBody"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Outreach Generate V1 Outreach Generate Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/outreach/newsletter": {"get": {"tags": ["outreach"], "summary": "List the brand's generated newsletters (free)", "description": "0 credits \u2014 the account's newsletters (generated via /v1/creative/newsletter),\nnewest first, optionally filtered to a brand. Sourced from the async jobs the\nAPI customer actually created (not the subscription dispatch).", "operationId": "list_newsletters_v1_outreach_newsletter_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "array", "items": {"type": "object", "additionalProperties": true}, "title": "Response List Newsletters V1 Outreach Newsletter Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/social/status": {"get": {"tags": ["social"], "summary": "Connected social platforms for a brand (free)", "description": "0 credits \u2014 per-platform connection status for the brand.", "operationId": "social_status_v1_social_status_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Social Status V1 Social Status Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/social/{platform}/initiate": {"get": {"tags": ["social"], "summary": "Start an OAuth connect for a platform (free)", "description": "0 credits \u2014 returns the provider ``auth_url`` + state to open in the\nbrowser. An internal service's public state-based callback finishes the connect.", "operationId": "social_initiate_v1_social__platform__initiate_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "platform", "in": "path", "required": true, "schema": {"type": "string", "title": "Platform"}}, {"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}, {"name": "redirect_url", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Redirect Url"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Social Initiate V1 Social  Platform  Initiate Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/social/{platform}/disconnect": {"post": {"tags": ["social"], "summary": "Disconnect a social platform (free)", "description": "0 credits \u2014 revoke + clear the brand's connection for a platform.", "operationId": "social_disconnect_v1_social__platform__disconnect_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "platform", "in": "path", "required": true, "schema": {"type": "string", "title": "Platform"}}, {"name": "brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Brand Id"}}], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/SocialDisconnectBody", "default": {}}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Social Disconnect V1 Social  Platform  Disconnect Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/social/{platform}/publish": {"post": {"tags": ["social"], "summary": "Publish a post to a social platform (5 credits)", "description": "5 credits (Social-Publishing). Charged post-success; if an internal service fails\nthe BackendError handler returns 4xx/503 and nothing is charged. Sandbox is\nfree + no real post (the @charges_credit bypass + ``sandbox`` forwarded to\nthe backend client). Returns the backend response augmented with\n``platform`` and ``credits_charged``.", "operationId": "social_publish_v1_social__platform__publish_post", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "platform", "in": "path", "required": true, "schema": {"type": "string", "title": "Platform"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SocialPublishBody"}}}}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Social Publish V1 Social  Platform  Publish Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/gbp/locations": {"get": {"tags": ["gbp"], "summary": "List GBP locations for a brand (free)", "description": "0 credits \u2014 the brand's connected Google Business locations.", "operationId": "list_locations_v1_gbp_locations_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "platform_brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Platform Brand Id"}}, {"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response List Locations V1 Gbp Locations Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/gbp/posts": {"get": {"tags": ["gbp"], "summary": "List GBP posts for a brand (free)", "description": "0 credits \u2014 the brand's GBP posts, optionally by location/status.", "operationId": "list_posts_v1_gbp_posts_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "platform_brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Platform Brand Id"}}, {"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}, {"name": "location_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Location Id"}}, {"name": "status", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Status"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response List Posts V1 Gbp Posts Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/gbp/posts/preview": {"post": {"tags": ["gbp"], "summary": "Preview a GBP post (free)", "description": "0 credits \u2014 render a preview without publishing.", "operationId": "preview_post_v1_gbp_posts_preview_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/GbpPostBody"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Preview Post V1 Gbp Posts Preview Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/gbp/posts/publish-with-media": {"post": {"tags": ["gbp"], "summary": "Publish a GBP post with media (50 credits)", "description": "50 credits (GBP Posting). Charged post-success; if an internal service-M fails the\nBackendError handler returns 4xx/503 and nothing is charged.", "operationId": "publish_with_media_v1_gbp_posts_publish_with_media_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/GbpPostBody"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Publish With Media V1 Gbp Posts Publish With Media Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/gbp/posts/generate": {"post": {"tags": ["gbp"], "summary": "Generate a GBP post image (50 credits, async)", "description": "Kick off an AI GBP post-image render (an internal service Vertex, ~minutes); poll the\nresult at ``/v1/jobs/{job_id}`` (prefix ``f``). Credits are reserved now,\nconsumed when the image renders and refunded on backend/enqueue failure, so a\nnon-delivered render is never charged. Publish it afterwards via\n``/v1/gbp/posts/publish-with-media``.", "operationId": "generate_post_v1_gbp_posts_generate_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/GbpGenerateBody"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Generate Post V1 Gbp Posts Generate Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/gbp/connection": {"get": {"tags": ["gbp"], "summary": "Google Business connection status for a brand (free)", "description": "0 credits \u2014 whether the brand has a connected Google Business profile +\nits account/location. (Connecting GBP is a follow-up; existing brands are\nconnected via the campaign flow.)", "operationId": "gbp_connection_v1_gbp_connection_get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}, {"name": "platform_brand_id", "in": "query", "required": false, "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Platform Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Gbp Connection V1 Gbp Connection Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/gbp/posts/preview-image": {"post": {"tags": ["gbp"], "summary": "Render an AI image for a GBP draft post (free; async)", "description": "0 credits \u2014 kick off the BDE-M image render (an internal service) for a draft post and\nreturn a ``job_id`` to poll. The GBP post is charged only on publish\n(``/v1/gbp/posts/publish-with-media``), so a previewed-but-unpublished image\nis never charged (money-safe).", "operationId": "preview_image_v1_gbp_posts_preview_image_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/GbpPreviewImageBody"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Preview Image V1 Gbp Posts Preview Image Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/gbp/posts/preview-jobs/{job_id}": {"get": {"tags": ["gbp"], "summary": "Poll a GBP image render job (free)", "description": "0 credits \u2014 status of the GBP image render; when completed it carries the\npublic image URL used at publish time.", "operationId": "preview_job_v1_gbp_posts_preview_jobs__job_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Job Id"}}, {"name": "platform_brand_id", "in": "query", "required": true, "schema": {"type": "string", "title": "Platform Brand Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Preview Job V1 Gbp Posts Preview Jobs  Job Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}, "/v1/campaigns/build": {"post": {"tags": ["build-campaign"], "summary": "AI campaign strategy generation (25 credits)", "operationId": "build_strategy_v1_campaigns_build_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BuildRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Build Strategy V1 Campaigns Build Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/campaigns/generate": {"post": {"tags": ["build-campaign"], "summary": "Assisted campaign \u2014 run strategy + persist a campaign in one call (25 credits)", "description": "The \"Build my campaign\" of the subscription, exposed to pure-API users:\nruns the brand's strategy engine (an internal service an internal service) AND persists a campaign\n(an internal service) linked to it, returning a ``campaign_id`` ready for\nCompose(/optimize)/A-B \u2014 no subscription required. Charges the 25cr strategy\nfee; on any failure ``@charges_credit`` refunds. Requires the brand to have a\nproduct catalog (``POST /v1/brands/{id}/products``).", "operationId": "generate_campaign_v1_campaigns_generate_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/GenerateCampaignRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Generate Campaign V1 Campaigns Generate Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/campaigns/optimize": {"post": {"tags": ["build-campaign"], "summary": "Campaign optimization pass (10 credits)", "operationId": "optimize_campaign_v1_campaigns_optimize_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/OptimizeRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Optimize Campaign V1 Campaigns Optimize Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/campaigns/ab-test": {"post": {"tags": ["build-campaign"], "summary": "A/B test configuration (5 credits)", "description": "SRS v3.0 \u00a717 \u2014 A/B test configuration \u2014 5 cr.\n\nConfigures N variants for an existing campaign with statistical\nsignificance calculations baked in.", "operationId": "ab_test_config_v1_campaigns_ab_test_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ABTestRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Ab Test Config V1 Campaigns Ab Test Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/campaigns/budget-optimize": {"post": {"tags": ["build-campaign"], "summary": "Cross-channel budget optimization (15 credits)", "description": "SRS v3.0 \u00a717 \u2014 Cross-channel budget optimization \u2014 15 cr.\n\nAI-driven allocation of the total budget across the requested channels.", "operationId": "budget_optimize_v1_campaigns_budget_optimize_post", "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BudgetOptimizeRequest"}}}, "required": true}, "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"additionalProperties": true, "type": "object", "title": "Response Budget Optimize V1 Campaigns Budget Optimize Post"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "402": {"description": "Not enough credits (`INSUFFICIENT_CREDITS`) or a per-key spending cap was hit (`KEY_SPENDING_LIMIT`). Pre-flight check \u2014 nothing was charged.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INSUFFICIENT_CREDITS", "message": "Your credit balance is below the cost of this operation.", "status": 402, "documentation_url": "https://docs.ai92.ai/errors/INSUFFICIENT_CREDITS"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}, "security": [{"ApiKeyBearer": []}]}}, "/v1/jobs/{job_id}": {"get": {"tags": ["jobs"], "summary": "Poll async/bulk job status", "description": "Return the status (and, when finished, the result) of an async job.\n\nThe ``job_id`` encodes the originating backend via its prefix\n(``h_<uuid>``, ``g_<uuid>``, \u2026). Returns 404 for unknown ids and for ids\nowned by a different tenant \u2014 existence is never leaked across accounts.", "operationId": "poll_job_v1_jobs__job_id__get", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "title": "Job Id"}}], "responses": {"200": {"description": "Successful Response", "content": {"application/json; charset=utf-8": {"schema": {"type": "object", "additionalProperties": true, "title": "Response Poll Job V1 Jobs  Job Id  Get"}}}}, "401": {"description": "Authentication failed \u2014 `AUTHENTICATION_REQUIRED` (missing or malformed `Authorization: Bearer` header) or `INVALID_API_KEY` (key not found, revoked, expired or from the wrong environment).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "AUTHENTICATION_REQUIRED", "message": "Authorization header missing", "status": 401, "documentation_url": "https://docs.ai92.ai/errors/AUTHENTICATION_REQUIRED"}}}}}, "403": {"description": "Access denied \u2014 e.g. `IP_NOT_ALLOWED` (the key has an IP allowlist) or `FORBIDDEN` (the key's scope does not cover this operation).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "FORBIDDEN", "message": "You do not have access to this resource.", "status": 403, "documentation_url": "https://docs.ai92.ai/errors/FORBIDDEN"}}}}}, "422": {"description": "Validation failed \u2014 `INVALID_REQUEST`. `error.message` lists every offending field (e.g. `\"Field required: client_id\"`).", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "INVALID_REQUEST", "message": "Field required: brand_id", "status": 422, "documentation_url": "https://docs.ai92.ai/errors/INVALID_REQUEST"}}}}}, "429": {"description": "Rate limit exceeded (`RATE_LIMITED`). Back off and retry after the number of seconds in the `Retry-After` header.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}, "example": {"error": {"code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry shortly.", "status": 429, "documentation_url": "https://docs.ai92.ai/errors/RATE_LIMITED"}}}}, "headers": {"Retry-After": {"description": "Seconds to wait before retrying.", "schema": {"type": "integer"}}}}}}}}, "components": {"schemas": {"ABTestRequest": {"properties": {"campaign_id": {"type": "string", "title": "Campaign Id"}, "variant_count": {"type": "integer", "maximum": 8, "minimum": 2, "title": "Variant Count", "default": 2}, "primary_metric": {"type": "string", "title": "Primary Metric", "default": "conversion_rate"}}, "type": "object", "required": ["campaign_id"], "title": "ABTestRequest"}, "AddonCheckoutRequest": {"properties": {"success_url": {"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Success Url"}, "cancel_url": {"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Cancel Url"}}, "type": "object", "required": ["success_url", "cancel_url"], "title": "AddonCheckoutRequest"}, "AnalyzeRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}}, "type": "object", "required": ["brand_id"], "title": "AnalyzeRequest"}, "AuditRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "url": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Url"}}, "type": "object", "required": ["brand_id"], "title": "AuditRequest"}, "Body_introspect_v1_oauth_introspect_post": {"properties": {"token": {"type": "string", "title": "Token"}}, "type": "object", "required": ["token"], "title": "Body_introspect_v1_oauth_introspect_post"}, "Body_revoke_v1_oauth_revoke_post": {"properties": {"token": {"type": "string", "title": "Token"}, "token_type_hint": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Token Type Hint"}}, "type": "object", "required": ["token"], "title": "Body_revoke_v1_oauth_revoke_post"}, "Body_token_v1_oauth_token_post": {"properties": {"grant_type": {"type": "string", "title": "Grant Type"}, "code": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Code"}, "redirect_uri": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Redirect Uri"}, "refresh_token": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Refresh Token"}, "code_verifier": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Code Verifier"}, "client_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Client Id"}, "client_secret": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Client Secret"}}, "type": "object", "required": ["grant_type"], "title": "Body_token_v1_oauth_token_post"}, "BudgetOptimizeRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "total_budget_usd": {"type": "number", "exclusiveMinimum": 0, "title": "Total Budget Usd"}, "channels": {"items": {"type": "string"}, "type": "array", "maxItems": 8, "minItems": 1, "title": "Channels"}}, "type": "object", "required": ["brand_id", "total_budget_usd", "channels"], "title": "BudgetOptimizeRequest"}, "BuildRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "campaign_objective": {"type": "string", "title": "Campaign Objective"}, "budget_usd": {"anyOf": [{"type": "number"}, {"type": "null"}], "title": "Budget Usd"}}, "type": "object", "required": ["brand_id", "campaign_objective"], "title": "BuildRequest"}, "BulkSearchRequest": {"properties": {"filters": {"additionalProperties": true, "type": "object", "title": "Filters"}, "limit": {"type": "integer", "maximum": 10000, "minimum": 10, "title": "Limit", "default": 100}}, "type": "object", "required": ["filters"], "title": "BulkSearchRequest"}, "CampaignCreateRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "name": {"type": "string", "maxLength": 128, "minLength": 1, "title": "Name"}, "channels": {"items": {"type": "string"}, "type": "array", "title": "Channels"}, "subject": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Subject"}, "content": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Content"}, "body": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Body"}, "recipients": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Recipients"}}, "type": "object", "required": ["brand_id", "name"], "title": "CampaignCreateRequest", "description": "Create a campaign shell (0 credits \u2014 billing happens on send).\n\nThe composer UIs (Outreach / Newsletter in an internal service) let the customer\ntype the *content* of the message. Those fields are carried here so the\nbackend persists what the user actually wrote instead of broadcasting a\ntemplate.\n\nField names mirror what ``createAndSendAI92Campaign`` (an internal service\n``services/AI92Service.ts``, PR #760) puts on the wire:\n\n  * ``subject``    \u2014 the message subject line (email/newsletter).\n  * ``content``    \u2014 the message body. Accepted under either ``content``\n                     (what the frontend sends) or ``body`` (alias) so both\n                     spellings work; ``content`` wins if both are present.\n  * ``recipients`` \u2014 an optional list of free-text recipients (email /\n                     phone / handle) the user typed in the composer. These\n                     are NOT contact IDs.\n\nAll four are optional and backward-compatible: existing callers that send\nonly ``{brand_id, name, channels}`` are unaffected."}, "CampaignGenerateRequest": {"properties": {"brand_id": {"type": "string", "minLength": 1, "title": "Brand Id"}, "planning_window_start": {"type": "string", "title": "Planning Window Start", "description": "ISO date, e.g. 2026-06-20"}, "planning_window_end": {"type": "string", "title": "Planning Window End", "description": "ISO date, e.g. 2026-06-27"}, "schedule_type": {"type": "string", "enum": ["MOD80", "MOD60"], "title": "Schedule Type", "default": "MOD80"}, "channels": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Channels"}}, "type": "object", "required": ["brand_id", "planning_window_start", "planning_window_end"], "title": "CampaignGenerateRequest"}, "CampaignPatchRequest": {"properties": {"name": {"anyOf": [{"type": "string", "maxLength": 128, "minLength": 1}, {"type": "null"}], "title": "Name"}, "channels": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Channels", "description": "current_channels"}}, "type": "object", "title": "CampaignPatchRequest"}, "CheckoutRequest": {"properties": {"package_code": {"$ref": "#/components/schemas/CreditPackageCode"}, "success_url": {"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Success Url"}, "cancel_url": {"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Cancel Url"}}, "type": "object", "required": ["package_code", "success_url", "cancel_url"], "title": "CheckoutRequest"}, "CleanRequest": {"properties": {"record_count": {"type": "integer", "title": "Record Count"}}, "type": "object", "required": ["record_count"], "title": "CleanRequest"}, "CompetitorIntelRequest": {"properties": {"primary_brand": {"type": "string", "title": "Primary Brand"}, "competitor_brands": {"items": {"type": "string"}, "type": "array", "maxItems": 10, "minItems": 1, "title": "Competitor Brands"}, "channels": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Channels"}}, "type": "object", "required": ["primary_brand", "competitor_brands"], "title": "CompetitorIntelRequest"}, "ContentOptimizeRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "page_url": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Page Url"}, "target_keyword": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Target Keyword"}}, "type": "object", "required": ["brand_id"], "title": "ContentOptimizeRequest"}, "CreateBrandRequest": {"properties": {"name": {"type": "string", "maxLength": 200, "minLength": 1, "title": "Name"}, "domain": {"anyOf": [{"type": "string", "maxLength": 255}, {"type": "null"}], "title": "Domain"}, "logo_url": {"anyOf": [{"type": "string", "maxLength": 1024}, {"type": "null"}], "title": "Logo Url"}, "brand_colors": {"anyOf": [{"additionalProperties": true, "type": "object"}, {"type": "null"}], "title": "Brand Colors"}, "tone": {"anyOf": [{"type": "string", "maxLength": 64}, {"type": "null"}], "title": "Tone"}, "industry": {"anyOf": [{"type": "string", "maxLength": 100}, {"type": "null"}], "title": "Industry", "description": "Industry/category of the business. Seeds an internal service brand study; an internal service fixes the foundation industry to this value and the research does NOT override it, so a correct value here grounds all generation for a brand-new (non-linked) business."}, "country": {"anyOf": [{"type": "string", "maxLength": 100}, {"type": "null"}], "title": "Country"}, "link_existing_brand_id": {"anyOf": [{"type": "string", "maxLength": 128}, {"type": "null"}], "title": "Link Existing Brand Id", "description": "Link an existing an internal service brand instead of creating one."}}, "type": "object", "required": ["name"], "title": "CreateBrandRequest"}, "CreateOAuthAppRequest": {"properties": {"name": {"type": "string", "maxLength": 128, "minLength": 1, "title": "Name"}, "description": {"anyOf": [{"type": "string", "maxLength": 1024}, {"type": "null"}], "title": "Description"}, "redirect_uris": {"items": {"type": "string"}, "type": "array", "title": "Redirect Uris"}, "scopes": {"items": {"type": "string"}, "type": "array", "title": "Scopes"}}, "type": "object", "required": ["name"], "title": "CreateOAuthAppRequest"}, "CreditPackageCode": {"type": "string", "enum": ["STARTER", "GROWTH", "PROFESSIONAL", "BUSINESS", "ENTERPRISE", "SCALE"], "title": "CreditPackageCode"}, "CustomCheckoutRequest": {"properties": {"credits": {"type": "integer", "maximum": 1000000, "minimum": 1000, "title": "Credits"}, "success_url": {"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Success Url"}, "cancel_url": {"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Cancel Url"}}, "type": "object", "required": ["credits", "success_url", "cancel_url"], "title": "CustomCheckoutRequest", "description": "Pay-as-you-go: buy an arbitrary credit amount (priced server-side by\nan internal service at the floor pack tier)."}, "DataExportRequest": {"properties": {"brand_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}, "dataset": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Dataset"}, "datasets": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Datasets"}, "record_count": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Record Count"}, "format": {"type": "string", "title": "Format", "default": "csv"}, "delivery": {"type": "string", "title": "Delivery", "default": "download"}}, "type": "object", "title": "DataExportRequest"}, "DispatchRequest": {"properties": {"recipient_ids": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Recipient Ids"}, "recipient": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Recipient"}, "channel": {"type": "string", "title": "Channel", "default": "email"}, "subject": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Subject"}, "body": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Body"}, "body_html": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Body Html"}}, "type": "object", "title": "DispatchRequest", "description": "Dispatch a campaign to one channel.\n\nThree mutually-exclusive ways to choose recipients:\n\n* ``recipient_ids`` \u2014 a list of contact IDs. Accurate per-message billing\n  via the reservation pattern (preferred \u2014 cannot over-bill).\n* ``recipient`` \u2014 a single free-text recipient (email / phone / handle)\n  the customer typed in the composer. NOT a contact ID. Billed as exactly\n  one message through the same reservation path (recipient_count = 1).\n* neither \u2014 broadcast to the full campaign list (backward-compatible\n  deduct-post-flight path; backend reports ``sent_count``).\n\n``recipient_ids`` and ``recipient`` cannot both be supplied."}, "DlqRedriveRequest": {"properties": {"delivery_ids": {"items": {"type": "string"}, "type": "array", "maxItems": 500, "title": "Delivery Ids"}, "max_count": {"type": "integer", "maximum": 500, "minimum": 1, "title": "Max Count", "default": 100}}, "type": "object", "title": "DlqRedriveRequest", "description": "Body for ``POST /v1/webhooks/{endpoint_id}/dlq/redrive``.\n\n``delivery_ids`` is optional; omit to redrive every DLQ delivery on\nthe endpoint up to ``max_count`` (oldest first). ``max_count`` caps\nthe redrive at 100 by default so a misconfigured customer can't\nre-trigger thousands of bad deliveries at once."}, "EnrichRequest": {"properties": {"person_id": {"type": "string", "title": "Person Id", "description": "Contact UUID to enrich. Get it from GET /v1/contacts/search \u2014 each result carries `person_id` (an alias of `id`)."}, "fields": {"items": {"type": "string"}, "type": "array", "title": "Fields"}}, "type": "object", "required": ["person_id"], "title": "EnrichRequest"}, "ExportRequest": {"properties": {"since": {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "null"}], "title": "Since"}, "until": {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "null"}], "title": "Until"}, "include_credit_transactions": {"type": "boolean", "title": "Include Credit Transactions", "default": true}, "include_request_log": {"type": "boolean", "title": "Include Request Log", "default": true}}, "type": "object", "title": "ExportRequest"}, "GbpGenerateBody": {"properties": {"platform_brand_id": {"type": "string", "title": "Platform Brand Id"}, "image_brief": {"type": "string", "maxLength": 500, "minLength": 1, "title": "Image Brief"}, "post_text": {"type": "string", "maxLength": 2000, "minLength": 1, "title": "Post Text"}, "post_type": {"type": "string", "title": "Post Type", "default": "STANDARD"}}, "type": "object", "required": ["platform_brand_id", "image_brief", "post_text"], "title": "GbpGenerateBody", "description": "Generate an AI image for a GBP post (mirrors the campaign GBP creative).\nThe caller supplies the post text + a one-line visual brief; an internal service renders\nthe image on Vertex (brand-safety checked)."}, "GbpPostBody": {"properties": {"platform_brand_id": {"type": "string", "title": "Platform Brand Id"}, "location_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Location Id"}, "summary": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Summary"}}, "additionalProperties": true, "type": "object", "required": ["platform_brand_id"], "title": "GbpPostBody"}, "GbpPreviewImageBody": {"properties": {"platform_brand_id": {"type": "string", "title": "Platform Brand Id"}, "post_id": {"type": "integer", "title": "Post Id"}, "image_brief": {"type": "string", "maxLength": 500, "minLength": 1, "title": "Image Brief"}, "post_text": {"type": "string", "title": "Post Text", "default": ""}, "post_type": {"type": "string", "title": "Post Type", "default": "STANDARD"}}, "type": "object", "required": ["platform_brand_id", "post_id", "image_brief"], "title": "GbpPreviewImageBody", "description": "Render an AI image for an existing GBP draft post (campaign-parity flow).\n\nCreate the draft first via ``POST /v1/gbp/posts/preview`` (returns\n``post_id``), call this to render the image, poll\n``/v1/gbp/posts/preview-jobs/{job_id}``, then publish via\n``/v1/gbp/posts/publish-with-media`` with\n``media={\"source\": \"generated\", \"job_id\": ...}``."}, "GbpRequest": {"properties": {"location_ids": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Location Ids"}}, "type": "object", "title": "GbpRequest"}, "GenerateAssetRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "prompt": {"type": "string", "title": "Prompt"}}, "type": "object", "required": ["brand_id", "prompt"], "title": "GenerateAssetRequest"}, "GenerateCampaignRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "campaign_objective": {"type": "string", "title": "Campaign Objective", "default": "lead_gen"}, "channels": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Channels", "description": "current_channels"}, "name": {"anyOf": [{"type": "string", "maxLength": 128}, {"type": "null"}], "title": "Name"}}, "type": "object", "required": ["brand_id"], "title": "GenerateCampaignRequest"}, "GenerateRequest": {"properties": {"brand_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}, "prompt": {"type": "string", "maxLength": 2000, "minLength": 1, "title": "Prompt"}, "asset_type": {"type": "string", "enum": ["image", "video"], "title": "Asset Type", "default": "image"}, "duration_s": {"type": "integer", "enum": [8, 12, 16, 20], "title": "Duration S", "default": 8}}, "type": "object", "required": ["prompt"], "title": "GenerateRequest"}, "IcpRequest": {"properties": {"industries": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Industries"}, "titles": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Titles"}, "geos": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Geos"}, "company_sizes": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Company Sizes"}}, "type": "object", "title": "IcpRequest"}, "IntentEnrichRequest": {"properties": {"intent_signal_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Intent Signal Id"}, "visitor_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Visitor Id"}, "depth": {"type": "string", "title": "Depth", "default": "basic"}, "brand_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}}, "type": "object", "title": "IntentEnrichRequest"}, "IntentSignalRequest": {"properties": {"brand_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Brand Id"}, "industry": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Industry"}, "keywords": {"items": {"type": "string"}, "type": "array", "maxItems": 20, "title": "Keywords"}}, "type": "object", "title": "IntentSignalRequest"}, "KeyCreateRequest": {"properties": {"name": {"type": "string", "maxLength": 128, "minLength": 1, "title": "Name"}, "kind": {"anyOf": [{"type": "string", "pattern": "^(production|sandbox)$"}, {"type": "null"}], "title": "Kind"}, "expires_in_days": {"anyOf": [{"type": "integer", "maximum": 730, "minimum": 1}, {"type": "null"}], "title": "Expires In Days"}, "ip_whitelist": {"items": {"type": "string"}, "type": "array", "title": "Ip Whitelist"}, "daily_credit_limit": {"anyOf": [{"type": "integer", "minimum": 1}, {"type": "null"}], "title": "Daily Credit Limit"}, "monthly_credit_limit": {"anyOf": [{"type": "integer", "minimum": 1}, {"type": "null"}], "title": "Monthly Credit Limit"}, "brand_scope": {"items": {"type": "string"}, "type": "array", "title": "Brand Scope"}}, "type": "object", "required": ["name"], "title": "KeyCreateRequest"}, "KeyListResponse": {"properties": {"keys": {"items": {"additionalProperties": true, "type": "object"}, "type": "array", "title": "Keys"}}, "type": "object", "required": ["keys"], "title": "KeyListResponse"}, "KeyPatchRequest": {"properties": {"name": {"anyOf": [{"type": "string", "maxLength": 128}, {"type": "null"}], "title": "Name"}, "ip_whitelist": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Ip Whitelist"}, "daily_credit_limit": {"anyOf": [{"type": "integer", "minimum": 0}, {"type": "null"}], "title": "Daily Credit Limit"}, "monthly_credit_limit": {"anyOf": [{"type": "integer", "minimum": 0}, {"type": "null"}], "title": "Monthly Credit Limit"}, "brand_scope": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Brand Scope"}}, "type": "object", "title": "KeyPatchRequest"}, "KeywordResearchRequest": {"properties": {"seed_keywords": {"items": {"type": "string"}, "type": "array", "maxItems": 500, "minItems": 1, "title": "Seed Keywords"}, "market": {"type": "string", "title": "Market", "default": "US"}, "language": {"type": "string", "title": "Language", "default": "en"}}, "type": "object", "required": ["seed_keywords"], "title": "KeywordResearchRequest"}, "NewsletterRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "topic": {"type": "string", "maxLength": 500, "minLength": 1, "title": "Topic"}}, "type": "object", "required": ["brand_id", "topic"], "title": "NewsletterRequest"}, "OptimizeRequest": {"properties": {"campaign_id": {"type": "string", "title": "Campaign Id"}, "primary_metric": {"type": "string", "title": "Primary Metric", "default": "conversion_rate"}, "current_channels": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Current Channels"}}, "type": "object", "required": ["campaign_id"], "title": "OptimizeRequest"}, "OutreachDecisionBody": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "decision": {"type": "string", "title": "Decision"}, "reason": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Reason"}}, "type": "object", "required": ["brand_id", "decision"], "title": "OutreachDecisionBody"}, "OutreachGenerateBody": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "channel": {"type": "string", "title": "Channel", "default": "email"}, "brief": {"type": "string", "title": "Brief", "default": ""}}, "type": "object", "required": ["brand_id"], "title": "OutreachGenerateBody"}, "OutreachReplySendBody": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "subject": {"type": "string", "title": "Subject"}, "body_html": {"type": "string", "title": "Body Html"}, "body_text": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Body Text"}, "in_reply_to_message_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "In Reply To Message Id"}}, "type": "object", "required": ["brand_id", "subject", "body_html"], "title": "OutreachReplySendBody"}, "OutreachReplySuggestBody": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "tone": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Tone", "default": "professional"}}, "type": "object", "required": ["brand_id"], "title": "OutreachReplySuggestBody"}, "OutreachSendModeBody": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "send_mode": {"type": "string", "title": "Send Mode"}}, "type": "object", "required": ["brand_id", "send_mode"], "title": "OutreachSendModeBody"}, "PredictiveRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}, "horizon_days": {"type": "integer", "maximum": 365, "minimum": 7, "title": "Horizon Days", "default": 30}, "metric": {"type": "string", "title": "Metric", "default": "roas"}}, "type": "object", "required": ["brand_id"], "title": "PredictiveRequest"}, "ProductRequest": {"properties": {"name": {"type": "string", "maxLength": 255, "minLength": 1, "title": "Name"}, "product_url": {"anyOf": [{"type": "string", "maxLength": 1024}, {"type": "null"}], "title": "Product Url"}, "image_url": {"anyOf": [{"type": "string", "maxLength": 1024}, {"type": "null"}], "title": "Image Url"}, "attributes": {"anyOf": [{"additionalProperties": true, "type": "object"}, {"type": "null"}], "title": "Attributes"}}, "type": "object", "required": ["name"], "title": "ProductRequest"}, "ProspectAlertRequest": {"properties": {"business_id": {"type": "string", "minLength": 1, "title": "Business Id"}, "days_back": {"type": "integer", "maximum": 7, "minimum": 1, "title": "Days Back", "default": 7}, "keyword": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Keyword"}, "industry": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Industry"}, "webhook_url": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Webhook Url"}, "notification_email": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Notification Email"}}, "type": "object", "required": ["business_id"], "title": "ProspectAlertRequest"}, "ProvisionRequest": {"properties": {"link_brand_id": {"anyOf": [{"type": "string", "maxLength": 128}, {"type": "null"}], "title": "Link Brand Id"}, "brand_name": {"anyOf": [{"type": "string", "maxLength": 200}, {"type": "null"}], "title": "Brand Name"}, "brand_domain": {"anyOf": [{"type": "string", "maxLength": 255}, {"type": "null"}], "title": "Brand Domain"}}, "type": "object", "title": "ProvisionRequest"}, "ReplayRequest": {"properties": {"since": {"type": "string", "format": "date-time", "title": "Since"}, "until": {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "null"}], "title": "Until"}, "event_types": {"items": {"type": "string"}, "type": "array", "title": "Event Types"}}, "type": "object", "required": ["since"], "title": "ReplayRequest"}, "ReplyRequest": {"properties": {"review_id": {"type": "string", "title": "Review Id"}, "reply_text": {"type": "string", "title": "Reply Text"}}, "type": "object", "required": ["review_id", "reply_text"], "title": "ReplyRequest"}, "RequestReviewRequest": {"properties": {"location_id": {"type": "string", "title": "Location Id"}, "customer_email": {"type": "string", "title": "Customer Email"}}, "type": "object", "required": ["location_id", "customer_email"], "title": "RequestReviewRequest"}, "RevealRequest": {"properties": {"person_id": {"type": "string", "title": "Person Id", "description": "Contact UUID to unlock. Get it from GET /v1/contacts/search \u2014 each result carries `person_id` (an alias of `id`). Run the free search first, then pass that value here."}, "mode": {"type": "string", "title": "Mode", "default": "email"}, "include_phone": {"type": "boolean", "title": "Include Phone", "default": false}, "fields": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Fields"}}, "type": "object", "required": ["person_id"], "title": "RevealRequest"}, "ScanRequest": {"properties": {"url": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Url"}, "full": {"type": "boolean", "title": "Full", "default": true}}, "type": "object", "title": "ScanRequest"}, "SegmentRequest": {"properties": {"name": {"type": "string", "maxLength": 128, "minLength": 1, "title": "Name"}, "rules": {"additionalProperties": true, "type": "object", "title": "Rules"}, "segment_type": {"type": "string", "title": "Segment Type", "default": "dynamic"}}, "type": "object", "required": ["name", "rules"], "title": "SegmentRequest"}, "SeoRequest": {"properties": {"domain": {"type": "string", "maxLength": 255, "minLength": 1, "title": "Domain"}, "keywords": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Keywords"}, "competitors": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Competitors"}}, "type": "object", "required": ["domain"], "title": "SeoRequest"}, "SocialDisconnectBody": {"properties": {"reason": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Reason"}}, "type": "object", "title": "SocialDisconnectBody"}, "SocialPublishBody": {"properties": {"brand_id": {"type": "string", "minLength": 1, "title": "Brand Id"}, "caption": {"type": "string", "maxLength": 5000, "minLength": 1, "title": "Caption"}, "asset_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Asset Id"}, "media_url": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Media Url"}, "schedule_at": {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "null"}], "title": "Schedule At"}}, "type": "object", "required": ["brand_id", "caption"], "title": "SocialPublishBody", "description": "Publish a single post to a connected social platform.\n\n``asset_id`` references a creative asset already generated for the brand\n(an internal service / Promote); ``media_url`` is an alternative direct media link.\nProvide a ``caption`` always; the two media inputs are optional and a\ntext-only post is allowed. ``schedule_at`` (ISO 8601, future) defers the\npost; omit it to publish immediately."}, "SubscribeRequest": {"properties": {"tier": {"$ref": "#/components/schemas/SubscriptionTier"}, "success_url": {"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Success Url"}, "cancel_url": {"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Cancel Url"}}, "type": "object", "required": ["tier", "success_url", "cancel_url"], "title": "SubscribeRequest"}, "SubscriptionAddonKind": {"type": "string", "enum": ["mass_mail", "rank_tracking_starter", "rank_tracking_pro", "rank_tracking_scale"], "title": "SubscriptionAddonKind"}, "SubscriptionTier": {"type": "string", "enum": ["pro_sub", "business_sub", "enterprise_sub"], "title": "SubscriptionTier"}, "SyncImportRequest": {"properties": {"source": {"type": "string", "maxLength": 64, "minLength": 1, "title": "Source"}, "record_count": {"type": "integer", "minimum": 1, "title": "Record Count"}, "target_brand_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Target Brand Id"}}, "type": "object", "required": ["source", "record_count"], "title": "SyncImportRequest"}, "UpdateBrandRequest": {"properties": {"name": {"anyOf": [{"type": "string", "maxLength": 200, "minLength": 1}, {"type": "null"}], "title": "Name"}, "domain": {"anyOf": [{"type": "string", "maxLength": 255}, {"type": "null"}], "title": "Domain"}, "logo_url": {"anyOf": [{"type": "string", "maxLength": 1024}, {"type": "null"}], "title": "Logo Url"}, "tone": {"anyOf": [{"type": "string", "maxLength": 64}, {"type": "null"}], "title": "Tone"}, "brand_colors": {"anyOf": [{"additionalProperties": true, "type": "object"}, {"type": "null"}], "title": "Brand Colors"}}, "type": "object", "title": "UpdateBrandRequest", "description": "Safe, editable brand fields. Only the keys present in the request body are\napplied (Pydantic v2 ``model_fields_set``), so a partial PATCH never clears an\nunsent field. ``canonical_brand_id`` / account ownership are immutable here."}, "UploadListRequest": {"properties": {"list_name": {"type": "string", "maxLength": 128, "minLength": 1, "title": "List Name"}, "record_count": {"type": "integer", "minimum": 1, "title": "Record Count"}, "source_format": {"type": "string", "title": "Source Format", "default": "csv"}, "validate_emails": {"type": "boolean", "title": "Validate Emails", "default": true}}, "type": "object", "required": ["list_name", "record_count"], "title": "UploadListRequest"}, "ValidateRequest": {"properties": {"brand_id": {"type": "string", "title": "Brand Id"}}, "type": "object", "required": ["brand_id"], "title": "ValidateRequest"}, "VerifyEmailRequest": {"properties": {"email": {"type": "string", "title": "Email"}}, "type": "object", "required": ["email"], "title": "VerifyEmailRequest"}, "WebhookCreateRequest": {"properties": {"url": {"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri", "title": "Url"}, "description": {"anyOf": [{"type": "string", "maxLength": 255}, {"type": "null"}], "title": "Description"}, "events": {"items": {"type": "string"}, "type": "array", "title": "Events"}}, "type": "object", "required": ["url"], "title": "WebhookCreateRequest"}, "WebhookUpdateRequest": {"properties": {"url": {"anyOf": [{"type": "string", "maxLength": 2083, "minLength": 1, "format": "uri"}, {"type": "null"}], "title": "Url"}, "description": {"anyOf": [{"type": "string", "maxLength": 255}, {"type": "null"}], "title": "Description"}, "events": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Events"}, "active": {"anyOf": [{"type": "boolean"}, {"type": "null"}], "title": "Active"}}, "type": "object", "title": "WebhookUpdateRequest", "description": "Editable webhook fields. Only keys present in the body are applied\n(Pydantic v2 ``model_fields_set``), so a partial PATCH never clears an unsent\nfield. ``url`` is validated as an http(s) URL; ``events`` is validated against\nthe catalog; ``active`` toggles delivery without deleting the endpoint."}, "_AddKeywordRequest": {"properties": {"term": {"anyOf": [{"type": "string", "maxLength": 255}, {"type": "null"}], "title": "Term"}, "keywords": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "title": "Keywords"}, "domain": {"anyOf": [{"type": "string", "maxLength": 255}, {"type": "null"}], "title": "Domain"}}, "type": "object", "title": "_AddKeywordRequest"}, "_AuditExportBody": {"properties": {"since": {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "null"}], "title": "Since"}, "until": {"anyOf": [{"type": "string", "format": "date-time"}, {"type": "null"}], "title": "Until"}, "include_credit_transactions": {"type": "boolean", "title": "Include Credit Transactions", "default": true}, "include_request_log": {"type": "boolean", "title": "Include Request Log", "default": true}}, "type": "object", "title": "_AuditExportBody"}, "_AutoRechargePatch": {"properties": {"enabled": {"anyOf": [{"type": "boolean"}, {"type": "null"}], "title": "Enabled"}, "min_balance_threshold": {"anyOf": [{"type": "integer", "minimum": 0}, {"type": "null"}], "title": "Min Balance Threshold"}, "recharge_package_code": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Recharge Package Code"}}, "type": "object", "title": "_AutoRechargePatch"}, "ErrorEnvelope": {"title": "ErrorEnvelope", "type": "object", "required": ["error"], "properties": {"error": {"type": "object", "required": ["code", "message", "status"], "properties": {"code": {"type": "string", "description": "Stable machine-readable error code, e.g. INVALID_REQUEST, AUTHENTICATION_REQUIRED, INVALID_API_KEY, INSUFFICIENT_CREDITS, RATE_LIMITED."}, "message": {"type": "string", "description": "Human-readable explanation of what went wrong."}, "status": {"type": "integer", "description": "HTTP status code, mirrored in the body."}, "documentation_url": {"type": "string", "description": "Link to this error code's documentation page."}}}}}}, "securitySchemes": {"ApiKeyBearer": {"type": "http", "description": "All authenticated requests send ``Authorization: Bearer <token>`` \u2014 an AI92 API key (``ai92_live_*`` live, ``ai92_test_*`` sandbox; same host, the key prefix selects the mode) or an OAuth 2.0 access token.", "scheme": "bearer", "bearerFormat": "AI92 API key (ai92_live_* / ai92_test_*) or OAuth 2.0 access token"}}}, "servers": [{"url": "https://api.ai92.ai", "description": "Production"}, {"url": "https://staging-923.ai92.ai", "description": "Staging"}], "security": [{"ApiKeyBearer": []}]}