{ "openapi": "3.1.0", "info": { "title": "Casafari account and sign-up API", "version": "2026-10-15.5", "summary": "Your account: plan, units left, whether calls can run, and the payment link to poll after a person pays.", "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": "Account" }, { "name": "Sign-up" } ], "externalDocs": { "url": "https://developers.casafari.com/docs" }, "paths": { "/v1/account": { "get": { "operationId": "platform_account_get", "summary": "Platform account get", "description": "Free: costs 0 units.", "tags": [ "Account" ], "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] }, { "oauth2": [ "account:read" ] } ], "x-casafari-operation-id": "platform.account.get", "x-casafari-units": 0, "x-casafari-scope": "account:read", "x-casafari-mcp-tools": [ "account_status" ], "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": { "$ref": "#/components/schemas/AccountStatus" } } } }, "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/account", "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/account", "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/account", "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/account", "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/account", "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/account", "code": "token_expired", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unauthorized", "invalid_credential", "credential_revoked", "token_expired" ] }, "403": { "description": "`insufficient_scope`, `account_suspended` (https://platform.casafari.com/errors/insufficient-scope, 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/account", "code": "insufficient_scope", "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/account", "code": "account_suspended", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "insufficient_scope", "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/account", "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/account", "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/account", "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/account", "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/account", "code": "internal_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "internal_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/account", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unavailable" ] } } } }, "/v1/account/payment-links/{payment_link_id}": { "get": { "operationId": "platform_payment_link_get", "summary": "Platform payment link get", "description": "Free: costs 0 units.", "tags": [ "Account" ], "security": [ { "apiKeyBearer": [] }, { "apiKeyHeader": [] }, { "oauth2": [ "account:read" ] } ], "x-casafari-operation-id": "platform.payment-link.get", "x-casafari-units": 0, "x-casafari-scope": "account:read", "parameters": [ { "name": "payment_link_id", "in": "path", "required": true, "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": { "$ref": "#/components/schemas/PaymentLinkStatus" } } } }, "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/account/payment-links/{payment_link_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/account/payment-links/{payment_link_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/account/payment-links/{payment_link_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/account/payment-links/{payment_link_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/account/payment-links/{payment_link_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/account/payment-links/{payment_link_id}", "code": "token_expired", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unauthorized", "invalid_credential", "credential_revoked", "token_expired" ] }, "403": { "description": "`insufficient_scope`, `account_suspended` (https://platform.casafari.com/errors/insufficient-scope, 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/account/payment-links/{payment_link_id}", "code": "insufficient_scope", "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/account/payment-links/{payment_link_id}", "code": "account_suspended", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "insufficient_scope", "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/account/payment-links/{payment_link_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/account/payment-links/{payment_link_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/account/payment-links/{payment_link_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/account/payment-links/{payment_link_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/account/payment-links/{payment_link_id}", "code": "internal_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "internal_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/account/payment-links/{payment_link_id}", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unavailable" ] } } } }, "/v1/signups/terms": { "get": { "operationId": "signups_terms", "summary": "Read the current terms", "description": "Free. Returns the terms version a sign-up must accept.", "tags": [ "Sign-up" ], "security": [], "responses": { "200": { "description": "The current terms.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupTerms" } } } }, "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/signups/terms", "code": "method_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "method_not_allowed" ] }, "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/signups/terms", "code": "internal_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "internal_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/signups/terms", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unavailable" ] } } } }, "/v1/signups": { "post": { "operationId": "signups_start", "summary": "Start a sign-up", "description": "Emails a 6-digit code to the person. Entering it accepts the terms and opens a Free plan account.", "tags": [ "Sign-up" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" } } } }, "responses": { "202": { "description": "Code sent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupStarted" } } } }, "400": { "description": "`invalid_request`, `email_not_allowed`, `terms_not_accepted`, `verification_code_invalid`, `verification_code_expired` (https://platform.casafari.com/errors/invalid-request, https://platform.casafari.com/errors/email-not-allowed, https://platform.casafari.com/errors/terms-not-accepted, https://platform.casafari.com/errors/verification-code-invalid, https://platform.casafari.com/errors/verification-code-expired)", "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/signups", "code": "invalid_request", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "email_not_allowed": { "value": { "type": "https://platform.casafari.com/errors/email-not-allowed", "title": "This email address cannot be used to sign up.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups", "code": "email_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "terms_not_accepted": { "value": { "type": "https://platform.casafari.com/errors/terms-not-accepted", "title": "The current terms must be accepted.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups", "code": "terms_not_accepted", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "verification_code_invalid": { "value": { "type": "https://platform.casafari.com/errors/verification-code-invalid", "title": "The code is not correct.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups", "code": "verification_code_invalid", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "verification_code_expired": { "value": { "type": "https://platform.casafari.com/errors/verification-code-expired", "title": "The code has expired or was used up.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups", "code": "verification_code_expired", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "invalid_request", "email_not_allowed", "terms_not_accepted", "verification_code_invalid", "verification_code_expired" ] }, "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/signups", "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/signups", "code": "method_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "method_not_allowed" ] }, "429": { "description": "`signup_limited`, `rate_limited` (https://platform.casafari.com/errors/signup-limited, https://platform.casafari.com/errors/rate-limited)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "signup_limited": { "value": { "type": "https://platform.casafari.com/errors/signup-limited", "title": "Too many new accounts from this network today.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups", "code": "signup_limited", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "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/signups", "code": "rate_limited", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "signup_limited", "rate_limited" ] }, "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/signups", "code": "internal_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "internal_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/signups", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unavailable" ] } } } }, "/v1/signups/{signup_id}/verify": { "post": { "operationId": "signups_verify", "summary": "Finish a sign-up with the emailed code", "description": "Returns the account and an API key, shown once.", "tags": [ "Sign-up" ], "security": [], "parameters": [ { "name": "signup_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupVerifyRequest" } } } }, "responses": { "201": { "description": "Account opened.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupCompleted" } } } }, "400": { "description": "`invalid_request`, `email_not_allowed`, `terms_not_accepted`, `verification_code_invalid`, `verification_code_expired` (https://platform.casafari.com/errors/invalid-request, https://platform.casafari.com/errors/email-not-allowed, https://platform.casafari.com/errors/terms-not-accepted, https://platform.casafari.com/errors/verification-code-invalid, https://platform.casafari.com/errors/verification-code-expired)", "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/signups/{signup_id}/verify", "code": "invalid_request", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "email_not_allowed": { "value": { "type": "https://platform.casafari.com/errors/email-not-allowed", "title": "This email address cannot be used to sign up.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups/{signup_id}/verify", "code": "email_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "terms_not_accepted": { "value": { "type": "https://platform.casafari.com/errors/terms-not-accepted", "title": "The current terms must be accepted.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups/{signup_id}/verify", "code": "terms_not_accepted", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "verification_code_invalid": { "value": { "type": "https://platform.casafari.com/errors/verification-code-invalid", "title": "The code is not correct.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups/{signup_id}/verify", "code": "verification_code_invalid", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "verification_code_expired": { "value": { "type": "https://platform.casafari.com/errors/verification-code-expired", "title": "The code has expired or was used up.", "status": 400, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups/{signup_id}/verify", "code": "verification_code_expired", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "invalid_request", "email_not_allowed", "terms_not_accepted", "verification_code_invalid", "verification_code_expired" ] }, "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/signups/{signup_id}/verify", "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/signups/{signup_id}/verify", "code": "method_not_allowed", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "method_not_allowed" ] }, "429": { "description": "`signup_limited`, `rate_limited` (https://platform.casafari.com/errors/signup-limited, https://platform.casafari.com/errors/rate-limited)", "headers": { "Casafari-Request-Id": { "$ref": "#/components/headers/Casafari-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "signup_limited": { "value": { "type": "https://platform.casafari.com/errors/signup-limited", "title": "Too many new accounts from this network today.", "status": 429, "detail": "Written for the request; see the code's page.", "instance": "/v1/signups/{signup_id}/verify", "code": "signup_limited", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } }, "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/signups/{signup_id}/verify", "code": "rate_limited", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "signup_limited", "rate_limited" ] }, "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/signups/{signup_id}/verify", "code": "internal_error", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "internal_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/signups/{signup_id}/verify", "code": "unavailable", "request_id": "req_01JABCDEFGHJKMNPQRSTVWXYZ2" } } } } }, "x-casafari-codes": [ "unavailable" ] } } } } }, "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" }