{ "openapi": "3.1.0", "info": { "title": "Casafari Comparables with Transactions API", "version": "2026-10-31.1", "summary": "Comparables with Transactions: everything Comparables returns plus registered closing prices of nearby sales, Spain's notary deals, Italy's registered sales from Agenzia delle Entrate and Poland's RCN (transactional_data) and France's DVF register (dvf_results), over REST and MCP; the same search as Comparables.", "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 tokens work on every product. Tokens are the billing atom; every operation lists its cost in x-casafari-units. When tokens run out the API answers 402 with a payment link to top up." }, "servers": [ { "url": "https://platform.casafari.com" } ], "tags": [ { "name": "Comparables with Transactions" } ], "externalDocs": { "url": "https://developers.casafari.com/docs" }, "paths": { "/v1/comparables-transactions/search": { "post": { "operationId": "comparables_transactions_get_comparables", "summary": "Value a property with comparables and registered closing prices", "description": "Costs 65 tokens a call. Page size: `comparables_count` in the body, at most 50 (a Free plan account is capped lower).", "tags": [ "Comparables with Transactions" ], "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] }, { "oauth2": [ "comparables-transactions:read" ] } ], "x-casafari-operation-id": "comparables-transactions.get-comparables", "x-casafari-units": 65, "x-casafari-scope": "comparables-transactions:read", "x-casafari-mcp-tools": [ "comparables-transactions_get_comparables" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comparables_count": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of comparable properties in results." }, "location_boundary": { "type": "object", "properties": { "polygon": { "type": "array", "items": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude." } }, "required": [ "latitude", "longitude" ], "additionalProperties": false }, "minItems": 4, "description": "Closed polygon of geo-points to search within. First and last points must match." }, "circle": { "type": "object", "properties": { "distance": { "type": "number", "minimum": 0.05, "maximum": 50, "description": "Circle radius in kilometres (not metres) from `target_point`: 0.05 to 50, default 5.", "default": 5 }, "target_point": { "type": "object", "properties": { "coordinates": { "type": "object", "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude." } }, "required": [ "latitude", "longitude" ], "additionalProperties": false, "description": "Target point coordinates to search around." }, "address": { "type": "string", "description": "Address of the property to define the point to search around." }, "cadastral_reference": { "type": "object", "properties": { "country_code": { "type": "string", "enum": [ "ES" ], "description": "Country code following the ISO 3166-1 alpha-2 rules." }, "cadastral_reference": { "type": "string", "description": "Cadastral reference of the estate." }, "province": { "type": "string", "description": "Name of the estate's province." }, "municipality": { "type": "string", "description": "Name of the estate's municipality." } }, "required": [ "country_code", "cadastral_reference" ], "additionalProperties": false, "description": "Cadastral reference of the property to define the point to search around. For now available only for Spain." } }, "additionalProperties": false, "description": "Target point to search around. Can be defined as coordinates, address or cadastral reference of the property. Only one value should be provided." } }, "required": [ "target_point" ], "additionalProperties": false, "description": "Circle boundary to search within." } }, "additionalProperties": false, "description": "Location to search within. Can be defined as a polygon of geo-points or a circle with a given target point and a distance. Only one value should be provided." }, "sold_or_rented_after": { "type": [ "string", "null" ], "description": "Properties sold/rented since this date (in the format `YYYY-MM-DD`) will be considered as possible comparables. Default value: 9 months ago, counting from today. If `null` is passed, only active properties will be considered." }, "operation": { "type": "string", "enum": [ "sale", "rent" ], "description": "Operation type." }, "comparables_types": { "type": "array", "items": { "type": "string", "enum": [ "apartment", "studio", "duplex", "penthouse", "dachgeschosswohnung", "etagenwohnung", "erdgeschosswohnung", "country_house", "house", "palace", "townhouse", "villa", "country_estate", "chalet", "bungalow", "family_house", "reihenhaus", "reihenendhaus", "reihenmittelhaus", "einfamilienhaus", "zweifamilienhaus", "landwirtschaftliche_betriebe", "retail", "office", "industrial", "warehouse", "hotel", "other_commercial", "restaurant", "werkstatt", "plot", "urban_plot", "rural_plot", "room", "other", "garage", "parking", "apartment_building", "office_building", "mix_use_building" ] }, "description": "Property types to compare with, all from one type group. Groups: apartment (erdgeschosswohnung, etagenwohnung, dachgeschosswohnung, duplex, studio, penthouse, apartment); house (villa, reihenhaus, palace, country_estate, zweifamilienhaus, reihenmittelhaus, reihenendhaus, landwirtschaftliche_betriebe, country_house, townhouse, chalet, bungalow, einfamilienhaus, house; family_house is deprecated); room (room); building (mix_use_building, office_building, apartment_building); investment (restaurant, other_commercial, warehouse, office, industrial, werkstatt, hotel, retail); plot (rural_plot, urban_plot; plot is deprecated); other (garage, other, parking). Not every type is available in every country." }, "min_price": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "The minimum price filter for comparables result. Default value: 0." }, "max_price": { "type": "integer", "minimum": 1, "maximum": 2147483647, "description": "The maximum price filter for comparables result." }, "condition": { "type": "string", "enum": [ "used", "ruin", "very-good", "new", "other" ], "description": "Property condition: used, ruin, very-good, new or other." }, "bedrooms": { "type": "integer", "minimum": 0, "maximum": 15000, "description": "Target number of bedrooms of the property being valued. A similarity target, not a filter: comparables with other bedroom counts can be returned, ranked lower. Cannot be used together with `rooms`." }, "rooms": { "type": "integer", "minimum": 0, "maximum": 15000, "description": "Number of rooms (cannot be used together with `bedrooms`)." }, "bathrooms": { "type": "integer", "minimum": 1, "maximum": 15000, "description": "Number of bathrooms." }, "construction_year": { "type": "integer", "minimum": 1, "maximum": 3000, "description": "Desired construction year." }, "total_area": { "type": "integer", "minimum": 5, "maximum": 10000000, "description": "Desired total area, square meters. This field is required for `hotel`, `industrial`, `office`, `other_commercial`, `restaurant`, `retail`, `warehouse`, `werkstatt` property types if `target_point.cadastral_reference` is not provided." }, "plot_area": { "type": "integer", "minimum": 20, "maximum": 10000000, "description": "Desired plot area, square meters. This field is required for `rural_plot` and `urban_plot` property types if `target_point.cadastral_reference` is not provided." }, "floors": { "type": "array", "items": { "type": "string", "enum": [ "no_floor", "ground", "middle", "top" ] }, "description": "List of floor types." }, "floor_number": { "type": "array", "items": { "type": "integer", "minimum": -250, "maximum": 250 }, "description": "Desired list of floor numbers. Negative values indicate underground floors (e.g. basements). Minimum value is -250. Maximum value is 250." }, "orientation": { "type": "string", "enum": [ "exterior", "interior" ], "description": "Property view orientation." }, "views": { "type": "array", "items": { "type": "string", "enum": [ "water", "landscape", "city", "golf", "park" ] }, "description": "List of views from the property." }, "directions": { "type": "array", "items": { "type": "string", "enum": [ "north", "south", "east", "west" ] }, "description": "List of cardinal directions the property faces." }, "characteristics": { "type": "object", "properties": { "must_have": { "type": "array", "items": { "type": "string", "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ] }, "description": "Include only properties that have all these characteristics." }, "nice_to_have": { "type": "array", "items": { "type": "string", "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ] }, "description": "Include properties that have any of these characteristics." }, "exclude": { "type": "array", "items": { "type": "string", "enum": [ "balcony", "elevator", "no_elevator", "garage", "garden", "parking", "storage", "swimming_pool", "terrace", "rental_license", "furniture", "rented_out", "life_annuity" ] }, "description": "Exclude properties that contain any of these characteristics." } }, "additionalProperties": false, "description": "Property characteristics." }, "energy_ratings": { "type": "array", "items": { "type": "string", "enum": [ "Unknown", "A+", "A", "B", "C", "D", "E", "F", "G", "H" ] }, "description": "List of energy ratings." }, "days_on_market_from": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Minimum days on market value." }, "days_on_market_to": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Maximum days on market value." }, "with_agencies": { "type": "array", "items": { "type": "string" }, "description": "Only properties advertised by these agencies, companies or sources, as free-text names. No list of names is available over MCP; an unknown name matches nothing." }, "without_agencies": { "type": "array", "items": { "type": "string" }, "description": "Exclude properties advertised by these agencies, companies or sources, as free-text names. No list of names is available over MCP." }, "exclude_outliers": { "type": "boolean", "description": "Exclude properties that are significantly underpriced or overpriced compared to similar properties. Default value: true." } }, "required": [ "comparables_count", "location_boundary", "operation", "comparables_types" ] } } } }, "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/comparables-transactions/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/comparables-transactions/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/comparables-transactions/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/comparables-transactions/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/comparables-transactions/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/comparables-transactions/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/comparables-transactions/search", "code": "token_expired", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unauthorized", "invalid_credential", "credential_revoked", "token_expired" ] }, "402": { "description": "`payment_required` (https://platform.casafari.com/errors/payment-required)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payment_required": { "value": { "type": "https://platform.casafari.com/errors/payment-required", "title": "Payment is required to continue.", "status": 402, "detail": "Written for the request; see the code's page.", "instance": "/v1/comparables-transactions/search", "code": "payment_required", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "payment_required" ] }, "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/comparables-transactions/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/comparables-transactions/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/comparables-transactions/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/comparables-transactions/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/comparables-transactions/search", "code": "method_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "method_not_allowed" ] }, "409": { "description": "`conflict` (https://platform.casafari.com/errors/conflict)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "conflict": { "value": { "type": "https://platform.casafari.com/errors/conflict", "title": "The request conflicts with the current state.", "status": 409, "detail": "Written for the request; see the code's page.", "instance": "/v1/comparables-transactions/search", "code": "conflict", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "conflict" ] }, "413": { "description": "`payload_too_large` (https://platform.casafari.com/errors/payload-too-large)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "payload_too_large": { "value": { "type": "https://platform.casafari.com/errors/payload-too-large", "title": "The request body is too large.", "status": 413, "detail": "Written for the request; see the code's page.", "instance": "/v1/comparables-transactions/search", "code": "payload_too_large", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "payload_too_large" ] }, "415": { "description": "`unsupported_media_type` (https://platform.casafari.com/errors/unsupported-media-type)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "unsupported_media_type": { "value": { "type": "https://platform.casafari.com/errors/unsupported-media-type", "title": "Send the body as application/json.", "status": 415, "detail": "Written for the request; see the code's page.", "instance": "/v1/comparables-transactions/search", "code": "unsupported_media_type", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unsupported_media_type" ] }, "422": { "description": "`validation_failed` (https://platform.casafari.com/errors/validation-failed)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "validation_failed": { "value": { "type": "https://platform.casafari.com/errors/validation-failed", "title": "The request body did not match the schema.", "status": 422, "detail": "Written for the request; see the code's page.", "instance": "/v1/comparables-transactions/search", "code": "validation_failed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "validation_failed" ] }, "429": { "description": "`rate_limited`, `daily_limit_reached`, `request_limit_reached`, `usage_limit_reached` (https://platform.casafari.com/errors/rate-limited, https://platform.casafari.com/errors/daily-limit-reached, https://platform.casafari.com/errors/request-limit-reached, https://platform.casafari.com/errors/usage-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/comparables-transactions/search", "code": "rate_limited", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "daily_limit_reached": { "value": { "type": "https://platform.casafari.com/errors/daily-limit-reached", "title": "This account has reached its daily limit.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/comparables-transactions/search", "code": "daily_limit_reached", "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/comparables-transactions/search", "code": "request_limit_reached", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "usage_limit_reached": { "value": { "type": "https://platform.casafari.com/errors/usage-limit-reached", "title": "A usage limit of this plan is used up.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/comparables-transactions/search", "code": "usage_limit_reached", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "rate_limited", "daily_limit_reached", "request_limit_reached", "usage_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/comparables-transactions/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/comparables-transactions/search", "code": "upstream_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "upstream_error" ] }, "503": { "description": "`capacity_exhausted`, `unavailable` (https://platform.casafari.com/errors/capacity-exhausted, 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": { "capacity_exhausted": { "value": { "type": "https://platform.casafari.com/errors/capacity-exhausted", "title": "The platform has reached its capacity for today.", "status": 503, "detail": "Written for the request; see the code's page.", "instance": "/v1/comparables-transactions/search", "code": "capacity_exhausted", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "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/comparables-transactions/search", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "capacity_exhausted", "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/comparables-transactions/search", "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", "existing_api_path", "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" ] }, "reset_at": { "type": [ "string", "null" ], "format": "date-time" }, "request_limits": { "type": "array", "items": { "type": "object", "required": [ "window", "unit", "limit", "used", "remaining", "period_seconds", "reset_at" ], "properties": { "window": { "type": "string", "enum": [ "minute", "session", "day", "week", "month", "locations" ] }, "unit": { "type": "string", "enum": [ "requests", "places" ] }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "period_seconds": { "type": "integer" }, "reset_at": { "type": "string", "format": "date-time" } } } }, "claro_trial_searches": { "type": [ "object", "null" ], "required": [ "limit", "used", "remaining" ], "properties": { "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" } } }, "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": "Tokens this call cost.", "schema": { "type": "integer" } }, "Casafari-Units-Remaining": { "description": "Tokens 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).", "comparables-transactions:read": "Access to comparables-transactions (read)." } }, "clientCredentials": { "tokenUrl": "https://platform.casafari.com/oauth/token", "scopes": { "account:read": "Access to account (read).", "locations:read": "Access to locations (read).", "comparables-transactions:read": "Access to comparables-transactions (read)." } } } } } }, "x-casafari-resource": "https://platform.casafari.com/v1/comparables-transactions" }