{ "openapi": "3.1.0", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "IPConfig Geolocation API", "version": "0.1.0", "summary": "Canonical REST contract for IP geolocation, usage, and API key lifecycle flows.", "description": "Authoritative OpenAPI 3.1 contract for the IPConfig geolocation SaaS. Payload examples are sourced from `@ipconfig/contracts` where possible, while schema components are maintained alongside runtime route behavior to keep SDK, docs, and GPT Action consumers aligned.", "license": { "name": "Proprietary", "url": "https://ipconfig.site/legal" } }, "servers": [ { "url": "https://api.ipconfig.site", "description": "Production API server." }, { "url": "https://staging-api.ipconfig.site", "description": "Staging API server." }, { "url": "http://127.0.0.1:3000", "description": "Local development server." } ], "tags": [ { "name": "Lookup", "description": "Single and batch geolocation lookup operations." }, { "name": "Usage", "description": "Authenticated organization usage and quota reporting." }, { "name": "API Keys", "description": "Self-service API key listing and lifecycle management." } ], "paths": { "/v1/public/lookup": { "post": { "tags": [ "Lookup" ], "operationId": "lookupGuestIp", "summary": "Run a guest lookup.", "description": "Resolve one IP address for an unauthenticated guest user. The server applies the guest daily lookup state machine before the lookup engine and returns explicit `null` values for non-entitled provenance fields.", "security": [], "requestBody": { "required": true, "description": "Guest lookup request payload.", "content": { "application/json": { "examples": { "guest_lookup_request": { "summary": "Guest lookup request example.", "value": { "ip": "8.8.8.8" } } }, "schema": { "$ref": "#/components/schemas/LookupRequest" } } } }, "responses": { "200": { "description": "Successful guest lookup response.", "content": { "application/json": { "examples": { "guest_lookup_success": { "summary": "Guest lookup success example.", "value": { "ip": "8.8.8.8", "ip_version": 4, "release": { "release_label": "2026-04-21-main", "activated_at": "2026-04-21T02:15:00Z" }, "location": { "country_code": "US", "subdivision_1": "California", "subdivision_2": "Santa Clara County", "city_name": "Mountain View", "postal_code": "94043", "timezone_name": "America/Los_Angeles", "latitude": 37.4224, "longitude": -122.0853 }, "network": { "autonomous_system_number": 15169, "autonomous_system_organization": "Google LLC", "isp_name": "Google LLC" }, "provenance": { "country_source": null, "city_source": null, "asn_source": null }, "request_id": "req_01hsz8j7j4v0t0s1n4p3m8f2ac" } } }, "schema": { "$ref": "#/components/schemas/LookupResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableIpError" }, "429": { "description": "Guest daily lookup limit exceeded.", "content": { "application/json": { "examples": { "guest_daily_limit_exceeded": { "summary": "Guest daily limit example.", "value": { "error": { "code": "guest_daily_limit_exceeded", "message": "Guest daily lookup limit reached. Create an account to continue.", "request_id": "req_01ht001q6r2d3w2ab8zn74p4md", "details": { "limit_scope": "rolling_utc_day", "next_lookup_at": "2026-04-24T00:00:00Z", "signup_url": "https://app.geo.example.com/signup" } } } } }, "schema": { "$ref": "#/components/schemas/GuestLimitErrorResponse" } } } }, "503": { "$ref": "#/components/responses/ReleaseUnavailableError" } } } }, "/v1/lookup": { "post": { "tags": [ "Lookup" ], "operationId": "lookupIp", "summary": "Run a single authenticated lookup.", "description": "Resolve one IPv4 or IPv6 address with Bearer API key authentication. Omitted `include` values default to the caller's plan entitlement maximum.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "description": "Authenticated single-lookup request payload.", "content": { "application/json": { "examples": { "single_lookup_request": { "summary": "Single lookup request example.", "value": { "ip": "8.8.8.8", "include": [ "country", "asn", "city", "timezone", "coordinates", "provenance" ], "locale": "en", "response_format": "standard" } } }, "schema": { "$ref": "#/components/schemas/LookupRequest" } } } }, "responses": { "200": { "description": "Successful authenticated lookup response.", "content": { "application/json": { "examples": { "single_lookup_success": { "summary": "Single lookup success example.", "value": { "ip": "8.8.8.8", "ip_version": 4, "release": { "release_label": "2026-04-21-main", "activated_at": "2026-04-21T02:15:00Z" }, "location": { "country_code": "US", "subdivision_1": "California", "subdivision_2": null, "city_name": "Mountain View", "postal_code": "94043", "timezone_name": "America/Los_Angeles", "latitude": 37.4224, "longitude": -122.0853 }, "network": { "autonomous_system_number": 15169, "autonomous_system_organization": "Google LLC", "isp_name": "Google LLC" }, "provenance": { "country_source": "geolite2_geo_whois_asn_country", "city_source": "geolite2_city", "asn_source": "asn" }, "request_id": "req_01hsz8j7j4v0t0s1n4p3m8f2aa" } } }, "schema": { "$ref": "#/components/schemas/LookupResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequestError" }, "401": { "$ref": "#/components/responses/InvalidApiKeyError" }, "403": { "$ref": "#/components/responses/PlanNotEntitledError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableIpError" }, "429": { "description": "Rate limit or monthly quota exceeded.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "Per-second rate-limit rejection example.", "value": { "error": { "code": "rate_limit_exceeded", "message": "Request rate exceeded for the current caller.", "request_id": "req_01ht003q6r2d3w2ab8zn74p4mf", "details": { "retry_after_seconds": 30, "limit_scope": "api_key" } } } }, "monthly_quota_exceeded": { "summary": "Monthly quota rejection example.", "value": { "error": { "code": "monthly_quota_exceeded", "message": "Monthly lookup quota exceeded for the current subscription.", "request_id": "req_01ht002q6r2d3w2ab8zn74p4me", "details": { "plan": "basic", "quota_limit": 10000, "quota_used": 10000, "quota_remaining": 0, "current_period_ends_at": "2026-05-01T00:00:00Z" } } } } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/MonthlyQuotaErrorResponse" } ] } } } }, "503": { "$ref": "#/components/responses/ReleaseUnavailableError" } } } }, "/v1/batch/lookup": { "post": { "tags": [ "Lookup" ], "operationId": "batchLookupIps", "summary": "Run a batch lookup.", "description": "Resolve multiple IP addresses in a single authenticated request. Batch lookup is available only on plans with the `batch_lookup` entitlement, and individual item failures remain embedded in the `results` array.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "description": "Authenticated batch-lookup request payload.", "content": { "application/json": { "examples": { "batch_lookup_request": { "summary": "Batch lookup request example.", "value": { "ips": [ "8.8.8.8", "1.1.1.1" ], "include": [ "country", "asn", "provenance" ], "locale": "en", "response_format": "standard" } } }, "schema": { "$ref": "#/components/schemas/BatchLookupRequest" } } } }, "responses": { "200": { "description": "Successful batch lookup response with ordered per-item results.", "content": { "application/json": { "examples": { "batch_lookup_success": { "summary": "Batch lookup success example.", "value": { "request_id": "req_01hsz9mkg3v0t0s1n4p3m8f2ab", "results": [ { "ip": "8.8.8.8", "status": "ok", "result": { "ip": "8.8.8.8", "ip_version": 4, "release": { "release_label": "2026-04-21-main", "activated_at": "2026-04-21T02:15:00Z" }, "location": { "country_code": "US", "subdivision_1": null, "subdivision_2": null, "city_name": null, "postal_code": null, "timezone_name": null, "latitude": null, "longitude": null }, "network": { "autonomous_system_number": 15169, "autonomous_system_organization": "Google LLC", "isp_name": "Google LLC" }, "provenance": { "country_source": "geolite2_geo_whois_asn_country", "city_source": null, "asn_source": "asn" } }, "error": null }, { "ip": "0.0.0.0", "status": "error", "result": null, "error": { "code": "unprocessable_ip", "message": "IP format accepted syntactically but invalid for lookup.", "request_id": "req_01hsz9mkg3v0t0s1n4p3m8f2ab", "details": null } } ] } } }, "schema": { "$ref": "#/components/schemas/BatchLookupResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequestError" }, "401": { "$ref": "#/components/responses/InvalidApiKeyError" }, "403": { "$ref": "#/components/responses/PlanNotEntitledError" }, "429": { "description": "Rate limit or monthly quota exceeded.", "content": { "application/json": { "examples": { "rate_limit_exceeded": { "summary": "Per-second batch rate-limit rejection example.", "value": { "error": { "code": "rate_limit_exceeded", "message": "Request rate exceeded for the current caller.", "request_id": "req_01ht003q6r2d3w2ab8zn74p4mf", "details": { "retry_after_seconds": 30, "limit_scope": "api_key" } } } }, "monthly_quota_exceeded": { "summary": "Batch quota rejection example.", "value": { "error": { "code": "monthly_quota_exceeded", "message": "Monthly lookup quota exceeded for the current subscription.", "request_id": "req_01ht002q6r2d3w2ab8zn74p4me", "details": { "plan": "basic", "quota_limit": 10000, "quota_used": 10000, "quota_remaining": 0, "current_period_ends_at": "2026-05-01T00:00:00Z" } } } } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/RateLimitErrorResponse" }, { "$ref": "#/components/schemas/MonthlyQuotaErrorResponse" } ] } } } }, "503": { "$ref": "#/components/responses/ReleaseUnavailableError" } } } }, "/v1/me/usage": { "get": { "tags": [ "Usage" ], "operationId": "getUsageSummary", "summary": "Read current usage and quota state.", "description": "Return organization-scoped quota state, usage analytics, top endpoints, and top API keys. Bearer authentication is the canonical machine-access contract for this route.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current usage and quota summary.", "content": { "application/json": { "examples": { "usage_summary_success": { "summary": "Usage summary example.", "value": { "plan": "pro", "quota": { "monthly_limit": 1000000, "monthly_used": 250420, "monthly_remaining": 749580, "current_period_started_at": "2026-04-01T00:00:00Z", "current_period_ends_at": "2026-05-01T00:00:00Z" }, "rate_limit": { "requests_per_second": 100 }, "usage_windows": { "last_24_hours": { "request_count": 14200, "billable_count": 14112, "cache_hit_count": 12543, "db_hit_count": 1657, "cache_hit_ratio": 0.8833 }, "last_7_days": { "request_count": 80120, "billable_count": 79654, "cache_hit_count": 70611, "db_hit_count": 9509, "cache_hit_ratio": 0.8813 }, "last_30_days": { "request_count": 250420, "billable_count": 248940, "cache_hit_count": 220114, "db_hit_count": 30306, "cache_hit_ratio": 0.8789 } }, "top_api_keys": [ { "api_key_id": "11111111-1111-4111-8111-111111111111", "label": "production", "key_mask": "geo_live_****9x3a", "request_count": 121004, "billable_count": 120112 } ], "top_endpoints": [ { "endpoint": "/v1/lookup", "request_count": 240144 }, { "endpoint": "/v1/batch/lookup", "request_count": 10276 } ] } } }, "schema": { "$ref": "#/components/schemas/UsageSummaryResponse" } } } }, "401": { "$ref": "#/components/responses/InvalidApiKeyError" }, "403": { "$ref": "#/components/responses/PlanNotEntitledError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/me/api-keys": { "get": { "tags": [ "API Keys" ], "operationId": "listApiKeys", "summary": "List masked API keys for the current organization.", "description": "Return masked API key metadata for the authenticated organization. Raw bearer secrets are never returned from this route.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Masked API key metadata list.", "content": { "application/json": { "examples": { "api_key_list_success": { "summary": "API key list example.", "value": { "api_keys": [ { "api_key_id": "11111111-1111-4111-8111-111111111111", "label": "production", "status": "active", "key_prefix": "geo_live_0123456789abcde", "key_mask": "geo_live_0123456789abcde...4567", "environment_tag": null, "scopes": [], "created_at": "2026-04-21T10:00:00Z", "last_used_at": "2026-04-23T16:45:00Z", "revoked_at": null, "expires_at": null } ] } } }, "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } } }, "401": { "$ref": "#/components/responses/InvalidApiKeyError" }, "403": { "$ref": "#/components/responses/PlanNotEntitledError" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "tags": [ "API Keys" ], "operationId": "createApiKey", "summary": "Create an API key.", "description": "Create a new API key for the active dashboard organization and return the raw secret exactly once. This route is protected by a NextAuth dashboard session plus RBAC, not bearer authentication. Enterprise-only fields such as `environment_tag` and `scopes` must be omitted unless the caller's plan allows them.", "security": [ { "DashboardSession": [] } ], "requestBody": { "required": true, "description": "API key creation request payload.", "content": { "application/json": { "examples": { "api_key_create_request": { "summary": "API key create request example.", "value": { "label": "staging", "expires_at": null } } }, "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } } }, "responses": { "201": { "description": "Created API key metadata plus one-time secret reveal.", "content": { "application/json": { "examples": { "api_key_create_success": { "summary": "API key create response example.", "value": { "api_key": { "api_key_id": "22222222-2222-4222-8222-222222222222", "label": "staging", "status": "active", "key_prefix": "geo_live_0123456789abcde", "key_mask": "geo_live_0123456789abcde...4567", "environment_tag": null, "scopes": [], "created_at": "2026-04-23T18:20:00Z", "last_used_at": null, "revoked_at": null, "expires_at": null }, "api_key_secret": "geo_live_0123456789abcdef0123456789abcdef01234567" } } }, "schema": { "$ref": "#/components/schemas/ApiKeyCreateResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequestError" }, "401": { "$ref": "#/components/responses/DashboardUnauthorizedError" }, "403": { "description": "Dashboard RBAC or plan gating rejected the request.", "content": { "application/json": { "examples": { "forbidden": { "summary": "Dashboard permission failure example.", "value": { "error": { "code": "forbidden", "message": "You do not have access to this resource.", "request_id": "req_01ht009q6r2d3w2ab8zn74p4ml", "details": null } } }, "plan_not_entitled": { "summary": "Plan gating example.", "value": { "error": { "code": "plan_not_entitled", "message": "The current subscription does not allow this action.", "request_id": "req_01ht000w1b5y8k6r0brp4j2f6p", "details": { "feature": "batch_lookup", "plan": "basic" } } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "409": { "$ref": "#/components/responses/ConflictError" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/me/api-keys/{api_key_id}": { "patch": { "tags": [ "API Keys" ], "operationId": "updateApiKey", "summary": "Pause, rotate, relabel, or revoke an API key.", "description": "Update the lifecycle or display metadata for one API key within the active dashboard organization. This route is protected by a NextAuth dashboard session plus RBAC, not bearer authentication. Rotation returns a replacement key secret exactly once.", "security": [ { "DashboardSession": [] } ], "parameters": [ { "name": "api_key_id", "in": "path", "required": true, "description": "API key identifier for the key being updated.", "schema": { "$ref": "#/components/schemas/ApiKeyId" } } ], "requestBody": { "required": true, "description": "API key update request payload.", "content": { "application/json": { "examples": { "api_key_update_request": { "summary": "API key update request example.", "value": { "label": "production-rotated", "rotate": true } } }, "schema": { "$ref": "#/components/schemas/ApiKeyUpdateRequest" } } } }, "responses": { "200": { "description": "Updated API key metadata and optional one-time rotated secret.", "content": { "application/json": { "examples": { "api_key_update_success": { "summary": "API key update response example.", "value": { "api_key": { "api_key_id": "33333333-3333-4333-8333-333333333333", "label": "production-rotated", "status": "active", "key_prefix": "geo_live_89abcdef0123456", "key_mask": "geo_live_89abcdef0123456...cdef", "environment_tag": null, "scopes": [], "created_at": "2026-04-21T10:00:00Z", "last_used_at": "2026-04-23T16:45:00Z", "revoked_at": null, "expires_at": null }, "api_key_secret": "geo_live_89abcdef0123456789abcdef0123456789abcdef" } } }, "schema": { "$ref": "#/components/schemas/ApiKeyUpdateResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequestError" }, "401": { "$ref": "#/components/responses/DashboardUnauthorizedError" }, "403": { "description": "Dashboard RBAC or plan gating rejected the request.", "content": { "application/json": { "examples": { "forbidden": { "summary": "Dashboard permission failure example.", "value": { "error": { "code": "forbidden", "message": "You do not have access to this resource.", "request_id": "req_01ht00aq6r2d3w2ab8zn74p4mm", "details": null } } }, "plan_not_entitled": { "summary": "Plan gating example.", "value": { "error": { "code": "plan_not_entitled", "message": "The current subscription does not allow this action.", "request_id": "req_01ht000w1b5y8k6r0brp4j2f6p", "details": { "feature": "batch_lookup", "plan": "basic" } } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "409": { "$ref": "#/components/responses/ConflictError" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Machine-to-machine bearer token authentication using an issued API key secret." }, "DashboardSession": { "type": "apiKey", "in": "cookie", "name": "next-auth.session-token", "description": "Browser dashboard session issued by NextAuth.js. Production deployments may use the `__Secure-next-auth.session-token` cookie name." } }, "schemas": { "RequestId": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Stable request identifier for tracing, support, and log correlation." }, "IpAddress": { "type": "string", "format": "ipvanyaddress", "description": "IPv4 or IPv6 address string." }, "IpVersion": { "type": "integer", "enum": [ 4, 6 ], "description": "Resolved IP family as a numeric version.", "x-enumDescriptions": { "4": "Resolved IPv4 address.", "6": "Resolved IPv6 address." } }, "Locale": { "type": "string", "minLength": 2, "maxLength": 35, "description": "Locale hint for human-readable labels only. Core codes never change by locale." }, "ResponseFormat": { "type": "string", "enum": [ "standard" ], "description": "Response format selector. V1 supports `standard` only.", "x-enumDescriptions": { "standard": "Standard JSON response format." } }, "CountryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code." }, "SourceCode": { "type": "string", "pattern": "^[a-z0-9_]+$", "description": "Stable source code used in provenance payloads, docs, and sync logic." }, "ReleaseLabel": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Human-readable unified release label exposed by the API." }, "IsoDateTime": { "type": "string", "format": "date-time", "description": "RFC 3339 date-time string with an explicit UTC offset." }, "PlanCode": { "type": "string", "enum": [ "basic", "pro", "enterprise" ], "description": "Commercial plan code.", "x-enumDescriptions": { "basic": "Basic commercial plan.", "pro": "Pro commercial plan.", "enterprise": "Enterprise commercial plan." } }, "LookupInclude": { "type": "string", "enum": [ "country", "asn", "city", "timezone", "coordinates", "provenance" ], "description": "Additive lookup include flag.", "x-enumDescriptions": { "country": "Country-level location fields.", "asn": "Autonomous system number and organization fields.", "city": "City-level location fields.", "timezone": "IANA timezone field.", "coordinates": "Latitude and longitude fields.", "provenance": "Field-level resolved source metadata." } }, "LookupIncludeList": { "type": "array", "minItems": 1, "maxItems": 6, "uniqueItems": true, "description": "Ordered include list for additive lookup attributes.", "items": { "$ref": "#/components/schemas/LookupInclude" } }, "ErrorCode": { "type": "string", "enum": [ "unauthorized", "forbidden", "invalid_request", "invalid_api_key", "plan_not_entitled", "not_found", "conflict", "unprocessable_ip", "rate_limit_exceeded", "guest_daily_limit_exceeded", "monthly_quota_exceeded", "internal_error", "release_unavailable" ], "description": "Stable API error code.", "x-enumDescriptions": { "unauthorized": "Dashboard authentication is required.", "forbidden": "Authenticated caller lacks the required dashboard permission.", "invalid_request": "Validation failure.", "invalid_api_key": "Missing or bad bearer token.", "plan_not_entitled": "Feature exists but plan does not allow it.", "not_found": "Requested resource or IP result not found.", "conflict": "Lifecycle or mutation conflict.", "unprocessable_ip": "IP format accepted syntactically but invalid for lookup.", "rate_limit_exceeded": "Per-second request rate exceeded.", "guest_daily_limit_exceeded": "Guest already used the free daily lookup.", "monthly_quota_exceeded": "Authenticated monthly quota exhausted.", "internal_error": "Unexpected server failure.", "release_unavailable": "No active release is available for lookups." } }, "ApiKeyId": { "type": "string", "format": "uuid", "description": "API key identifier." }, "ApiKeyStatus": { "type": "string", "enum": [ "active", "paused", "revoked", "rotated", "expired" ], "description": "Lifecycle status for an API key.", "x-enumDescriptions": { "active": "The key can be used normally.", "paused": "The key exists but is temporarily disabled.", "revoked": "The key is permanently revoked.", "rotated": "The key has been replaced by a newer key.", "expired": "The key reached its expiration time." } }, "ApiErrorPayload": { "type": "object", "additionalProperties": false, "description": "Shared error payload envelope for API failures.", "required": [ "code", "message", "request_id", "details" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode", "description": "Stable API error code." }, "message": { "type": "string", "minLength": 1, "description": "Human-readable error summary suitable for developers and LLM agents." }, "request_id": { "$ref": "#/components/schemas/RequestId", "description": "Stable request identifier for tracing, support, and log correlation." }, "details": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Nullable structured context for troubleshooting, quota messaging, or UI actions." } } }, "ApiErrorResponse": { "type": "object", "additionalProperties": false, "description": "Shared error response envelope.", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ApiErrorPayload", "description": "Structured API error payload." } } }, "GuestLimitErrorDetails": { "type": "object", "additionalProperties": false, "description": "Guest lookup limit details.", "required": [ "limit_scope", "next_lookup_at", "signup_url" ], "properties": { "limit_scope": { "type": "string", "enum": [ "rolling_utc_day" ], "description": "Guest lookup window. V1 allows one successful lookup per rolling UTC day.", "x-enumDescriptions": { "rolling_utc_day": "One successful lookup per UTC day." } }, "next_lookup_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Next time the guest lookup window should allow a new successful attempt." }, "signup_url": { "type": [ "string", "null" ], "format": "uri", "description": "Optional signup or upgrade URL used by the landing page CTA." } } }, "GuestLimitErrorResponse": { "type": "object", "additionalProperties": false, "description": "Guest daily lookup limit error response.", "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "request_id", "details" ], "properties": { "code": { "type": "string", "enum": [ "guest_daily_limit_exceeded" ], "description": "Stable guest-limit error code.", "x-enumDescriptions": { "guest_daily_limit_exceeded": "Guest daily lookup limit exceeded." } }, "message": { "type": "string", "minLength": 1, "description": "Human-readable guest-limit error summary." }, "request_id": { "$ref": "#/components/schemas/RequestId", "description": "Stable request identifier for tracing, support, and log correlation." }, "details": { "$ref": "#/components/schemas/GuestLimitErrorDetails", "description": "Guest daily limit details." } } } } }, "MonthlyQuotaErrorDetails": { "type": "object", "additionalProperties": false, "description": "Monthly quota rejection details.", "required": [ "plan", "quota_limit", "quota_used", "quota_remaining", "current_period_ends_at" ], "properties": { "plan": { "$ref": "#/components/schemas/PlanCode", "description": "Commercial plan code." }, "quota_limit": { "type": [ "integer", "null" ], "minimum": 0, "description": "Monthly plan quota ceiling. Null means the limit is contract-defined." }, "quota_used": { "type": "integer", "minimum": 0, "description": "Authoritative number of lookups consumed in the current period." }, "quota_remaining": { "type": [ "integer", "null" ], "minimum": 0, "description": "Remaining monthly quota after the current rejection." }, "current_period_ends_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Quota reset time for the current plan period." } } }, "MonthlyQuotaErrorResponse": { "type": "object", "additionalProperties": false, "description": "Monthly quota exceeded error response.", "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "request_id", "details" ], "properties": { "code": { "type": "string", "enum": [ "monthly_quota_exceeded" ], "description": "Stable monthly quota error code.", "x-enumDescriptions": { "monthly_quota_exceeded": "Authenticated monthly quota exhausted." } }, "message": { "type": "string", "minLength": 1, "description": "Human-readable monthly quota error summary." }, "request_id": { "$ref": "#/components/schemas/RequestId", "description": "Stable request identifier for tracing, support, and log correlation." }, "details": { "$ref": "#/components/schemas/MonthlyQuotaErrorDetails", "description": "Monthly quota details." } } } } }, "RateLimitErrorDetails": { "type": "object", "additionalProperties": false, "description": "Rate-limit rejection details.", "required": [ "retry_after_seconds", "limit_scope" ], "properties": { "retry_after_seconds": { "type": [ "integer", "null" ], "minimum": 0, "description": "Recommended wait time before retrying the same route." }, "limit_scope": { "type": "string", "enum": [ "guest", "api_key", "organization" ], "description": "Server-side rate-limit bucket that rejected the request.", "x-enumDescriptions": { "guest": "Guest caller rate-limit bucket.", "api_key": "Per-API-key rate-limit bucket.", "organization": "Organization-wide rate-limit bucket." } } } }, "RateLimitErrorResponse": { "type": "object", "additionalProperties": false, "description": "Rate limit exceeded error response.", "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message", "request_id", "details" ], "properties": { "code": { "type": "string", "enum": [ "rate_limit_exceeded" ], "description": "Stable rate-limit error code.", "x-enumDescriptions": { "rate_limit_exceeded": "Per-second request rate exceeded." } }, "message": { "type": "string", "minLength": 1, "description": "Human-readable rate-limit error summary." }, "request_id": { "$ref": "#/components/schemas/RequestId", "description": "Stable request identifier for tracing, support, and log correlation." }, "details": { "$ref": "#/components/schemas/RateLimitErrorDetails", "description": "Rate-limit details." } } } } }, "LookupRequest": { "type": "object", "additionalProperties": false, "description": "Single-lookup request payload.", "required": [ "ip" ], "properties": { "ip": { "$ref": "#/components/schemas/IpAddress", "description": "IPv4 or IPv6 address string." }, "include": { "oneOf": [ { "$ref": "#/components/schemas/LookupIncludeList" }, { "type": "null" } ], "description": "Optional include list. Omitted values default to the caller's entitlement maximum." }, "locale": { "oneOf": [ { "$ref": "#/components/schemas/Locale" }, { "type": "null" } ], "description": "Locale hint for human-readable labels only. Core codes never change." }, "response_format": { "oneOf": [ { "$ref": "#/components/schemas/ResponseFormat" }, { "type": "null" } ], "description": "Response format selector. Omit to use the V1 default." } } }, "LookupRelease": { "type": "object", "additionalProperties": false, "description": "Active unified release metadata returned with a lookup result.", "required": [ "release_label", "activated_at" ], "properties": { "release_label": { "$ref": "#/components/schemas/ReleaseLabel", "description": "Human-readable unified release label exposed by the API." }, "activated_at": { "$ref": "#/components/schemas/IsoDateTime", "description": "Timestamp when this unified release became active." } } }, "LookupLocation": { "type": "object", "additionalProperties": false, "description": "Location fields resolved for the requested IP address.", "required": [ "country_code", "subdivision_1", "subdivision_2", "city_name", "postal_code", "timezone_name", "latitude", "longitude" ], "properties": { "country_code": { "oneOf": [ { "$ref": "#/components/schemas/CountryCode" }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2 country code. Null means unavailable or not entitled." }, "subdivision_1": { "type": [ "string", "null" ], "minLength": 1, "description": "Top-level subdivision name. Null means unavailable or not entitled." }, "subdivision_2": { "type": [ "string", "null" ], "minLength": 1, "description": "Second-level subdivision name. Null means unavailable or not entitled." }, "city_name": { "type": [ "string", "null" ], "minLength": 1, "description": "City name. Null means unavailable or not entitled." }, "postal_code": { "type": [ "string", "null" ], "minLength": 1, "description": "Postal or ZIP code. Null means unavailable or not entitled." }, "timezone_name": { "type": [ "string", "null" ], "minLength": 1, "description": "IANA timezone name. Null means unavailable or not entitled." }, "latitude": { "type": [ "number", "null" ], "minimum": -90, "maximum": 90, "description": "Latitude in decimal degrees. Null means unavailable or not entitled." }, "longitude": { "type": [ "number", "null" ], "minimum": -180, "maximum": 180, "description": "Longitude in decimal degrees. Null means unavailable or not entitled." } } }, "LookupNetwork": { "type": "object", "additionalProperties": false, "description": "Network and ASN fields resolved for the requested IP address.", "required": [ "autonomous_system_number", "autonomous_system_organization", "isp_name" ], "properties": { "autonomous_system_number": { "type": [ "integer", "null" ], "minimum": 0, "description": "Autonomous system number. Null means unavailable or not entitled." }, "autonomous_system_organization": { "type": [ "string", "null" ], "minLength": 1, "description": "Autonomous system organization name. Null means unavailable or not entitled." }, "isp_name": { "type": [ "string", "null" ], "minLength": 1, "description": "Resolved ISP or network name. Null means unavailable or not entitled." } } }, "LookupProvenance": { "type": "object", "additionalProperties": false, "description": "Field-level source attribution metadata for a lookup result.", "required": [ "country_source", "city_source", "asn_source" ], "properties": { "country_source": { "oneOf": [ { "$ref": "#/components/schemas/SourceCode" }, { "type": "null" } ], "description": "Resolved source code for country attribution. Null means unavailable or omitted." }, "city_source": { "oneOf": [ { "$ref": "#/components/schemas/SourceCode" }, { "type": "null" } ], "description": "Resolved source code for city attribution. Null means unavailable or omitted." }, "asn_source": { "oneOf": [ { "$ref": "#/components/schemas/SourceCode" }, { "type": "null" } ], "description": "Resolved source code for ASN attribution. Null means unavailable or omitted." } } }, "LookupPayload": { "type": "object", "additionalProperties": false, "description": "Lookup result payload without the top-level request identifier.", "required": [ "ip", "ip_version", "release", "location", "network", "provenance" ], "properties": { "ip": { "$ref": "#/components/schemas/IpAddress", "description": "IPv4 or IPv6 address string." }, "ip_version": { "$ref": "#/components/schemas/IpVersion", "description": "Resolved IP family as a numeric version." }, "release": { "$ref": "#/components/schemas/LookupRelease", "description": "Active unified release metadata returned with the lookup result." }, "location": { "$ref": "#/components/schemas/LookupLocation", "description": "Location fields resolved for the requested IP address." }, "network": { "$ref": "#/components/schemas/LookupNetwork", "description": "Network and ASN fields resolved for the requested IP address." }, "provenance": { "$ref": "#/components/schemas/LookupProvenance", "description": "Field-level source attribution metadata for the lookup result." } } }, "LookupResponse": { "type": "object", "additionalProperties": false, "description": "Successful single-lookup response payload.", "required": [ "request_id", "ip", "ip_version", "release", "location", "network", "provenance" ], "properties": { "request_id": { "$ref": "#/components/schemas/RequestId", "description": "Stable request identifier for tracing, support, and log correlation." }, "ip": { "$ref": "#/components/schemas/IpAddress", "description": "IPv4 or IPv6 address string." }, "ip_version": { "$ref": "#/components/schemas/IpVersion", "description": "Resolved IP family as a numeric version." }, "release": { "$ref": "#/components/schemas/LookupRelease", "description": "Active unified release metadata returned with the lookup result." }, "location": { "$ref": "#/components/schemas/LookupLocation", "description": "Location fields resolved for the requested IP address." }, "network": { "$ref": "#/components/schemas/LookupNetwork", "description": "Network and ASN fields resolved for the requested IP address." }, "provenance": { "$ref": "#/components/schemas/LookupProvenance", "description": "Field-level source attribution metadata for the lookup result." } } }, "BatchLookupRequest": { "type": "object", "additionalProperties": false, "description": "Batch-lookup request payload.", "required": [ "ips" ], "properties": { "ips": { "type": "array", "minItems": 1, "description": "One or more IPv4 or IPv6 addresses to resolve in a single batch request.", "items": { "$ref": "#/components/schemas/IpAddress" } }, "include": { "oneOf": [ { "$ref": "#/components/schemas/LookupIncludeList" }, { "type": "null" } ], "description": "Optional include list applied to every IP in the batch." }, "locale": { "oneOf": [ { "$ref": "#/components/schemas/Locale" }, { "type": "null" } ], "description": "Locale hint for human-readable labels only. Core codes never change." }, "response_format": { "oneOf": [ { "$ref": "#/components/schemas/ResponseFormat" }, { "type": "null" } ], "description": "Response format selector. Omit to use the V1 default." } } }, "BatchLookupItem": { "type": "object", "additionalProperties": false, "description": "Per-item batch lookup result.", "required": [ "ip", "status", "result", "error" ], "properties": { "ip": { "$ref": "#/components/schemas/IpAddress", "description": "Requested IP address for this batch item." }, "status": { "type": "string", "enum": [ "ok", "error" ], "description": "Per-item resolution status within the batch response.", "x-enumDescriptions": { "ok": "The batch item resolved successfully.", "error": "The batch item failed and includes a structured error payload." } }, "result": { "oneOf": [ { "$ref": "#/components/schemas/LookupPayload" }, { "type": "null" } ], "description": "Resolved lookup payload when `status` is `ok`; otherwise null." }, "error": { "oneOf": [ { "$ref": "#/components/schemas/ApiErrorPayload" }, { "type": "null" } ], "description": "Per-item error payload when `status` is `error`; otherwise null." } } }, "BatchLookupResponse": { "type": "object", "additionalProperties": false, "description": "Successful batch lookup response payload.", "required": [ "request_id", "results" ], "properties": { "request_id": { "$ref": "#/components/schemas/RequestId", "description": "Stable request identifier for tracing, support, and log correlation." }, "results": { "type": "array", "description": "Ordered batch resolution results matching the submitted IP sequence.", "items": { "$ref": "#/components/schemas/BatchLookupItem" } } } }, "QuotaSnapshot": { "type": "object", "additionalProperties": false, "description": "Current quota state for the authenticated organization.", "required": [ "monthly_limit", "monthly_used", "monthly_remaining", "current_period_started_at", "current_period_ends_at" ], "properties": { "monthly_limit": { "type": [ "integer", "null" ], "minimum": 0, "description": "Monthly lookup quota limit. Null means contract-defined or unlimited." }, "monthly_used": { "type": "integer", "minimum": 0, "description": "Authoritative monthly lookup usage counted in PostgreSQL." }, "monthly_remaining": { "type": [ "integer", "null" ], "minimum": 0, "description": "Remaining monthly lookup allowance. Null means no numeric ceiling is exposed." }, "current_period_started_at": { "$ref": "#/components/schemas/IsoDateTime", "description": "Start of the current billing or quota accounting window." }, "current_period_ends_at": { "$ref": "#/components/schemas/IsoDateTime", "description": "End of the current billing or quota accounting window." } } }, "RateLimitSnapshot": { "type": "object", "additionalProperties": false, "description": "Effective rate-limit state for the authenticated organization.", "required": [ "requests_per_second" ], "properties": { "requests_per_second": { "type": [ "integer", "null" ], "minimum": 1, "description": "Effective per-second rate limit. Null means contract-defined or custom." } } }, "UsageWindow": { "type": "object", "additionalProperties": false, "description": "Aggregated usage metrics for one reporting window.", "required": [ "request_count", "billable_count", "cache_hit_count", "db_hit_count", "cache_hit_ratio" ], "properties": { "request_count": { "type": "integer", "minimum": 0, "description": "Total requests served in the reported time window." }, "billable_count": { "type": "integer", "minimum": 0, "description": "Billable lookups recorded in the reported time window." }, "cache_hit_count": { "type": "integer", "minimum": 0, "description": "Number of lookups served from Redis-backed caches in the window." }, "db_hit_count": { "type": "integer", "minimum": 0, "description": "Number of lookups that required PostgreSQL resolution in the window." }, "cache_hit_ratio": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "Cache hit ratio as a 0-1 decimal. Null means no requests were served in the window." } } }, "ApiKeyUsageSummary": { "type": "object", "additionalProperties": false, "description": "Top API key usage summary row.", "required": [ "api_key_id", "label", "key_mask", "request_count", "billable_count" ], "properties": { "api_key_id": { "$ref": "#/components/schemas/ApiKeyId", "description": "API key identifier." }, "label": { "type": "string", "minLength": 1, "description": "Display label for a top-usage API key." }, "key_mask": { "type": "string", "minLength": 4, "maxLength": 32, "description": "Masked API key display value for dashboard usage summaries." }, "request_count": { "type": "integer", "minimum": 0, "description": "Requests attributed to this API key in the summary window." }, "billable_count": { "type": "integer", "minimum": 0, "description": "Billable requests attributed to this API key in the summary window." } } }, "EndpointUsageSummary": { "type": "object", "additionalProperties": false, "description": "Top endpoint usage summary row.", "required": [ "endpoint", "request_count" ], "properties": { "endpoint": { "type": "string", "minLength": 1, "description": "Normalized API route identifier such as `/v1/lookup`." }, "request_count": { "type": "integer", "minimum": 0, "description": "Requests served for the endpoint in the summary window." } } }, "UsageSummaryResponse": { "type": "object", "additionalProperties": false, "description": "Authenticated organization usage and quota summary response.", "required": [ "plan", "quota", "rate_limit", "usage_windows", "top_api_keys", "top_endpoints" ], "properties": { "plan": { "$ref": "#/components/schemas/PlanCode", "description": "Commercial plan code." }, "quota": { "$ref": "#/components/schemas/QuotaSnapshot", "description": "Current quota state for the authenticated organization." }, "rate_limit": { "$ref": "#/components/schemas/RateLimitSnapshot", "description": "Effective rate-limit state for the authenticated organization." }, "usage_windows": { "type": "object", "additionalProperties": false, "description": "Aggregated usage windows used by the dashboard analytics surfaces.", "required": [ "last_24_hours", "last_7_days", "last_30_days" ], "properties": { "last_24_hours": { "$ref": "#/components/schemas/UsageWindow", "description": "Usage metrics for the last 24 hours." }, "last_7_days": { "$ref": "#/components/schemas/UsageWindow", "description": "Usage metrics for the last 7 days." }, "last_30_days": { "$ref": "#/components/schemas/UsageWindow", "description": "Usage metrics for the last 30 days." } } }, "top_api_keys": { "type": "array", "description": "Top API keys by request volume for the authenticated organization.", "items": { "$ref": "#/components/schemas/ApiKeyUsageSummary" } }, "top_endpoints": { "type": "array", "description": "Top endpoints by request volume for the authenticated organization.", "items": { "$ref": "#/components/schemas/EndpointUsageSummary" } } } }, "EnvironmentTag": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9_-]*$", "description": "Display-safe environment tag for enterprise key management." }, "ApiKeyScope": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9:_-]+$", "description": "Display-safe API key scope token." }, "ApiKeyScopeList": { "type": "array", "description": "Optional enterprise-only API key scopes.", "items": { "$ref": "#/components/schemas/ApiKeyScope" } }, "ApiKeyMetadata": { "type": "object", "additionalProperties": false, "description": "Masked API key metadata shown in dashboard and usage views.", "required": [ "api_key_id", "label", "status", "key_prefix", "key_mask", "environment_tag", "scopes", "created_at", "last_used_at", "revoked_at", "expires_at" ], "properties": { "api_key_id": { "$ref": "#/components/schemas/ApiKeyId", "description": "API key identifier." }, "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display label shown in the dashboard and usage analytics." }, "status": { "$ref": "#/components/schemas/ApiKeyStatus", "description": "Lifecycle status for an API key." }, "key_prefix": { "type": "string", "minLength": 4, "maxLength": 24, "description": "Display-safe token prefix used to identify a key without revealing the secret." }, "key_mask": { "type": "string", "minLength": 4, "maxLength": 32, "description": "Masked API key display value shown after creation and in dashboard listings." }, "environment_tag": { "$ref": "#/components/schemas/EnvironmentTag", "description": "Optional enterprise environment tag such as `production` or `staging`." }, "scopes": { "$ref": "#/components/schemas/ApiKeyScopeList", "description": "Optional enterprise scopes attached to the key." }, "created_at": { "$ref": "#/components/schemas/IsoDateTime", "description": "Key creation timestamp." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last successful use of the key. Null means never used." }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Revocation timestamp. Null means the key is not revoked." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional expiration timestamp. Null means no explicit expiration is set." } } }, "ApiKeyListResponse": { "type": "object", "additionalProperties": false, "description": "API key list response for the authenticated organization.", "required": [ "api_keys" ], "properties": { "api_keys": { "type": "array", "description": "Dashboard-visible API key list for the authenticated organization.", "items": { "$ref": "#/components/schemas/ApiKeyMetadata" } } } }, "ApiKeyCreateRequest": { "type": "object", "additionalProperties": false, "description": "API key creation request payload.", "required": [ "label" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display label for the new API key." }, "environment_tag": { "$ref": "#/components/schemas/EnvironmentTag", "description": "Optional enterprise-only environment tag. Omit unless the caller's plan allows tagged keys." }, "scopes": { "$ref": "#/components/schemas/ApiKeyScopeList", "description": "Optional enterprise-only scope restrictions for the new API key." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional expiration timestamp. Use null to create a non-expiring key." } } }, "ApiKeyCreateResponse": { "type": "object", "additionalProperties": false, "description": "API key creation response with one-time secret reveal.", "required": [ "api_key", "api_key_secret" ], "properties": { "api_key": { "$ref": "#/components/schemas/ApiKeyMetadata", "description": "Masked API key metadata for the created key." }, "api_key_secret": { "type": "string", "minLength": 12, "description": "One-time revealed bearer secret. It must not be returned after creation." } } }, "ApiKeyUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "API key update request payload. At least one field must be provided, and `rotate` and `revoke` must not both be true in the same request.", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 120, "description": "New dashboard label for the API key." }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Lifecycle update that activates or pauses the key.", "x-enumDescriptions": { "active": "Activate the key.", "paused": "Pause the key." } }, "rotate": { "type": "boolean", "description": "When true, rotates the key secret and returns a one-time replacement secret." }, "revoke": { "type": "boolean", "description": "When true, revokes the key permanently." }, "environment_tag": { "$ref": "#/components/schemas/EnvironmentTag", "description": "Optional enterprise-only replacement environment tag. Omit unless the caller's plan allows tagged keys." }, "scopes": { "$ref": "#/components/schemas/ApiKeyScopeList", "description": "Optional enterprise-only replacement scope list for the API key." } } }, "ApiKeyUpdateResponse": { "type": "object", "additionalProperties": false, "description": "API key update response with optional one-time rotated secret reveal.", "required": [ "api_key", "api_key_secret" ], "properties": { "api_key": { "$ref": "#/components/schemas/ApiKeyMetadata", "description": "Masked API key metadata after the update is applied." }, "api_key_secret": { "type": [ "string", "null" ], "minLength": 12, "description": "One-time replacement secret returned only when a rotation occurred." } } } }, "responses": { "InvalidRequestError": { "description": "Validation failure.", "content": { "application/json": { "examples": { "invalid_request": { "summary": "Invalid request example.", "value": { "error": { "code": "invalid_request", "message": "Request validation failed.", "request_id": "req_01ht000w1b5y8k6r0brp4j2f6m", "details": { "field": "ip", "issue": "Must be a valid IPv4 or IPv6 address string." } } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "InvalidApiKeyError": { "description": "Missing or bad bearer token.", "content": { "application/json": { "examples": { "invalid_api_key": { "summary": "Invalid API key example.", "value": { "error": { "code": "invalid_api_key", "message": "Authorization header is required.", "request_id": "req_01ht000w1b5y8k6r0brp4j2f6n", "details": { "auth_scheme": "bearer", "key_prefix": null, "reason": "missing_bearer_token" } } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "DashboardUnauthorizedError": { "description": "Dashboard session is missing or invalid.", "content": { "application/json": { "examples": { "unauthorized": { "summary": "Dashboard session required example.", "value": { "error": { "code": "unauthorized", "message": "Dashboard authentication is required.", "request_id": "req_01ht008q6r2d3w2ab8zn74p4mk", "details": null } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "PlanNotEntitledError": { "description": "Feature exists but the current plan does not allow it.", "content": { "application/json": { "examples": { "plan_not_entitled": { "summary": "Plan gating example.", "value": { "error": { "code": "plan_not_entitled", "message": "The current subscription does not allow this action.", "request_id": "req_01ht000w1b5y8k6r0brp4j2f6p", "details": { "feature": "batch_lookup", "plan": "basic" } } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "NotFoundError": { "description": "Requested resource or IP result not found.", "content": { "application/json": { "examples": { "not_found": { "summary": "Not found example.", "value": { "error": { "code": "not_found", "message": "Requested resource was not found.", "request_id": "req_01ht004q6r2d3w2ab8zn74p4mg", "details": null } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "ConflictError": { "description": "Lifecycle or mutation conflict.", "content": { "application/json": { "examples": { "conflict": { "summary": "Conflict example.", "value": { "error": { "code": "conflict", "message": "The current subscription has reached its active API key limit.", "request_id": "req_01ht005q6r2d3w2ab8zn74p4mh", "details": null } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "UnprocessableIpError": { "description": "IP format accepted syntactically but invalid for lookup.", "content": { "application/json": { "examples": { "unprocessable_ip": { "summary": "Unprocessable IP example.", "value": { "error": { "code": "unprocessable_ip", "message": "IP format accepted syntactically but invalid for lookup.", "request_id": "req_01ht006q6r2d3w2ab8zn74p4mi", "details": null } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "ReleaseUnavailableError": { "description": "No active release is available for lookup requests.", "content": { "application/json": { "examples": { "release_unavailable": { "summary": "Release unavailable example.", "value": { "error": { "code": "release_unavailable", "message": "No active unified release is available for lookup requests.", "request_id": "req_01ht007q6r2d3w2ab8zn74p4mj", "details": null } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } }, "InternalError": { "description": "Unexpected server failure.", "content": { "application/json": { "examples": { "internal_error": { "summary": "Internal error example.", "value": { "error": { "code": "internal_error", "message": "Unexpected server failure.", "request_id": "req_01ht008q6r2d3w2ab8zn74p4mk", "details": null } } } }, "schema": { "$ref": "#/components/schemas/ApiErrorResponse" } } } } } } }