{ "openapi": "3.1.0", "info": { "title": "Casafari Location Lookup API", "version": "2026-10-15.3", "summary": "Find a place by name and get the location id every other product takes. Free.", "description": "Casafari sells property data to people and AI agents through self-serve APIs and MCP servers. One account, one key and one balance of units work on every product. Units are the billing atom; every operation lists its cost in x-casafari-units. When units run out the API answers 402 with a payment link a person opens." }, "servers": [ { "url": "https://platform.casafari.com" } ], "tags": [ { "name": "Location Lookup" } ], "externalDocs": { "url": "https://developers.casafari.com/docs" }, "paths": { "/v1/locations/search": { "get": { "operationId": "locations_search", "summary": "Search locations by name or postcode", "description": "Free: costs 0 units. Search by name, by postcode, or both. Postcode coverage: Spain fully, France partly, Portugal only parts of Lisbon; other countries are not covered.", "tags": [ "Location Lookup" ], "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] }, { "oauth2": [ "locations:read" ] } ], "x-casafari-operation-id": "locations.search", "x-casafari-units": 0, "x-casafari-scope": "locations:read", "x-casafari-mcp-tools": [ "locations_search" ], "parameters": [ { "name": "query", "in": "query", "required": false, "description": "A place name or alias; misspellings are tolerated. Required unless postcode is given.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "postcode", "in": "query", "required": false, "description": "The places this postcode covers, smallest area first (for example 28019 or 1950-102). One postcode matches several places. Postcode coverage: Spain fully, France partly, Portugal only parts of Lisbon; other countries are not covered.", "schema": { "type": "string", "minLength": 3, "maxLength": 10 } }, { "name": "postcode_match", "in": "query", "required": false, "description": "exact (default) matches a full-length code; prefix matches the start of one (280, 1950). 2-digit Spanish province prefixes are not postcodes. Needs postcode.", "schema": { "type": "string", "enum": [ "exact", "prefix" ], "default": "exact" } }, { "name": "country", "in": "query", "required": false, "description": "ISO 3166-1 alpha-2 country code to restrict the search to; must be entitled.", "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "lang", "in": "query", "required": false, "description": "Language of the names returned.", "schema": { "type": "string", "enum": [ "en", "es", "pt", "fr", "de", "it", "pl" ], "default": "en" } }, { "name": "size", "in": "query", "required": false, "description": "Page size, at most 25 (a Free plan account is capped lower).", "schema": { "type": "integer", "minimum": 1, "maximum": 25 } } ], "responses": { "200": { "description": "Success.", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" }, "Casafari-Units-Charged": { "$ref": "#/components/headers/Casafari-Units-Charged" }, "Casafari-Units-Remaining": { "$ref": "#/components/headers/Casafari-Units-Remaining" }, "Casafari-Units-Source": { "$ref": "#/components/headers/Casafari-Units-Source" }, "Casafari-Plan": { "$ref": "#/components/headers/Casafari-Plan" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "`invalid_request`, `key_in_query`, `page_depth_exceeded` (https://platform.casafari.com/errors/invalid-request, https://platform.casafari.com/errors/key-in-query, https://platform.casafari.com/errors/page-depth-exceeded)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "value": { "type": "https://platform.casafari.com/errors/invalid-request", "title": "The request is not valid.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "invalid_request", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "key_in_query": { "value": { "type": "https://platform.casafari.com/errors/key-in-query", "title": "Credentials are not accepted in the URL.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "key_in_query", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "page_depth_exceeded": { "value": { "type": "https://platform.casafari.com/errors/page-depth-exceeded", "title": "The request asks for more results than this plan allows.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "page_depth_exceeded", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "invalid_request", "key_in_query", "page_depth_exceeded" ] }, "401": { "description": "`unauthorized`, `invalid_credential`, `credential_revoked`, `token_expired` (https://platform.casafari.com/errors/unauthorized, https://platform.casafari.com/errors/invalid-credential, https://platform.casafari.com/errors/credential-revoked, https://platform.casafari.com/errors/token-expired)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "value": { "type": "https://platform.casafari.com/errors/unauthorized", "title": "A credential is required.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "unauthorized", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "invalid_credential": { "value": { "type": "https://platform.casafari.com/errors/invalid-credential", "title": "The credential is not valid.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "invalid_credential", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "credential_revoked": { "value": { "type": "https://platform.casafari.com/errors/credential-revoked", "title": "The credential has been revoked.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "credential_revoked", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "token_expired": { "value": { "type": "https://platform.casafari.com/errors/token-expired", "title": "The access token has expired.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "token_expired", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unauthorized", "invalid_credential", "credential_revoked", "token_expired" ] }, "403": { "description": "`insufficient_scope`, `not_entitled`, `account_suspended` (https://platform.casafari.com/errors/insufficient-scope, https://platform.casafari.com/errors/not-entitled, https://platform.casafari.com/errors/account-suspended)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "value": { "type": "https://platform.casafari.com/errors/insufficient-scope", "title": "The credential lacks the scope this operation needs.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "insufficient_scope", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "not_entitled": { "value": { "type": "https://platform.casafari.com/errors/not-entitled", "title": "This account is not entitled to this product or country.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "not_entitled", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "account_suspended": { "value": { "type": "https://platform.casafari.com/errors/account-suspended", "title": "The account is suspended.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "account_suspended", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "insufficient_scope", "not_entitled", "account_suspended" ] }, "404": { "description": "`not_found` (https://platform.casafari.com/errors/not-found)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "value": { "type": "https://platform.casafari.com/errors/not-found", "title": "Not found.", "status": 404, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "not_found", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "not_found" ] }, "405": { "description": "`method_not_allowed` (https://platform.casafari.com/errors/method-not-allowed)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "value": { "type": "https://platform.casafari.com/errors/method-not-allowed", "title": "Method not allowed.", "status": 405, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "method_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "method_not_allowed" ] }, "429": { "description": "`rate_limited`, `request_limit_reached` (https://platform.casafari.com/errors/rate-limited, https://platform.casafari.com/errors/request-limit-reached)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "value": { "type": "https://platform.casafari.com/errors/rate-limited", "title": "Too many requests.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "rate_limited", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "request_limit_reached": { "value": { "type": "https://platform.casafari.com/errors/request-limit-reached", "title": "This account has reached a request limit.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "request_limit_reached", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "rate_limited", "request_limit_reached" ] }, "500": { "description": "`internal_error` (https://platform.casafari.com/errors/internal-error)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "value": { "type": "https://platform.casafari.com/errors/internal-error", "title": "Something went wrong on our side.", "status": 500, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "internal_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "internal_error" ] }, "502": { "description": "`upstream_error` (https://platform.casafari.com/errors/upstream-error)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "value": { "type": "https://platform.casafari.com/errors/upstream-error", "title": "The data service failed to answer.", "status": 502, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "upstream_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "upstream_error" ] }, "503": { "description": "`unavailable` (https://platform.casafari.com/errors/unavailable)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unavailable": { "value": { "type": "https://platform.casafari.com/errors/unavailable", "title": "The service is not available just now.", "status": 503, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unavailable" ] }, "504": { "description": "`upstream_timeout` (https://platform.casafari.com/errors/upstream-timeout)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_timeout": { "value": { "type": "https://platform.casafari.com/errors/upstream-timeout", "title": "The data service took too long to answer.", "status": 504, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/search", "code": "upstream_timeout", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "upstream_timeout" ] } } } }, "/v1/locations/{location_id}": { "get": { "operationId": "locations_get", "summary": "Get a location with its parents", "description": "Free: costs 0 units.", "tags": [ "Location Lookup" ], "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] }, { "oauth2": [ "locations:read" ] } ], "x-casafari-operation-id": "locations.get", "x-casafari-units": 0, "x-casafari-scope": "locations:read", "x-casafari-mcp-tools": [ "locations_get" ], "parameters": [ { "name": "location_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success.", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" }, "Casafari-Units-Charged": { "$ref": "#/components/headers/Casafari-Units-Charged" }, "Casafari-Units-Remaining": { "$ref": "#/components/headers/Casafari-Units-Remaining" }, "Casafari-Units-Source": { "$ref": "#/components/headers/Casafari-Units-Source" }, "Casafari-Plan": { "$ref": "#/components/headers/Casafari-Plan" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "`invalid_request`, `key_in_query` (https://platform.casafari.com/errors/invalid-request, https://platform.casafari.com/errors/key-in-query)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "value": { "type": "https://platform.casafari.com/errors/invalid-request", "title": "The request is not valid.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "invalid_request", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "key_in_query": { "value": { "type": "https://platform.casafari.com/errors/key-in-query", "title": "Credentials are not accepted in the URL.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "key_in_query", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "invalid_request", "key_in_query" ] }, "401": { "description": "`unauthorized`, `invalid_credential`, `credential_revoked`, `token_expired` (https://platform.casafari.com/errors/unauthorized, https://platform.casafari.com/errors/invalid-credential, https://platform.casafari.com/errors/credential-revoked, https://platform.casafari.com/errors/token-expired)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "value": { "type": "https://platform.casafari.com/errors/unauthorized", "title": "A credential is required.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "unauthorized", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "invalid_credential": { "value": { "type": "https://platform.casafari.com/errors/invalid-credential", "title": "The credential is not valid.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "invalid_credential", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "credential_revoked": { "value": { "type": "https://platform.casafari.com/errors/credential-revoked", "title": "The credential has been revoked.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "credential_revoked", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "token_expired": { "value": { "type": "https://platform.casafari.com/errors/token-expired", "title": "The access token has expired.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "token_expired", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unauthorized", "invalid_credential", "credential_revoked", "token_expired" ] }, "403": { "description": "`insufficient_scope`, `not_entitled`, `account_suspended` (https://platform.casafari.com/errors/insufficient-scope, https://platform.casafari.com/errors/not-entitled, https://platform.casafari.com/errors/account-suspended)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "value": { "type": "https://platform.casafari.com/errors/insufficient-scope", "title": "The credential lacks the scope this operation needs.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "insufficient_scope", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "not_entitled": { "value": { "type": "https://platform.casafari.com/errors/not-entitled", "title": "This account is not entitled to this product or country.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "not_entitled", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "account_suspended": { "value": { "type": "https://platform.casafari.com/errors/account-suspended", "title": "The account is suspended.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "account_suspended", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "insufficient_scope", "not_entitled", "account_suspended" ] }, "404": { "description": "`not_found` (https://platform.casafari.com/errors/not-found)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "value": { "type": "https://platform.casafari.com/errors/not-found", "title": "Not found.", "status": 404, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "not_found", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "not_found" ] }, "405": { "description": "`method_not_allowed` (https://platform.casafari.com/errors/method-not-allowed)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "value": { "type": "https://platform.casafari.com/errors/method-not-allowed", "title": "Method not allowed.", "status": 405, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "method_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "method_not_allowed" ] }, "429": { "description": "`rate_limited`, `request_limit_reached` (https://platform.casafari.com/errors/rate-limited, https://platform.casafari.com/errors/request-limit-reached)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "value": { "type": "https://platform.casafari.com/errors/rate-limited", "title": "Too many requests.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "rate_limited", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "request_limit_reached": { "value": { "type": "https://platform.casafari.com/errors/request-limit-reached", "title": "This account has reached a request limit.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "request_limit_reached", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "rate_limited", "request_limit_reached" ] }, "500": { "description": "`internal_error` (https://platform.casafari.com/errors/internal-error)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "value": { "type": "https://platform.casafari.com/errors/internal-error", "title": "Something went wrong on our side.", "status": 500, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "internal_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "internal_error" ] }, "502": { "description": "`upstream_error` (https://platform.casafari.com/errors/upstream-error)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "value": { "type": "https://platform.casafari.com/errors/upstream-error", "title": "The data service failed to answer.", "status": 502, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "upstream_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "upstream_error" ] }, "503": { "description": "`unavailable` (https://platform.casafari.com/errors/unavailable)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unavailable": { "value": { "type": "https://platform.casafari.com/errors/unavailable", "title": "The service is not available just now.", "status": 503, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unavailable" ] }, "504": { "description": "`upstream_timeout` (https://platform.casafari.com/errors/upstream-timeout)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_timeout": { "value": { "type": "https://platform.casafari.com/errors/upstream-timeout", "title": "The data service took too long to answer.", "status": 504, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}", "code": "upstream_timeout", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "upstream_timeout" ] } } } }, "/v1/locations/{location_id}/children": { "get": { "operationId": "locations_children", "summary": "List the child locations of a location", "description": "Free: costs 0 units.", "tags": [ "Location Lookup" ], "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] }, { "oauth2": [ "locations:read" ] } ], "x-casafari-operation-id": "locations.children", "x-casafari-units": 0, "x-casafari-scope": "locations:read", "parameters": [ { "name": "location_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "size", "in": "query", "required": false, "description": "Page size, at most 100 (a Free plan account is capped lower).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Position of the next page, copied from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" }, "Casafari-Units-Charged": { "$ref": "#/components/headers/Casafari-Units-Charged" }, "Casafari-Units-Remaining": { "$ref": "#/components/headers/Casafari-Units-Remaining" }, "Casafari-Units-Source": { "$ref": "#/components/headers/Casafari-Units-Source" }, "Casafari-Plan": { "$ref": "#/components/headers/Casafari-Plan" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "`invalid_request`, `key_in_query`, `page_depth_exceeded` (https://platform.casafari.com/errors/invalid-request, https://platform.casafari.com/errors/key-in-query, https://platform.casafari.com/errors/page-depth-exceeded)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "value": { "type": "https://platform.casafari.com/errors/invalid-request", "title": "The request is not valid.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "invalid_request", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "key_in_query": { "value": { "type": "https://platform.casafari.com/errors/key-in-query", "title": "Credentials are not accepted in the URL.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "key_in_query", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "page_depth_exceeded": { "value": { "type": "https://platform.casafari.com/errors/page-depth-exceeded", "title": "The request asks for more results than this plan allows.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "page_depth_exceeded", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "invalid_request", "key_in_query", "page_depth_exceeded" ] }, "401": { "description": "`unauthorized`, `invalid_credential`, `credential_revoked`, `token_expired` (https://platform.casafari.com/errors/unauthorized, https://platform.casafari.com/errors/invalid-credential, https://platform.casafari.com/errors/credential-revoked, https://platform.casafari.com/errors/token-expired)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "value": { "type": "https://platform.casafari.com/errors/unauthorized", "title": "A credential is required.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "unauthorized", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "invalid_credential": { "value": { "type": "https://platform.casafari.com/errors/invalid-credential", "title": "The credential is not valid.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "invalid_credential", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "credential_revoked": { "value": { "type": "https://platform.casafari.com/errors/credential-revoked", "title": "The credential has been revoked.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "credential_revoked", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "token_expired": { "value": { "type": "https://platform.casafari.com/errors/token-expired", "title": "The access token has expired.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "token_expired", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unauthorized", "invalid_credential", "credential_revoked", "token_expired" ] }, "403": { "description": "`insufficient_scope`, `not_entitled`, `account_suspended` (https://platform.casafari.com/errors/insufficient-scope, https://platform.casafari.com/errors/not-entitled, https://platform.casafari.com/errors/account-suspended)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "value": { "type": "https://platform.casafari.com/errors/insufficient-scope", "title": "The credential lacks the scope this operation needs.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "insufficient_scope", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "not_entitled": { "value": { "type": "https://platform.casafari.com/errors/not-entitled", "title": "This account is not entitled to this product or country.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "not_entitled", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "account_suspended": { "value": { "type": "https://platform.casafari.com/errors/account-suspended", "title": "The account is suspended.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "account_suspended", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "insufficient_scope", "not_entitled", "account_suspended" ] }, "404": { "description": "`not_found` (https://platform.casafari.com/errors/not-found)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "value": { "type": "https://platform.casafari.com/errors/not-found", "title": "Not found.", "status": 404, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "not_found", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "not_found" ] }, "405": { "description": "`method_not_allowed` (https://platform.casafari.com/errors/method-not-allowed)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "value": { "type": "https://platform.casafari.com/errors/method-not-allowed", "title": "Method not allowed.", "status": 405, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "method_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "method_not_allowed" ] }, "429": { "description": "`rate_limited`, `request_limit_reached` (https://platform.casafari.com/errors/rate-limited, https://platform.casafari.com/errors/request-limit-reached)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "value": { "type": "https://platform.casafari.com/errors/rate-limited", "title": "Too many requests.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "rate_limited", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "request_limit_reached": { "value": { "type": "https://platform.casafari.com/errors/request-limit-reached", "title": "This account has reached a request limit.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "request_limit_reached", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "rate_limited", "request_limit_reached" ] }, "500": { "description": "`internal_error` (https://platform.casafari.com/errors/internal-error)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "value": { "type": "https://platform.casafari.com/errors/internal-error", "title": "Something went wrong on our side.", "status": 500, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "internal_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "internal_error" ] }, "502": { "description": "`upstream_error` (https://platform.casafari.com/errors/upstream-error)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "value": { "type": "https://platform.casafari.com/errors/upstream-error", "title": "The data service failed to answer.", "status": 502, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "upstream_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "upstream_error" ] }, "503": { "description": "`unavailable` (https://platform.casafari.com/errors/unavailable)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unavailable": { "value": { "type": "https://platform.casafari.com/errors/unavailable", "title": "The service is not available just now.", "status": 503, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unavailable" ] }, "504": { "description": "`upstream_timeout` (https://platform.casafari.com/errors/upstream-timeout)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_timeout": { "value": { "type": "https://platform.casafari.com/errors/upstream-timeout", "title": "The data service took too long to answer.", "status": 504, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/{location_id}/children", "code": "upstream_timeout", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "upstream_timeout" ] } } } }, "/v1/locations/by-coordinates": { "get": { "operationId": "locations_by_coordinates", "summary": "Find the locations that contain a point", "description": "Free: costs 0 units.", "tags": [ "Location Lookup" ], "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] }, { "oauth2": [ "locations:read" ] } ], "x-casafari-operation-id": "locations.by-coordinates", "x-casafari-units": 0, "x-casafari-scope": "locations:read", "responses": { "200": { "description": "Success.", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" }, "Casafari-Units-Charged": { "$ref": "#/components/headers/Casafari-Units-Charged" }, "Casafari-Units-Remaining": { "$ref": "#/components/headers/Casafari-Units-Remaining" }, "Casafari-Units-Source": { "$ref": "#/components/headers/Casafari-Units-Source" }, "Casafari-Plan": { "$ref": "#/components/headers/Casafari-Plan" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "`invalid_request`, `key_in_query` (https://platform.casafari.com/errors/invalid-request, https://platform.casafari.com/errors/key-in-query)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "invalid_request": { "value": { "type": "https://platform.casafari.com/errors/invalid-request", "title": "The request is not valid.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "invalid_request", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "key_in_query": { "value": { "type": "https://platform.casafari.com/errors/key-in-query", "title": "Credentials are not accepted in the URL.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "key_in_query", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "invalid_request", "key_in_query" ] }, "401": { "description": "`unauthorized`, `invalid_credential`, `credential_revoked`, `token_expired` (https://platform.casafari.com/errors/unauthorized, https://platform.casafari.com/errors/invalid-credential, https://platform.casafari.com/errors/credential-revoked, https://platform.casafari.com/errors/token-expired)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unauthorized": { "value": { "type": "https://platform.casafari.com/errors/unauthorized", "title": "A credential is required.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "unauthorized", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "invalid_credential": { "value": { "type": "https://platform.casafari.com/errors/invalid-credential", "title": "The credential is not valid.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "invalid_credential", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "credential_revoked": { "value": { "type": "https://platform.casafari.com/errors/credential-revoked", "title": "The credential has been revoked.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "credential_revoked", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "token_expired": { "value": { "type": "https://platform.casafari.com/errors/token-expired", "title": "The access token has expired.", "status": 401, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "token_expired", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unauthorized", "invalid_credential", "credential_revoked", "token_expired" ] }, "403": { "description": "`insufficient_scope`, `not_entitled`, `account_suspended` (https://platform.casafari.com/errors/insufficient-scope, https://platform.casafari.com/errors/not-entitled, https://platform.casafari.com/errors/account-suspended)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "insufficient_scope": { "value": { "type": "https://platform.casafari.com/errors/insufficient-scope", "title": "The credential lacks the scope this operation needs.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "insufficient_scope", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "not_entitled": { "value": { "type": "https://platform.casafari.com/errors/not-entitled", "title": "This account is not entitled to this product or country.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "not_entitled", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "account_suspended": { "value": { "type": "https://platform.casafari.com/errors/account-suspended", "title": "The account is suspended.", "status": 403, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "account_suspended", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "insufficient_scope", "not_entitled", "account_suspended" ] }, "404": { "description": "`not_found` (https://platform.casafari.com/errors/not-found)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "not_found": { "value": { "type": "https://platform.casafari.com/errors/not-found", "title": "Not found.", "status": 404, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "not_found", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "not_found" ] }, "405": { "description": "`method_not_allowed` (https://platform.casafari.com/errors/method-not-allowed)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "method_not_allowed": { "value": { "type": "https://platform.casafari.com/errors/method-not-allowed", "title": "Method not allowed.", "status": 405, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "method_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "method_not_allowed" ] }, "429": { "description": "`rate_limited`, `request_limit_reached` (https://platform.casafari.com/errors/rate-limited, https://platform.casafari.com/errors/request-limit-reached)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "rate_limited": { "value": { "type": "https://platform.casafari.com/errors/rate-limited", "title": "Too many requests.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "rate_limited", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "request_limit_reached": { "value": { "type": "https://platform.casafari.com/errors/request-limit-reached", "title": "This account has reached a request limit.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "request_limit_reached", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "rate_limited", "request_limit_reached" ] }, "500": { "description": "`internal_error` (https://platform.casafari.com/errors/internal-error)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "internal_error": { "value": { "type": "https://platform.casafari.com/errors/internal-error", "title": "Something went wrong on our side.", "status": 500, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "internal_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "internal_error" ] }, "502": { "description": "`upstream_error` (https://platform.casafari.com/errors/upstream-error)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_error": { "value": { "type": "https://platform.casafari.com/errors/upstream-error", "title": "The data service failed to answer.", "status": 502, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "upstream_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "upstream_error" ] }, "503": { "description": "`unavailable` (https://platform.casafari.com/errors/unavailable)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unavailable": { "value": { "type": "https://platform.casafari.com/errors/unavailable", "title": "The service is not available just now.", "status": 503, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unavailable" ] }, "504": { "description": "`upstream_timeout` (https://platform.casafari.com/errors/upstream-timeout)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "upstream_timeout": { "value": { "type": "https://platform.casafari.com/errors/upstream-timeout", "title": "The data service took too long to answer.", "status": 504, "detail": "Written for the request; see the code's page.", "instance": "/v1/locations/by-coordinates", "code": "upstream_timeout", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "upstream_timeout" ] } } } } }, "components": { "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status", "detail", "instance", "code", "request_id" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "enum": [ "invalid_request", "validation_failed", "key_in_query", "page_depth_exceeded", "payload_too_large", "unsupported_media_type", "unauthorized", "invalid_credential", "credential_revoked", "token_expired", "insufficient_scope", "not_entitled", "verification_required", "not_self_serve", "account_suspended", "permission_denied", "origin_mismatch", "reauthentication_required", "payment_required", "not_found", "method_not_allowed", "conflict", "resource_limit_reached", "rate_limited", "daily_limit_reached", "request_limit_reached", "signup_limited", "email_not_allowed", "terms_not_accepted", "verification_code_invalid", "verification_code_expired", "internal_error", "upstream_error", "capacity_exhausted", "unavailable", "upstream_timeout", "usage_limit_reached" ] }, "request_id": { "type": "string" } }, "additionalProperties": true }, "AccountStatus": { "type": "object", "required": [ "account_id", "plan", "standing", "can_call", "units" ], "properties": { "account_id": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "billing_mode": { "type": "string" } } }, "standing": { "type": "string" }, "can_call": { "type": "boolean" }, "blocked_reason": { "type": [ "string", "null" ] }, "units": { "type": "object", "additionalProperties": true }, "upgrade_url": { "type": [ "string", "null" ], "format": "uri" }, "console_url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "PaymentLinkStatus": { "type": "object", "required": [ "payment_link_id", "status", "poll_after_s" ], "properties": { "payment_link_id": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "completed", "expired", "superseded" ] }, "reason": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "poll_after_s": { "type": "integer" } } }, "SignupRequest": { "type": "object", "required": [ "email", "terms_version" ], "properties": { "email": { "type": "string", "format": "email" }, "terms_version": { "type": "string" }, "account_name": { "type": "string" }, "client": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "tips_opt_out": { "type": "boolean", "default": false, "description": "true: don't send the person tips and usage emails. Account, billing and security emails still arrive." }, "news_opt_in": { "type": "boolean", "default": false, "description": "true: the person agrees to news emails." } } }, "SignupStarted": { "type": "object", "required": [ "signup_id", "status", "verify_url" ], "properties": { "signup_id": { "type": "string" }, "status": { "const": "code_sent" }, "delivery": { "const": "email" }, "expires_at": { "type": "string", "format": "date-time" }, "verify_url": { "type": "string", "format": "uri" }, "terms_url": { "type": "string", "format": "uri" } } }, "SignupVerifyRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "The 6-digit code emailed to the person." } } }, "SignupCompleted": { "type": "object", "required": [ "account_id", "api_key", "scopes", "plan" ], "properties": { "account_id": { "type": "string" }, "user_id": { "type": "string" }, "api_key": { "type": "string", "description": "Shown once." }, "key_id": { "type": "string" }, "key_hint": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "plan": { "type": "object", "properties": { "id": { "type": "string" }, "trial_units": { "type": [ "integer", "null" ] }, "trial_ends_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "api_base_url": { "type": "string", "format": "uri" }, "resources": { "type": "object", "additionalProperties": true }, "console_url": { "type": "string", "format": "uri" }, "docs_url": { "type": "string", "format": "uri" } } }, "SignupTerms": { "type": "object", "required": [ "terms_version", "terms_url", "privacy_url" ], "properties": { "terms_version": { "type": "string" }, "terms_url": { "type": "string", "format": "uri" }, "privacy_url": { "type": "string", "format": "uri" } } } }, "headers": { "Casafari-Request-Id": { "description": "Id of this request; quote it when asking for help.", "schema": { "type": "string" } }, "Casafari-Units-Charged": { "description": "Units this call cost.", "schema": { "type": "integer" } }, "Casafari-Units-Remaining": { "description": "Units left across the account's funding.", "schema": { "type": "integer" } }, "Casafari-Units-Source": { "description": "Which funding paid: trial, included, prepaid or overage.", "schema": { "type": "string" } }, "Casafari-Plan": { "description": "The account's plan id.", "schema": { "type": "string" } }, "RateLimit": { "description": "Current rate-limit state (RFC 9331 draft).", "schema": { "type": "string" } }, "RateLimit-Policy": { "description": "The rate-limit policy that applies.", "schema": { "type": "string" } } }, "securitySchemes": { "apiKeyBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "cf_sk_ API key", "description": "Authorization: Bearer cf_sk_..." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "The same API key in a header." }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://platform.casafari.com/oauth/authorize", "tokenUrl": "https://platform.casafari.com/oauth/token", "scopes": { "account:read": "Access to account (read).", "locations:read": "Access to locations (read)." } }, "clientCredentials": { "tokenUrl": "https://platform.casafari.com/oauth/token", "scopes": { "account:read": "Access to account (read).", "locations:read": "Access to locations (read)." } } } } } }, "x-casafari-resource": "https://platform.casafari.com/v1/locations" }