{ "openapi": "3.1.0", "info": { "title": "ZeroCaptcha API", "description": "Solve CAPTCHAs, starting with Cloudflare Turnstile, and pay from a prepaid balance.\n\nErrors come in three shapes. Every endpoint but the compatible and 2Captcha ones answers a failure with an RFC 9457 problem document (`application/problem+json`) carrying a stable `code`. The compatible endpoints, `/createTask`, `/getTaskResult` and `/getBalance`, answer in their dialect, as the clients they serve expect: HTTP 200 with `errorId` 1, an `errorCode` and an `errorDescription`. The 2Captcha endpoints, `/in.php` and `/res.php`, answer HTTP 200 with an error code such as `ERROR_ZERO_BALANCE`, as text or, with `json=1`, as JSON with `status` 0. What fails outside an endpoint is a problem document on every path, the dialects' included: a body over the size limit (413), an unknown path (404) or method (405), a request that runs out of time (504), this instance shedding load (503, with `Retry-After`) and a fault in the server (500). Every response carries its request's ID in `X-Request-Id`.", "version": "0.1.0" }, "paths": { "/createTask": { "post": { "tags": [ "compatible" ], "summary": "Create a task (compatible)", "description": "The createTask call other providers use. The body is\n`{\"clientKey\": \"…\", \"task\": {\"type\": \"TurnstileTaskProxyless\", \"websiteURL\": \"…\", \"websiteKey\": \"…\"}}`;\nthe reply is `{\"errorId\": 0, \"taskId\": \"…\"}`. An `Idempotency-Key` header\nworks as it does on REST. Creations share the key's and the account's\nbudgets, if the service sets any, with `POST /v1/tasks`. Over one, the\nreply is `ERROR_RATE_LIMIT` with `Retry-After`, and nothing is created or\ncharged.", "operationId": "compatCreateTask", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Your ID for this task, 1 to 255 visible ASCII characters, as on `POST /v1/tasks`.", "required": false, "schema": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[!-~]+$" } } ], "requestBody": { "description": "The server reads the body more leniently than its schema, and decides: it takes JSON whatever the Content-Type, as some clients send text/plain, a number wherever it expects text, and `null` for an absent field, and it ignores fields it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "`errorId` 0 with `taskId`, or 1 with `errorCode` and `errorDescription`.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Once the key is known, when its creations have budgets: where the key's and its account's stand, per policy `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Once the key is known, when its creations have budgets: the key's and its account's, per policy `q` units, refilled evenly over `w` seconds." }, "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "With `ERROR_RATE_LIMIT`: seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatCreateReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/feedbackTask": { "post": { "tags": [ "compatible" ], "summary": "Report how a token did (CapSolver)", "description": "CapSolver's `feedbackTask`: `{\"clientKey\": \"…\", \"taskId\": \"…\", \"result\":\n{\"invalid\": true}}` says the site refused the token, `false` that it took\nit; `invalid` may also come beside `result`. Recorded for our staff, never\nrefunded. Without `invalid`, `ERROR_INVALID_REQUEST`.", "operationId": "compatFeedbackTask", "requestBody": { "description": "The server reads the body more leniently than its schema, and decides: it takes JSON whatever the Content-Type, as some clients send text/plain, a number wherever it expects text, and `null` for an absent field, and it ignores fields it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatFeedbackRequest" } } }, "required": true }, "responses": { "200": { "description": "`errorId` 0 with `status: \"success\"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatReportReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/getBalance": { "post": { "tags": [ "compatible" ], "summary": "Get the balance (compatible)", "description": "`{\"clientKey\": \"…\"}`; the reply is `{\"errorId\": 0, \"balance\": 12.3456}`,\nthe available balance in US dollars, printed exactly. Reads share their budgets with REST; over one, the reply is\n`ERROR_RATE_LIMIT` with `Retry-After`.", "operationId": "compatGetBalance", "requestBody": { "description": "The server reads the body more leniently than its schema, and decides: it takes JSON whatever the Content-Type, as some clients send text/plain, a number wherever it expects text, and `null` for an absent field, and it ignores fields it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatBalanceRequest" } } }, "required": true }, "responses": { "200": { "description": "The balance, or an error in the dialect's shape.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Once the key is known: where its budgets for reading stand, and its account's, per policy `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Once the key is known: its budgets for reading, and its account's, per policy `q` units, refilled evenly over `w` seconds." }, "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "With `ERROR_RATE_LIMIT`: seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatBalanceReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/getTaskResult": { "post": { "tags": [ "compatible" ], "summary": "Get a task's result (compatible)", "description": "`{\"clientKey\": \"…\", \"taskId\": \"…\"}`. While the task runs the reply is\n`{\"errorId\": 0, \"status\": \"processing\"}`; once solved it is\n`status: \"ready\"` with `solution.token` and `cost`, and for a challenge\npage `solution.userAgent` and `solution.cookies` too. A failed task, or one\nwhose token expired, replies with `errorId: 1` and its `errorCode`. Polls\nshare the budgets for reads with REST; over one, the reply is\n`ERROR_RATE_LIMIT` with `Retry-After`.", "operationId": "compatGetTaskResult", "requestBody": { "description": "The server reads the body more leniently than its schema, and decides: it takes JSON whatever the Content-Type, as some clients send text/plain, a number wherever it expects text, and `null` for an absent field, and it ignores fields it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatResultRequest" } } }, "required": true }, "responses": { "200": { "description": "The task's state, or an error in the dialect's shape.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Once the key is known: where its budgets for reading stand, and its account's, per policy `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "Once the key is known: its budgets for reading, and its account's, per policy `q` units, refilled evenly over `w` seconds." }, "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "With `ERROR_RATE_LIMIT`: seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatResultReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/healthz": { "get": { "tags": [ "health" ], "summary": "Liveness probe", "description": "Answers while the process can serve HTTP, without checking any dependency.", "operationId": "getLiveness", "responses": { "200": { "description": "The process is up.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/in.php": { "get": { "tags": [ "2captcha" ], "summary": "Submit a task (2Captcha)", "description": "2Captcha's `in.php` for Cloudflare Turnstile: `method=turnstile` with\n`sitekey` and `pageurl`, and optionally `action`, `data`, `proxy` and\n`pingback`. The reply is `OK|`, or `{\"status\": 1, \"request\":\n\"\"}` with `json=1`; poll `res.php` with the ID. Priced, held and\ncharged as `POST /v1/tasks` is; an `Idempotency-Key` header works as it\ndoes there.", "operationId": "twoCaptchaSubmit", "parameters": [ { "name": "key", "in": "query", "description": "Your API key, `zc_live_…`. A missing or malformed one is `ERROR_WRONG_USER_KEY`, an unknown or revoked one `ERROR_KEY_DOES_NOT_EXIST`.", "required": true, "schema": { "type": "string" } }, { "name": "method", "in": "query", "description": "`turnstile`; any other method is `ERROR_BAD_PARAMETERS`.", "required": true, "schema": { "type": "string" }, "example": "turnstile" }, { "name": "sitekey", "in": "query", "description": "The widget's site key.", "required": true, "schema": { "type": "string" } }, { "name": "pageurl", "in": "query", "description": "The page the widget is on: a public http or https page, as `websiteURL` is on REST. Missing or invalid, `ERROR_PAGEURL`.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "The widget's action, if it sets one.", "required": false, "schema": { "type": "string" } }, { "name": "data", "in": "query", "description": "The widget's cData, if it sets one.", "required": false, "schema": { "type": "string" } }, { "name": "pingback", "in": "query", "description": "Where to POST the result once the task ends: 2Captcha's pingback form, `id` and `code`, signed with your callback secret. Any public URL, with no registration.", "required": false, "schema": { "type": "string" } }, { "name": "json", "in": "query", "description": "`1` for JSON replies; `0`, the default, for plain text.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "proxy", "in": "query", "description": "Your proxy as `login:password@host:port` or `host:port`; the task then runs through it.", "required": false, "schema": { "type": "string" } }, { "name": "proxytype", "in": "query", "description": "`HTTP`, the default, or `HTTPS`. SOCKS is not supported yet (`ERROR_PROXY_FORMAT`).", "required": false, "schema": { "type": "string" } }, { "name": "soft_id", "in": "query", "description": "Accepted and ignored.", "required": false, "schema": { "type": "string" } }, { "name": "header_acao", "in": "query", "description": "Accepted and ignored: this service sends no CORS headers.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "pagedata", "in": "query", "description": "Accepted and ignored: Cloudflare challenge pages are not supported.", "required": false, "schema": { "type": "string" } }, { "name": "userAgent", "in": "query", "description": "Accepted and ignored.", "required": false, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Your ID for this task, 1 to 255 visible ASCII characters, as on `POST /v1/tasks`.", "required": false, "schema": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[!-~]+$" } } ], "responses": { "200": { "description": "`OK|`, or an error code such as `ERROR_ZERO_BALANCE`; with `json=1`, the same as JSON.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "With `MAX_USER_TURN`: seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TwoCaptchaReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with an error code.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "tags": [ "2captcha" ], "summary": "Submit a task by POST (2Captcha)", "description": "`in.php` as a POST, the way 2Captcha's own clients send it: the\nparameters as a form (`application/x-www-form-urlencoded` or\n`multipart/form-data`) or a JSON object, and any in the query string too,\nwhich win. The replies are those of `GET /in.php`.", "operationId": "twoCaptchaSubmitForm", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Your ID for this task, 1 to 255 visible ASCII characters, as on `POST /v1/tasks`.", "required": false, "schema": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[!-~]+$" } } ], "requestBody": { "description": "Also taken as `multipart/form-data` or a JSON object.", "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TwoCaptchaSubmit" } } }, "required": true }, "responses": { "200": { "description": "`OK|`, or an error code such as `ERROR_ZERO_BALANCE`; with `json=1`, the same as JSON.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "With `MAX_USER_TURN`: seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TwoCaptchaReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with an error code.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/openapi.json": { "get": { "tags": [ "meta" ], "summary": "This contract", "description": "The OpenAPI 3.1 document that describes this API.", "operationId": "getOpenApi", "responses": { "200": { "description": "The OpenAPI document.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": {} } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/readyz": { "get": { "tags": [ "health" ], "summary": "Readiness probe", "description": "Answers when the service can reach its database, which must reply within\ntwo seconds.", "operationId": "getReadiness", "responses": { "200": { "description": "Ready for traffic.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthStatus" } } } }, "503": { "description": "The database cannot be reached.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reportCorrect": { "post": { "tags": [ "compatible" ], "summary": "Report a token that worked (2Captcha)", "description": "2Captcha's `reportCorrect`: `{\"clientKey\": \"…\", \"taskId\": \"…\"}` says the\nsite took the solved task's token. Recorded for our staff; one report per\ntask, on a task that succeeded.", "operationId": "compatReportCorrect", "requestBody": { "description": "The server reads the body more leniently than its schema, and decides: it takes JSON whatever the Content-Type, as some clients send text/plain, a number wherever it expects text, and `null` for an absent field, and it ignores fields it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatReportRequest" } } }, "required": true }, "responses": { "200": { "description": "`errorId` 0 with `status: \"success\"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatReportReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reportCorrectRecaptcha": { "post": { "tags": [ "compatible" ], "summary": "Report a token that worked (Anti-Captcha)", "description": "Anti-Captcha's `reportCorrectRecaptcha`: the same as `/reportCorrect`.", "operationId": "compatReportCorrectRecaptcha", "requestBody": { "description": "The server reads the body more leniently than its schema, and decides: it takes JSON whatever the Content-Type, as some clients send text/plain, a number wherever it expects text, and `null` for an absent field, and it ignores fields it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatReportRequest" } } }, "required": true }, "responses": { "200": { "description": "`errorId` 0 with `status: \"success\"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatReportReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reportIncorrect": { "post": { "tags": [ "compatible" ], "summary": "Report a refused token (2Captcha)", "description": "2Captcha's `reportIncorrect`: `{\"clientKey\": \"…\", \"taskId\": \"…\"}` says the\nsite refused the solved task's token. It is recorded for our staff, who\nwatch the solvers' quality with it; tasks are final, so it refunds\nnothing. One report per task, on a task that succeeded.", "operationId": "compatReportIncorrect", "requestBody": { "description": "The server reads the body more leniently than its schema, and decides: it takes JSON whatever the Content-Type, as some clients send text/plain, a number wherever it expects text, and `null` for an absent field, and it ignores fields it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatReportRequest" } } }, "required": true }, "responses": { "200": { "description": "`errorId` 0 with `status: \"success\"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatReportReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/reportIncorrectRecaptcha": { "post": { "tags": [ "compatible" ], "summary": "Report a refused token (Anti-Captcha)", "description": "Anti-Captcha's `reportIncorrectRecaptcha`, which its clients send for a\ntoken task: the same as `/reportIncorrect`. Recorded, never refunded.", "operationId": "compatReportIncorrectRecaptcha", "requestBody": { "description": "The server reads the body more leniently than its schema, and decides: it takes JSON whatever the Content-Type, as some clients send text/plain, a number wherever it expects text, and `null` for an absent field, and it ignores fields it does not use.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatReportRequest" } } }, "required": true }, "responses": { "200": { "description": "`errorId` 0 with `status: \"success\"`, or 1 with `errorCode` and `errorDescription`: `ERROR_NO_SUCH_CAPCHA_ID` for a task this key's account does not have, `ERROR_REPORT_NOT_RECORDED` for one that did not succeed, and `ERROR_DUPLICATE_REPORT` for one reported already.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatReportReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with `errorId` 1.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/res.php": { "get": { "tags": [ "2captcha" ], "summary": "Get a result or the balance (2Captcha)", "description": "2Captcha's `res.php`. `action=get&id=` answers\n`CAPCHA_NOT_READY` while the task runs, then `OK|`, or an error\ncode such as `ERROR_CAPTCHA_UNSOLVABLE` (nothing charged) or\n`ERROR_TOKEN_EXPIRED`; `action=get2` adds the price, `OK||`.\n`action=get&ids=,,…` reads up to 100 tasks at once: each one's\ntoken, `CAPCHA_NOT_READY` or error code, in order, joined by `|`.\n`action=reportbad` or `reportgood` with `id` records whether the site\ntook the token (`OK_REPORT_RECORDED`): recorded for our staff, never\nrefunded, as tasks are final. `action=getbalance` answers the available\nbalance in US dollars, such as `12.3456`. With `json=1`, each as\n`{\"status\": …, \"request\": …}`. Reads share their budgets with REST; over\none, the reply is `ERROR: 1005` with `Retry-After`.", "operationId": "twoCaptchaResult", "parameters": [ { "name": "key", "in": "query", "description": "Your API key, as for in.php.", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "`get` for a task's token (or several tasks' with `ids`), `get2` for its token and price, `reportbad` or `reportgood` to say whether the site took its token, or `getbalance` for the available balance. Missing, `ERROR_EMPTY_ACTION`.", "required": true, "schema": { "type": "string" }, "example": "get" }, { "name": "id", "in": "query", "description": "The task's ID, as in.php gave it, for `get`, `get2`, `reportbad` and `reportgood`; a task's UUID from another format works too. Not a task ID, `ERROR_WRONG_ID_FORMAT`; no task of this key's account, `ERROR_WRONG_CAPTCHA_ID`.", "required": false, "schema": { "type": "string" } }, { "name": "ids", "in": "query", "description": "With `action=get`, in place of `id`: up to 100 task IDs, comma-separated. The reply is each one's answer in order, joined by `|`, such as `CAPCHA_NOT_READY|0.AbC…|ERROR_CAPTCHA_UNSOLVABLE`.", "required": false, "schema": { "type": "string" } }, { "name": "json", "in": "query", "description": "`1` for JSON replies; `0`, the default, for plain text.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "The token, `CAPCHA_NOT_READY`, several tasks' answers, `OK_REPORT_RECORDED`, the balance, or an error code; with `json=1`, the same as JSON.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "With `ERROR: 1005`: seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "text/plain": { "schema": { "type": "string" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TwoCaptchaReply" } } } }, "default": { "description": "Only a failure outside the dialect, as RFC 9457 problem details: a body over the size limit (413), a request that ran out of time (504), this instance shedding load (503, with `Retry-After`) or a fault in the server (500). Every other failure is HTTP 200 with an error code.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/abuse-reports": { "post": { "tags": [ "abuse" ], "summary": "Report abuse", "description": "Reports a site that ZeroCaptcha was used against without permission. The\nreport is stored and sent to our staff, who look into it and act by hand:\nsuspending the customer, or refusing tasks for the site. Nothing changes\nautomatically. It needs no key or session. A browser's request must send\nno `Sec-Fetch-Site` but `same-origin` or `none` (`csrf_rejected`).\nReports have a budget per client address.", "operationId": "reportAbuse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewAbuseReport" } } }, "required": true }, "responses": { "202": { "description": "Received: staff will look into it.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AbuseReportReceipt" } } } }, "403": { "description": "A browser's request from another site (`csrf_rejected`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Not a site, nothing said, an evidence link that is not http or https, or not an email address (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many reports from this address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The report cannot be stored now (`service_unavailable`). Retry shortly.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/account": { "get": { "tags": [ "account" ], "summary": "Your account", "description": "The signed-in person's account: its standing, since when it is suspended\nand when it was last appealed, and the getting-started checklist, each\nstep as the server sees it. Owners and members, a suspended account's\ntoo.", "operationId": "getAccountOverview", "responses": { "200": { "description": "The account.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountOverview" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/account-policy": { "get": { "tags": [ "account" ], "summary": "The account policy", "description": "The values the account screens show: link lifetimes, the resend cooldown,\nthe re-authentication window, the address emails come from, the password\nlength, and the current Terms and Acceptable Use Policy versions, which\nsigning up accepts. Public and cacheable for five minutes; reads have a\nbudget per client address.", "operationId": "getAccountPolicy", "responses": { "200": { "description": "The policy.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=300" }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPolicy" } } } }, "429": { "description": "Too many reads from this address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/account/deletion": { "post": { "tags": [ "account" ], "summary": "Delete your account", "description": "Deletes the account at once and for good, confirmed with the owner's\npassword or a passkey. Its keys are revoked, its queued tasks cancelled\n(nothing is charged for them), and everyone's sign-in and personal data\nare erased: its people, sessions, passkeys, billing details, messages to\nsupport and activity log. The balance left is lost, as top-ups are final.\nJournals, top-ups and receipts are kept as the law and reconciliation\nneed them, and task records until their retention ends, without their\ntokens. The session's cookie is cleared. Owner only, with the CSRF\ntoken.", "operationId": "deleteAccount", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccount" } } }, "required": true }, "responses": { "200": { "description": "Deleted; the session's cookie is cleared.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDeleted" } } } }, "401": { "description": "The password or passkey is wrong (`invalid_credentials`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "A member's session, not an owner's (`role_required`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "How you sign in changed after the proof was checked, such as a password reset meanwhile; reload and confirm again (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "A proof that cannot confirm a deletion, such as an app's code (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts, as for log-in (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/account/export": { "get": { "tags": [ "account" ], "summary": "Export your data", "description": "A copy of the account's data as a JSON download\n(`zerocaptcha-export-.json`): for an owner, the account with its\npeople, keys (never the key itself), money, receipts, usage, newest\n1,000 tasks, support messages and activity; for a member, their own\ndata. Never a secret, a token or a proxy. Owners and members, a\nsuspended account's too.", "operationId": "exportAccount", "responses": { "200": { "description": "The data, as a download.", "headers": { "Content-Disposition": { "schema": { "type": "string" }, "description": "`attachment; filename=\"zerocaptcha-export-.json\"`." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountExport" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/accounts": { "post": { "tags": [ "account" ], "summary": "Sign up", "description": "Creates an account for an email address and a password, records that the\nperson accepted the current Terms and Acceptable Use Policy, and signs\nthem in, with a link to verify the address on its way. Creating an API\nkey and adding funds wait for that link to be opened (`email_unverified`);\nnothing else does. An address that already has an account is refused with\n`email_taken`. A browser's request must send no `Sec-Fetch-Site` but\n`same-origin` or `none` (`csrf_rejected`). Sign-ups have a budget per\nclient address, then per email address.", "operationId": "signUp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignUp" } } }, "required": true }, "responses": { "201": { "description": "Signed up and signed in; the cookies are set as a log-in sets them.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "`__Host-zc_session` and `__Host-zc_device`, as log-in sets them." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionView" } } } }, "409": { "description": "The address already has an account (`email_taken`): log in or reset the password.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The password breaks a rule (`weak_password`), or the address is not one (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many sign-ups from this address, or with this email address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/accounts/passkey": { "post": { "tags": [ "account" ], "summary": "Sign up with a passkey", "description": "Checks the new passkey against the challenge `POST\n/v1/accounts/passkey-options` made for `email`, then signs up as `POST\n/v1/accounts` does, with the passkey instead of a password: the account\nhas none until a reset link sets one, and its last passkey cannot be\nremoved while it has none. An address that already has an account is\nrefused with `email_taken`, and the passkey is not kept. A browser's\nrequest must send no `Sec-Fetch-Site` but `same-origin` or `none`\n(`csrf_rejected`).", "operationId": "signUpWithPasskey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeySignUp" } } }, "required": true }, "responses": { "201": { "description": "Signed up and signed in; the cookies are set as log-in sets them.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "`__Host-zc_session` and `__Host-zc_device`, as log-in sets them." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionView" } } } }, "409": { "description": "The address already has an account (`email_taken`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The address is not one, the passkey fails WebAuthn's checks, or its challenge expired, was used, or was for another address (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many sign-ups with this email address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/accounts/passkey-options": { "post": { "tags": [ "account" ], "summary": "Sign up with a passkey", "description": "A WebAuthn challenge to make the passkey a new account for `email` signs\nin with, instead of a password (\"Sign up with a passkey\"). An address\nthat already has an account is refused with `email_taken`. Send the new\npasskey to `POST /v1/accounts/passkey`. Sign-ups have a budget per client\naddress.\nA browser's request must send no `Sec-Fetch-Site` but `same-origin` or\n`none` (`csrf_rejected`).", "operationId": "signUpPasskeyOptions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeySignUpStart" } } }, "required": true }, "responses": { "200": { "description": "The options for `navigator.credentials.create`.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptions" } } } }, "409": { "description": "The address already has an account (`email_taken`): log in or reset the password.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The address is not one (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many sign-ups from this address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/balance": { "get": { "tags": [ "balance" ], "summary": "Get the balance", "description": "The available balance and what is held for tasks in progress.", "operationId": "getBalance", "responses": { "200": { "description": "The balance.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Where the caller's budgets for reading stand: per policy, `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "The caller's budgets for reading: per policy, `q` units, refilled evenly over `w` seconds." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "429": { "description": "Over a budget for reading (`rate_limited`); retry after `Retry-After`.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Where the caller's budgets for reading stand: per policy, `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "The caller's budgets for reading: per policy, `q` units, refilled evenly over `w` seconds." }, "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "session": [] } ] } }, "/v1/billing-details": { "get": { "tags": [ "billing" ], "summary": "Billing details", "description": "What the account's receipts print about it: all optional, and nothing a\npayment needs.", "operationId": "getBillingDetails", "responses": { "200": { "description": "The billing details; each absent until set.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingDetails" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "put": { "tags": [ "billing" ], "summary": "Set billing details", "description": "Replaces the billing details that later receipts print; a receipt\nalready issued keeps the details it was issued with. An absent or empty\nfield clears it. With the session's CSRF token.", "operationId": "putBillingDetails", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingDetails" } } }, "required": true }, "responses": { "200": { "description": "The billing details as they are now.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingDetails" } } } }, "422": { "description": "A field is too long (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/callback-secret": { "get": { "tags": [ "callbacks" ], "summary": "Get the callback secret", "description": "The secret this account's task callbacks are signed with, made on first\nread. Each call carries `ZeroCaptcha-Signature: t=,v1=`,\nthe HMAC-SHA256 of `.` keyed with this secret. Owners only\n(`role_required`).", "operationId": "getCallbackSecret", "responses": { "200": { "description": "The secret.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSecret" } } } }, "403": { "description": "A member, not an owner (`role_required`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/callback-secret/rotate": { "post": { "tags": [ "callbacks" ], "summary": "Rotate the callback secret", "description": "Replaces the secret at once: every call from then on, retries included,\nis signed with the new one. Owners only (`role_required`); written to the\nteam's activity.", "operationId": "rotateCallbackSecret", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The new secret.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackSecret" } } } }, "403": { "description": "A member, not an owner (`role_required`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/contact-messages": { "post": { "tags": [ "support" ], "summary": "Contact us", "description": "Sends a message to support from the public site: stored, and emailed to\nour support inbox. Staff answer by email, at the address given. It needs\nno key or session. A browser's request must send no `Sec-Fetch-Site` but\n`same-origin` or `none` (`csrf_rejected`). Messages have a budget per\nclient address.", "operationId": "sendContactMessage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewContactMessage" } } }, "required": true }, "responses": { "202": { "description": "Received: staff will answer by email.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReceipt" } } } }, "403": { "description": "A browser's request from another site (`csrf_rejected`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Not an email address, no message, one over 5,000 characters, or a subject over 200 (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many messages from this address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The message cannot be stored now (`service_unavailable`). Retry shortly.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/demo/clearance": { "get": { "tags": [ "demo" ], "summary": "Check for a Cloudflare clearance", "description": "Says whether this request carried a `cf_clearance` cookie, the one\nCloudflare sets once a challenge, or a Cloudflare Turnstile widget with\npre-clearance, is passed, and whether it came through Cloudflare's\nnetwork. The demo challenge pages call it from the browser, which sends\nthe cookie that page scripts may not be able to read. The cookie's value\nis never read out, logged or kept, and only Cloudflare can say whether it\nis still valid. It needs no key or session. Requests have the budget per\nclient address that public reads share. Never cached.", "operationId": "getDemoClearance", "responses": { "200": { "description": "What the request carried.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoClearance" } } } }, "429": { "description": "Too many requests from this address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The budget could not be checked now (`service_unavailable`). Retry shortly.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/demo/verify": { "post": { "tags": [ "demo" ], "summary": "Check a demo token", "description": "Asks Cloudflare's siteverify about a token from one of the demo pages'\nCloudflare Turnstile widgets, with that widget's secret, and returns the\nverdict as it came: success, the hostname, the action, the cData and the\nerror codes. Solves nothing: bring a token a widget gave, in a browser or\nthrough a task. A token passes siteverify once, within 300 seconds of the\nsolve. It needs no key or session. A browser's request must send no\n`Sec-Fetch-Site` but `same-origin` or `none` (`csrf_rejected`). Checks\nhave a budget per client address. The token is never logged or kept.", "operationId": "verifyDemoToken", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoVerification" } } }, "required": true }, "responses": { "200": { "description": "Cloudflare's verdict, a failing one included.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoVerdict" } } } }, "403": { "description": "A browser's request from another site (`csrf_rejected`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "An unknown widget, or no token, or not one siteverify takes (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many checks from this address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Cloudflare's siteverify did not answer, or this server does not serve the demo (`service_unavailable`). Retry shortly.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/email-verification": { "post": { "tags": [ "account" ], "summary": "Verify an email address", "description": "Proves an address with the token from a verification link, which the\ndashboard's `/verify-email` page reads from its fragment. It works signed\nout and in another browser too. An expired link, or one a change of\naddress replaced, gets `link_expired` (ask for a new one, signed in with\n`POST /v1/email-verification/resend`, or signed out with the link's own\ntoken and `POST /v1/email-verification/renewal`); a used one gets\n`link_used`. Uses of links have a budget per client address.", "operationId": "verifyEmail", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkToken" } } }, "required": true }, "responses": { "200": { "description": "The address is verified. A link to a new address moves the account to it.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifiedEmail" } } } }, "400": { "description": "Not a link this service made (`link_invalid`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The link was already used (`link_used`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "410": { "description": "The link expired, or a newer one or a change of address replaced it (`link_expired`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/email-verification/renewal": { "post": { "tags": [ "account" ], "summary": "Send a new link from an old one", "description": "For a person signed out, such as in another browser: sends a new\nverification link to the address an expired or replaced link was for, if\nthe account still has to prove it. A link to an address since verified\ngets `link_used`; one to an address the account no longer asks for,\n`link_expired`. The cooldown and the budgets of\n`POST /v1/email-verification/resend` apply.", "operationId": "renewVerificationLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkToken" } } }, "required": true }, "responses": { "202": { "description": "A new link is on its way to the address the old one was for.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSent" } } } }, "400": { "description": "Not a link this service made (`link_invalid`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The address is verified already (`link_used`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "410": { "description": "The account no longer asks to prove the address (`link_expired`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/email-verification/resend": { "post": { "tags": [ "account" ], "summary": "Send the verification email again", "description": "Sends a new verification link to the address the session still has to\nprove: the one it is moving to, or else the account's own while\nunverified. Earlier links keep working until they expire. Another may be\nasked for once the cooldown (`verificationResendCooldown` in the account\npolicy) has passed since the last; before that, `rate_limited` with the\nseconds left in `Retry-After`. With the session's CSRF token.", "operationId": "resendVerificationEmail", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "202": { "description": "A new link is on its way.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSent" } } } }, "409": { "description": "The address is verified, and no change of address is pending (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The cooldown has not passed, or too many emails were asked for (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds until another may be asked for." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/inbound/email": { "post": { "tags": [ "inbound" ], "summary": "Receive an email", "description": "Where the Cloudflare Email Worker posts each email sent to a role address\n(support@, billing@ and the rest), as the raw message, up to 10 MiB; not\nfor customers. It answers 404 unless the server has an inbound secret\n(`ZC_INBOUND_EMAIL_SECRET_FILE`). The request must carry\n`ZeroCaptcha-Inbound-Signature: t=,v1=.\">`, within five minutes of the server's clock and never used\nbefore, and `ZeroCaptcha-Envelope-To`, the address Cloudflare received it\nfor; `ZeroCaptcha-Envelope-From` gives the SMTP sender. The email is filed\nin that address's mailbox of the staff inbox, in the thread it answers. A\nmessage already there, by its Message-ID, changes nothing and is answered\n`duplicate`.", "operationId": "receiveInboundEmail", "requestBody": { "description": "The raw message, as Cloudflare received it.", "content": { "message/rfc822": { "schema": { "type": "string" } } }, "required": true }, "responses": { "200": { "description": "Filed, or already there.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundReceipt" } } } }, "401": { "description": "No signature, one that does not match the body, one over five minutes off, or one used before (`unauthorized`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "This server takes no inbound email (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Over 10 MiB (`payload_too_large`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "No envelope recipient, or a body that is not an email (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "It cannot be stored now (`service_unavailable`); the Worker keeps a copy in the backup mailbox.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/keys": { "get": { "tags": [ "keys" ], "summary": "List keys", "description": "The account's keys, newest first, revoked ones\nincluded, so a task always shows which key made it. The key itself never\nappears: each shows its prefix and its last four characters.", "operationId": "listKeys", "parameters": [ { "name": "limit", "in": "query", "description": "Keys per page, 1 to 100; 100 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "`nextCursor` from the previous page.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of keys.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyPage" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "post": { "tags": [ "keys" ], "summary": "Create a key", "description": "Makes a key and returns it whole, this once: store it at once, as only\nits hash is kept. Any account that is not suspended may make keys\n(`account_suspended`) once the owner asking has confirmed their email\naddress (`email_unverified`, decision 0043), and every task a key makes\nis real and charged. An account may have 20 active keys by default\n(`key_limit_reached`); a key being replaced by its rotation, and a revoked\none, does not count.", "operationId": "createKey", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKey" } } }, "required": true }, "responses": { "201": { "description": "The key, with the key itself, shown this once.", "headers": { "Location": { "schema": { "type": "string" }, "description": "The key: `/v1/keys/{id}`." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedKey" } } } }, "403": { "description": "The owner's email address is not confirmed yet (`email_unverified`): open the link, or ask for another with `POST /v1/email-verification/resend`. Or the account is suspended (`account_suspended`), or the caller is a member, not an owner (`role_required`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/keys/{id}": { "get": { "tags": [ "keys" ], "summary": "Get a key", "description": "One of the account's keys; another account's is not found.", "operationId": "getKey", "parameters": [ { "name": "id", "in": "path", "description": "The key's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The key.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyView" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "keys" ], "summary": "Rename a key, or change where it works from", "description": "The change applies to the key's next request. `allowedIps` replaces the\nwhole allowlist; `null` or an empty list lets the key work from any\naddress. Send `name`, `allowedIps` or both. A key that no longer works\ncannot change (`key_state_conflict`).", "operationId": "updateKey", "parameters": [ { "name": "id", "in": "path", "description": "The key's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKey" } } }, "required": true }, "responses": { "200": { "description": "The key, changed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyView" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/keys/{id}/end-overlap": { "post": { "tags": [ "keys" ], "summary": "End a rotated key's overlap now", "description": "The old key of a rotation stops working at once, as if its overlap had\nrun out. Only a key in its overlap has one to end (`key_state_conflict`).", "operationId": "endKeyOverlap", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the key being replaced.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The key, now revoked.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyView" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/keys/{id}/revoke": { "post": { "tags": [ "keys" ], "summary": "Revoke a key", "description": "The key stops working at once: every request made with it is refused with\n`key_revoked`, or `ERROR_KEY_REVOKED` in the compatible dialect. Tasks it\nalready created run to their end, charged only if they succeed. It stays\nlisted, so tasks still show which key made them. Revoking a key that no\nlonger works changes nothing, so a retry succeeds.", "operationId": "revokeKey", "parameters": [ { "name": "id", "in": "path", "description": "The key's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The key, revoked.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyView" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/keys/{id}/rotate": { "post": { "tags": [ "keys" ], "summary": "Rotate a key", "description": "Makes a new key with the old one's name, scopes and allowlist, and\nreturns it whole, this once. The old key keeps working for\nthe overlap chosen, 1 hour, 24 hours or 7 days, while the new one is\ndeployed; end it sooner with `POST /v1/keys/{id}/end-overlap`. After it,\nthe old key is refused as revoked: `key_revoked`, or `ERROR_KEY_REVOKED`\nin the compatible dialect. A key is rotated once, and only while it works\n(`key_state_conflict`), for an account that is not suspended. It needs no\nconfirmed email address: it replaces a key rather than adding one.", "operationId": "rotateKey", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the key to replace.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateKey" } } }, "required": true }, "responses": { "201": { "description": "The new key, with the key itself, shown this once, and the old key, now expiring.", "headers": { "Location": { "schema": { "type": "string" }, "description": "The new key: `/v1/keys/{id}`." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotatedKey" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/keys/{id}/spend-cap": { "get": { "tags": [ "keys" ], "summary": "A key's spend cap", "description": "The key's daily spend cap, if it has one, and what its tasks created this\nUTC day hold or were charged.", "operationId": "getKeySpendCap", "parameters": [ { "name": "id", "in": "path", "description": "The key's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The cap.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendCap" } } } }, "404": { "description": "No key of this account has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "put": { "tags": [ "keys" ], "summary": "Set a key's spend cap", "description": "Caps what the key's tasks may hold or be charged in one UTC day, or\nremoves the cap with null. A task that would pass it is refused with\n`spend_cap_reached` until midnight UTC. It applies from the next task.\nWith the session's CSRF token.", "operationId": "putKeySpendCap", "parameters": [ { "name": "id", "in": "path", "description": "The key's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewSpendCap" } } }, "required": true }, "responses": { "200": { "description": "The cap as it is now.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpendCap" } } } }, "404": { "description": "No key of this account has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The cap is not whole cents above zero (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/low-balance-alert": { "get": { "tags": [ "billing" ], "summary": "The low-balance email", "description": "Whether the account is emailed when its available balance falls below a\nthreshold, and at which.", "operationId": "getLowBalanceAlert", "responses": { "200": { "description": "The setting.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LowBalanceAlert" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "put": { "tags": [ "billing" ], "summary": "Set the low-balance email", "description": "Sets the threshold, or turns the email off with null. A new threshold\nstarts afresh: the next fall below it sends an email. With the session's\nCSRF token.", "operationId": "putLowBalanceAlert", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewLowBalanceAlert" } } }, "required": true }, "responses": { "200": { "description": "The setting as it is now.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LowBalanceAlert" } } } }, "422": { "description": "The threshold is not whole cents above zero (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/opt-out-requests": { "post": { "tags": [ "opt-out" ], "summary": "Ask to opt a domain out", "description": "Asks for a domain, and everything under it, to be excluded: tasks against\nit refused. The request is stored and sent to our staff, who check that\nyou speak for the domain and answer you by email; nothing changes until\nthey decide. It needs no key or session. A browser's request must send no\n`Sec-Fetch-Site` but `same-origin` or `none` (`csrf_rejected`). Requests\nhave a budget per client address, then per domain.", "operationId": "requestOptOut", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewOptOutRequest" } } }, "required": true }, "responses": { "202": { "description": "Received: staff will answer by email.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptOutReceipt" } } } }, "403": { "description": "A browser's request from another site (`csrf_rejected`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Not a domain, not an email address, or a message over 2,000 characters (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests from this address, or for this domain (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The request cannot be stored now (`service_unavailable`). Retry shortly.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/password-reset": { "post": { "tags": [ "account" ], "summary": "Ask for a password reset link", "description": "Emails a link to choose a new password, if an account uses the address.\nThe reply is the same either way, so nobody can use this to find\naccounts; each new link cancels the old ones. Requests have a budget per\nclient address, then per email address. A browser's request must send no\n`Sec-Fetch-Site` but `same-origin` or `none` (`csrf_rejected`).", "operationId": "requestPasswordReset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetRequest" } } }, "required": true }, "responses": { "202": { "description": "If an account uses the address, a link is on its way.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetRequested" } } } }, "422": { "description": "Not an email address (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests from this address, or for this email address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/password-reset/check": { "post": { "tags": [ "account" ], "summary": "Check a password reset link", "description": "Says whose a live reset link is and when it expires, without using it,\nso the page can show \"For alex@example.com\" before a new password is\ntyped. Uses of links have a budget per client address.", "operationId": "checkPasswordResetLink", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkToken" } } }, "required": true }, "responses": { "200": { "description": "The link is live.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetLink" } } } }, "400": { "description": "Not a link this service made (`link_invalid`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The link was already used (`link_used`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "410": { "description": "The link expired, or a newer one replaced it (`link_expired`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/password-reset/confirm": { "post": { "tags": [ "account" ], "summary": "Choose a new password", "description": "Sets a new password with the token from a reset link, which works once.\nEvery session of the account is signed out, every other reset link\nrevoked, its known devices forgotten, and its owner emailed that the\npassword changed; the address counts as verified. It does not sign in:\nlog in with the new password.", "operationId": "resetPassword", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPassword" } } }, "required": true }, "responses": { "200": { "description": "The password is set; every session is signed out.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordReset" } } } }, "400": { "description": "Not a link this service made (`link_invalid`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The link was already used (`link_used`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "410": { "description": "The link expired, or a newer one replaced it (`link_expired`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The password breaks a rule (`weak_password`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/payment-webhooks/{token}": { "post": { "tags": [ "billing" ], "summary": "Receive a payment webhook", "description": "Where the payment processor posts payment updates; not for customers.\nThe path carries a secret of its own, and the body must carry the\nprocessor's signature over it: an unknown path is 404, a missing or wrong\nsignature 401, and a signed update is answered 200 whatever it held, a\nrepeat included, so the processor stops sending it. A failure on our side\nis 503, which the processor retries.", "operationId": "receivePaymentWebhook", "parameters": [ { "name": "token", "in": "path", "description": "The webhook URL's secret segment.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The processor's payment update, signed in its header.", "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "Received.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookReply" } } } }, "401": { "description": "No signature, or one that does not match the body (`unauthorized`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not a webhook URL of this service (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/prices": { "get": { "tags": [ "prices" ], "summary": "List prices", "description": "What each task type costs: the price a task created now is charged if it\nsucceeds, and the next change already scheduled. It needs no key or\nsession. Production lists approved prices only; a task type without one is\nlisted with no price in effect, and its tasks are refused until it has one.\nA task is always charged the price in effect when it was created. Every\ncaller gets the same reply, which caches may keep for up to five minutes;\nsend the `ETag` of a reply you hold as `If-None-Match` to get 304 while it\nis current. Requests have a budget per client address.", "operationId": "listPrices", "parameters": [ { "name": "If-None-Match", "in": "header", "description": "The `ETag` of a reply you hold. While the prices are unchanged, the reply is 304 with no body.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The prices.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "`public, max-age=300`: any cache may keep the reply for five minutes, or until the next scheduled change if that is sooner." }, "ETag": { "schema": { "type": "string" }, "description": "The reply's strong entity tag. Send it back as `If-None-Match` to get 304 while the prices are unchanged." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceList" } } } }, "304": { "description": "The prices are those of the reply whose `ETag` was sent: keep using it.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "As on the full reply." }, "ETag": { "schema": { "type": "string" }, "description": "The reply's strong entity tag, as sent." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } } }, "429": { "description": "Over the budget of this client address (`rate_limited`); retry after `Retry-After`, and keep a copy of the list rather than asking again.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The prices cannot be read now (`service_unavailable`): the database cannot be reached, or this instance is shedding load. Retry shortly.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When this instance is shedding load, the seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/receipts": { "get": { "tags": [ "billing" ], "summary": "List receipts", "description": "The account's receipts, newest first.", "operationId": "listReceipts", "parameters": [ { "name": "limit", "in": "query", "description": "Receipts per page, 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "`nextCursor` from the previous page.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of receipts.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptPage" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/receipts/{id}": { "get": { "tags": [ "billing" ], "summary": "Get a receipt", "description": "One receipt: as JSON, or with `format=html` or `format=text` as a page to\nprint or save.", "operationId": "getReceipt", "parameters": [ { "name": "id", "in": "path", "description": "The receipt's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "format", "in": "query", "description": "`json` (the default), `html` or `text`.", "required": false, "schema": { "type": "string", "description": "The shape a receipt is sent in.", "enum": [ "json", "html", "text" ] } } ], "responses": { "200": { "description": "The receipt.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } }, "text/html": { "schema": { "type": "string" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "No receipt of this account has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/session": { "get": { "tags": [ "session" ], "summary": "The current session", "description": "Who is signed in, with the session's CSRF token, whether their address is\nverified yet, and until when changes that need a recent sign-in go\nthrough.", "operationId": "getSession", "responses": { "200": { "description": "The signed-in person.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionView" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "post": { "tags": [ "session" ], "summary": "Log in", "description": "Checks an email and password and starts a dashboard session, set as an\nHttpOnly cookie. The response carries the session's CSRF token. Log-in\nneeds no token, as there is no session yet, but a browser's request must\nsend no `Sec-Fetch-Site` but `same-origin` or `none` (`csrf_rejected`).\nAttempts have a budget per client address. Failures have a budget per\ndevice the user has signed in on, which the `__Host-zc_device` cookie set\nat each log-in marks, and one per email address that every other device\nshares; each refills over time. So failures elsewhere never keep the owner\nout of a browser they have signed in on. A log-in from a browser without\nthat cookie is emailed to the user. An account whose address is not yet\nverified logs in as any other. With two-factor on, a correct password\nanswers 202 \"two-factor required\" instead: finish with\n`POST /v1/session/second-factor` from the same browser.", "operationId": "logIn", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LogIn" } } }, "required": true }, "responses": { "201": { "description": "Signed in; the cookies are set.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "`__Host-zc_session`, the session; and `__Host-zc_device`, which marks this browser as a device the user has signed in on, for 30 days from this log-in by default. Both are HttpOnly, Secure and SameSite=Strict; logging out ends the session and keeps the device." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionView" } } } }, "202": { "description": "The password is right and two-factor is on: no session yet. The methods that can finish the log-in, within `expiresAt`.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "`__Host-zc_login`, the pending log-in: HttpOnly, Secure and SameSite=Strict, for 5 minutes by default. It opens no session; only a second factor sent with it does." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecondFactorRequired" } } } }, "401": { "description": "The email or password is wrong (`invalid_credentials`), whichever it is, and whether or not an account uses the email.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts from this address, or too many failures from this device, if the user has signed in on it, or else for this email (`rate_limited`); try again after `Retry-After`. Every email address has a budget, so this says nothing about which have accounts.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "Too many log-ins are waiting for a password check; try again after `Retry-After`.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "tags": [ "session" ], "summary": "Log out", "description": "Ends the current session and clears its cookie; with a session, send its\nCSRF token as `X-CSRF-Token`. Logging out without a session succeeds too,\nso a retry never fails. The device cookie stays, as it opens no session.", "operationId": "logOut", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Signed out; the cookie is cleared.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/session/passkey": { "post": { "tags": [ "session" ], "summary": "Log in with a passkey", "description": "Checks a passkey's answer to `POST /v1/session/passkey-options` and\nstarts a session, as log-in does: a passkey with user verification is two\nfactors, so no second step follows. The answer works once. A browser\nwithout a device cookie of the user's is emailed about, as for log-in. A\nbrowser's request must send no `Sec-Fetch-Site` but `same-origin` or\n`none` (`csrf_rejected`).", "operationId": "logInWithPasskey", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyAnswer" } } }, "required": true }, "responses": { "201": { "description": "Signed in; the cookies are set as log-in sets them.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "`__Host-zc_session` and `__Host-zc_device`, as log-in sets them." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionView" } } } }, "401": { "description": "The answer is not a registered passkey's, not to a live challenge, or fails WebAuthn's checks (`invalid_credentials`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts from this address (`rate_limited`), as for log-in.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/session/passkey-options": { "post": { "tags": [ "session" ], "summary": "Log in with a passkey", "description": "A WebAuthn challenge any of the service's discoverable passkeys may\nanswer, with user verification: \"Log in with a passkey\", with no address\nto type. Send the answer to `POST /v1/session/passkey`. Draws on the\nclient address's log-in budget. A browser's request must send no\n`Sec-Fetch-Site` but `same-origin` or `none` (`csrf_rejected`).", "operationId": "logInPasskeyOptions", "responses": { "200": { "description": "The options for `navigator.credentials.get`.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptions" } } } }, "429": { "description": "Too many attempts from this address (`rate_limited`), as for log-in.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/session/reauthentication": { "post": { "tags": [ "session" ], "summary": "Confirm it's you", "description": "Proves the session's holder is its user again, so that for\n`reauthenticationWindow` more seconds (see the account policy) the session\nmay make the changes that answer `reauthentication_required` otherwise:\nwith the password, a code from the authenticator app, or a passkey\n(ReAuth.dc.html). Password and code attempts count as log-ins do, against\nthe same budgets: a wrong one is `invalid_credentials`, and the session\nstays as it was. With the session's CSRF token.", "operationId": "reauthenticate", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reauthentication" } } }, "required": true }, "responses": { "200": { "description": "Confirmed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reauthenticated" } } } }, "401": { "description": "The password, code or passkey is wrong (`invalid_credentials`); the session is unchanged. Without a session, `unauthorized`.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts from this address, or too many failures (`rate_limited`), as for log-in.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/session/reauthentication/passkey-options": { "post": { "tags": [ "session" ], "summary": "Confirm it's you with a passkey", "description": "A WebAuthn challenge for the session's holder to answer with one of their\npasskeys, with user verification: the answer goes, as the `credential`\nof a `passkey` method, to `POST /v1/session/reauthentication` or to a\nchange that asks for a proof. It works once, for this session, within\nthe ceremony timeout; a new one replaces it. With the session's CSRF\ntoken.", "operationId": "reauthenticationPasskeyOptions", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The options for `navigator.credentials.get`.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptions" } } } }, "429": { "description": "Too many attempts from this address (`rate_limited`), as for log-in.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/session/second-factor": { "post": { "tags": [ "session" ], "summary": "Finish logging in", "description": "Sends the second factor for the pending log-in a correct password made\n(`POST /v1/session` answered 202), from the same browser, with its\n`__Host-zc_login` cookie: a code from the authenticator app, a recovery\ncode, or a passkey. It starts the session as log-in does, and uses up the\npending log-in. Each attempt counts as a log-in attempt, against the same\nbudgets, and a pending log-in allows 5 by default; then, or once it\nexpires, or if the password or a factor changed meanwhile, log in again.\nA browser's request must send no `Sec-Fetch-Site` but `same-origin` or\n`none` (`csrf_rejected`).", "operationId": "finishLogIn", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecondFactor" } } }, "required": true }, "responses": { "201": { "description": "Signed in; the cookies are set as log-in sets them, and `__Host-zc_login` is cleared.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "`__Host-zc_session` and `__Host-zc_device`, as log-in sets them; `__Host-zc_login` cleared." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionView" } } } }, "401": { "description": "The code, recovery code or passkey is wrong (`invalid_credentials`); or no pending log-in is live for this browser, it had its attempts, or a credential changed (`unauthorized`): log in again.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts from this address, or too many failures (`rate_limited`), as for log-in.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/session/second-factor/passkey-options": { "post": { "tags": [ "session" ], "summary": "Finish logging in with a passkey", "description": "A WebAuthn challenge for the pending log-in's user to answer with one of\ntheir passkeys, with user verification; send the answer as the\n`credential` of a `passkey` method to `POST /v1/session/second-factor`.\nNeeds the `__Host-zc_login` cookie, from the browser that sent the\npassword; a new challenge replaces the last. A browser's request must\nsend no `Sec-Fetch-Site` but `same-origin` or `none` (`csrf_rejected`).", "operationId": "finishLogInPasskeyOptions", "responses": { "200": { "description": "The options for `navigator.credentials.get`.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptions" } } } }, "401": { "description": "No pending log-in is live for this browser (`unauthorized`): log in again.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts from this address (`rate_limited`), as for log-in.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/sessions": { "get": { "tags": [ "session" ], "summary": "Your sessions", "description": "Every live session of the signed-in person, this one first, then by last\nactivity: the browser it was opened in, the client's address, when it\nstarted and when it was last active.", "operationId": "listSessions", "responses": { "200": { "description": "The sessions.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionList" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "delete": { "tags": [ "session" ], "summary": "Log out all other sessions", "description": "Ends every session of the signed-in person but the one making the\nrequest.", "operationId": "revokeOtherSessions", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "How many sessions ended.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revoked" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/sessions/{id}": { "delete": { "tags": [ "session" ], "summary": "Log out one session", "description": "Ends one of the signed-in person's sessions, on whatever device it is.\nEnding the one making the request logs out here, and clears its cookie.", "operationId": "revokeSession", "parameters": [ { "name": "id", "in": "path", "description": "The session's ID, from the list.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The session ended.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } } }, "404": { "description": "No live session of yours has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/status": { "get": { "tags": [ "status" ], "summary": "Platform status", "description": "The last 24 hours of the platform, as the status page shows them: the\nshare of finished tasks that succeeded, the median time to a token, and\nthe share of minutes in which the API was serving. A figure drawn from\ntoo few tasks, or with no minute to judge yet, is `null`. It needs no key\nor session. Every caller gets the same reply, which caches may keep for a\nminute. Requests have a budget per client address.", "operationId": "getStatus", "responses": { "200": { "description": "The figures.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "`public, max-age=60`: any cache may keep the reply for a minute." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusReport" } } } }, "429": { "description": "Over the budget of this client address (`rate_limited`); retry after `Retry-After`.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The figures cannot be read now (`service_unavailable`): the database cannot be reached, or this instance is shedding load. A status page shows the status as unknown.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When this instance is shedding load, the seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/support-messages": { "post": { "tags": [ "support" ], "summary": "Write to support", "description": "Sends a message to support from the dashboard: stored, and emailed to our\nsupport inbox. Staff answer by email, at the signed-in person's address.\nA suspended account may write too, and appeals its suspension with\n`topic: appeal`, which reaches staff marked as an appeal. With the\nsession's CSRF token. Messages have a budget per user.", "operationId": "sendSupportMessage", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewSupportMessage" } } }, "required": true }, "responses": { "202": { "description": "Received: staff will answer by email.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportReceipt" } } } }, "409": { "description": "An appeal from an account that is not suspended (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "No message, one over 5,000 characters, or a subject over 200 (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many messages from this person (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "The message cannot be stored now (`service_unavailable`). Retry shortly.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/tasks": { "get": { "tags": [ "tasks" ], "summary": "List tasks", "description": "Newest first, with cursor pagination.", "operationId": "listTasks", "parameters": [ { "name": "status", "in": "query", "description": "Only tasks with this status.", "required": false, "schema": { "$ref": "#/components/schemas/Status" } }, { "name": "limit", "in": "query", "description": "Tasks per page, 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "`nextCursor` from the previous page.", "required": false, "schema": { "type": "string" } }, { "name": "idempotencyKey", "in": "query", "description": "Only the task created with this Idempotency-Key, to recover a reply that was lost.", "required": false, "schema": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[!-~]+$" } } ], "responses": { "200": { "description": "A page of tasks.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Where the caller's budgets for reading stand: per policy, `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "The caller's budgets for reading: per policy, `q` units, refilled evenly over `w` seconds." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskPage" } } } }, "429": { "description": "Over a budget for reading (`rate_limited`); retry after `Retry-After`, and poll less often.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Where the caller's budgets for reading stand: per policy, `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "The caller's budgets for reading: per policy, `q` units, refilled evenly over `w` seconds." }, "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "session": [] } ] }, "post": { "tags": [ "tasks" ], "summary": "Create a task", "description": "Queues a task and holds its price on your balance; the price is charged\nonly if the task succeeds. Send an `Idempotency-Key` to retry safely: for\n24 hours, the same key and request return the first reply instead of a\nsecond task, and the same key with a different request is refused.\nCreations are bounded by your balance and your account's share of the\nqueue, and by no rate budget unless the service sets one.", "operationId": "createTask", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Your ID for this task, 1 to 255 visible ASCII characters.", "required": false, "schema": { "type": "string", "maxLength": 255, "minLength": 1, "pattern": "^[!-~]+$" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTask" } } }, "required": true }, "responses": { "201": { "description": "The task, queued; or, for a retry with the same `Idempotency-Key`, the first reply.", "headers": { "Idempotent-Replayed": { "schema": { "type": "string" }, "description": "`true` when this is the first reply to an earlier request with this `Idempotency-Key`; absent otherwise." }, "Location": { "schema": { "type": "string" }, "description": "The task: `/v1/tasks/{id}`." }, "RateLimit": { "schema": { "type": "string" }, "description": "When the service sets budgets for creations: where they stand, per policy `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "When the caller's creations have budgets: per policy, `q` units, refilled evenly over `w` seconds." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "409": { "description": "A request with this `Idempotency-Key` is still being processed (`idempotency_key_in_use`); retry after `Retry-After` for its reply.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "When the service sets budgets for creations: where they stand, per policy `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "When the caller's creations have budgets: per policy, `q` units, refilled evenly over `w` seconds." }, "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "The queue share is full (`queue_full`), or a budget for creating the service has set is spent (`rate_limited`). Nothing was created or charged; retry after `Retry-After`.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "When the service sets budgets for creations: where they stand, per policy `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "When the caller's creations have budgets: per policy, `q` units, refilled evenly over `w` seconds." }, "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "session": [] } ] } }, "/v1/tasks/events": { "get": { "tags": [ "tasks" ], "summary": "Live task updates", "description": "Server-sent events for the caller's tasks: `task` carries a task (without\nits token) each time it changes, `reset` asks the client to refetch its\nlist because updates were missed. Start from a list's `liveCursor`.\nOpening a stream draws on the caller's budget for reads, as a list read\ndoes; keeping it open costs nothing more. The stream ends when its key or\nsession no longer allows it, or when its client stops taking events; an\naccount may hold only a few streams open at once.", "operationId": "streamTaskEvents", "parameters": [ { "name": "since", "in": "query", "description": "Where to start: `liveCursor` from a task list, or the last event's ID.", "required": false, "schema": { "type": "string" } }, { "name": "Last-Event-ID", "in": "header", "description": "The last event's ID, sent by a reconnecting browser.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "An event stream.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Where the caller's budgets for reading stand: per policy, `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "The caller's budgets for reading: per policy, `q` units, refilled evenly over `w` seconds." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "429": { "description": "Over a budget for reading, or as many streams open as the account, or this server, may hold (`rate_limited`); reconnect less often, or close a stream, and retry after `Retry-After`.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Where the caller's budgets for reading stand: per policy, `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "The caller's budgets for reading: per policy, `q` units, refilled evenly over `w` seconds." }, "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "session": [] } ] } }, "/v1/tasks/{id}": { "get": { "tags": [ "tasks" ], "summary": "Get a task", "description": "The task's status, cost and, while it is valid, its token: for a\nchallenge page, its clearance cookie and the user agent it is bound to.\nA task that named a callback URL shows it with where its delivery stands\nand each attempt: when, the HTTP status, and when the next is due.", "operationId": "getTask", "parameters": [ { "name": "id", "in": "path", "description": "The task's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The task.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Where the caller's budgets for reading stand: per policy, `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "The caller's budgets for reading: per policy, `q` units, refilled evenly over `w` seconds." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskView" } } } }, "429": { "description": "Over a budget for reading (`rate_limited`); retry after `Retry-After`, and poll less often.", "headers": { "RateLimit": { "schema": { "type": "string" }, "description": "Where the caller's budgets for reading stand: per policy, `r` units left and `t` seconds until one more is back." }, "RateLimit-Policy": { "schema": { "type": "string" }, "description": "The caller's budgets for reading: per policy, `q` units, refilled evenly over `w` seconds." }, "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before retrying." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "session": [] } ] } }, "/v1/tasks/{id}/callback/resend": { "post": { "tags": [ "tasks" ], "summary": "Send a task's callback again", "description": "Calls the task's callback URL again, as soon as the worker gets to it,\nwith eight more attempts if it fails: once the callback was delivered or\ngiven up, or after its record was deleted. It is signed and shaped as\nthe first call was, and carries the same `ZeroCaptcha-Delivery` ID while\nits record lasts. A key needs the `tasks:write` scope; a session must be\nan owner's (`role_required`), with the CSRF token. A suspended account\nsends none (`account_suspended`).", "operationId": "resendTaskCallback", "parameters": [ { "name": "id", "in": "path", "description": "The task's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Queued: the callback as it stands now.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskCallback" } } } }, "403": { "description": "A member's session, not an owner's (`role_required`), a key without `tasks:write` (`insufficient_scope`), or a suspended account (`account_suspended`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No task of this account has this ID, or the task names no callback URL (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The task has not ended yet, or its callback is still being delivered (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "session": [] } ] } }, "/v1/tasks/{id}/report": { "post": { "tags": [ "tasks" ], "summary": "Report a task's token", "description": "Says whether the site accepted a solved task's token: `bad` when it\nrefused it, `good` when it worked. The report is recorded for our staff,\nwho watch the solvers' quality with it; tasks are final, so it refunds\nnothing. One report per task, and only on a task that succeeded. Needs\nthe `tasks:write` scope; with a session, the CSRF token.", "operationId": "reportTask", "parameters": [ { "name": "id", "in": "path", "description": "The task's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewTaskReport" } } }, "required": true }, "responses": { "201": { "description": "Recorded.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskReport" } } } }, "404": { "description": "No task of this account has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The task did not succeed, so there is no token to report on, or it has a report already (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api_key": [] }, { "session": [] } ] } }, "/v1/team": { "get": { "tags": [ "team" ], "summary": "Get the team", "description": "Everyone on the account, with their roles, and the invitations still\nopen. Members read it too; only owners change it.", "operationId": "getTeam", "responses": { "200": { "description": "The team.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/team/activity": { "get": { "tags": [ "team" ], "summary": "Get the team's activity", "description": "The latest 100 changes to the team and the callback secret: who made\neach, to whom, and when. Owners only (`role_required`).", "operationId": "getTeamActivity", "responses": { "200": { "description": "The latest changes.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamActivity" } } } }, "403": { "description": "A member, not an owner (`role_required`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/team/invitation": { "post": { "tags": [ "team" ], "summary": "Join a team", "description": "Accepts the invitation in `token`: makes the invited address a user of\nthe account with the invitation's role and `password`, with the address\nverified by the link, records that they accepted the current Terms and\nAcceptable Use Policy, and signs them in. The link then stops working.\nRefused as `check` refuses a link, and with `email_taken` when the\naddress has an account meanwhile. Joins share sign-up's budget per\nclient address.", "operationId": "acceptTeamInvitation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInvitation" } } }, "required": true }, "responses": { "201": { "description": "Joined and signed in; the cookies are set as a log-in sets them.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "`__Host-zc_session` and `__Host-zc_device`, as log-in sets them." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionView" } } } }, "400": { "description": "Not a link this service made (`link_invalid`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Already accepted (`link_used`), or the address has an account (`email_taken`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "410": { "description": "Withdrawn or expired (`link_expired`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The password breaks a rule (`weak_password`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many sign-ups and joins from this address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/team/invitation/check": { "post": { "tags": [ "team" ], "summary": "Check an invitation", "description": "What the invitation link in `token` offers: the address that joins, the\naccount and the role. A link that is not whole is `link_invalid`, one\nwithdrawn or past its 7 days `link_expired`, and one already accepted\n`link_used`. Needs no session.", "operationId": "checkTeamInvitation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationToken" } } }, "required": true }, "responses": { "200": { "description": "The invitation can be accepted.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "description": "Not a link this service made (`link_invalid`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Already accepted (`link_used`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "410": { "description": "Withdrawn or expired (`link_expired`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/team/invites": { "post": { "tags": [ "team" ], "summary": "Invite someone", "description": "Emails the address a link to join this account with `role`; the link\nworks once, for 7 days. Inviting an address again replaces its open\ninvitation with a new one. An address that already has an account is\nrefused with `email_taken`, as an address belongs to one account; one\nalready on this team, or a 21st open invitation, with `state_conflict`.\nInvitations, new or made again, draw on a budget per account and one per\ninvited address (`rate_limited`). Owners only (`role_required`), of an\naccount that is not suspended (`account_suspended`).", "operationId": "inviteTeamMember", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewInvite" } } }, "required": true }, "responses": { "201": { "description": "Invited; the email is on its way.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInvite" } } } }, "403": { "description": "A member, not an owner (`role_required`), or the account is suspended (`account_suspended`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The address has an account (`email_taken`), is on this team already, or the account has 20 open invitations (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The address is not one (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many invitations from this account, or to this address (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/team/invites/{id}": { "delete": { "tags": [ "team" ], "summary": "Withdraw an invitation", "description": "Its link stops working at once. Owners only (`role_required`).", "operationId": "revokeTeamInvite", "parameters": [ { "name": "id", "in": "path", "description": "The invitation's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Withdrawn.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } } }, "403": { "description": "A member, not an owner (`role_required`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No open invitation of this account has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/team/members/{id}": { "delete": { "tags": [ "team" ], "summary": "Remove someone, or leave", "description": "Removes a user from the team: their sign-in and sessions end at once, and\nthe address is free to sign up or be invited again. An owner may remove\nanyone; anyone may remove themselves, which is leaving. The account's\nlast owner can do neither (`state_conflict`).", "operationId": "removeTeamMember", "parameters": [ { "name": "id", "in": "path", "description": "The user's ID: your own to leave.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Removed; if it was you, your session has ended.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } } }, "403": { "description": "A member removing someone else (`role_required`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No one on this account's team has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "They are the account's last owner (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "patch": { "tags": [ "team" ], "summary": "Change someone's role", "description": "Makes someone on the team an owner or a member; it applies to their next\nrequest. The account's last owner cannot become a member\n(`state_conflict`): make someone else an owner first. Owners only\n(`role_required`).", "operationId": "changeTeamRole", "parameters": [ { "name": "id", "in": "path", "description": "The user's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoleChange" } } }, "required": true }, "responses": { "200": { "description": "Their role now.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } } }, "403": { "description": "A member, not an owner (`role_required`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No one on this account's team has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "They are the account's last owner (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/top-ups": { "get": { "tags": [ "billing" ], "summary": "List top-ups", "description": "The account's top-ups, newest first, with what each credited.", "operationId": "listTopUps", "parameters": [ { "name": "limit", "in": "query", "description": "Top-ups per page, 1 to 100; 50 by default.", "required": false, "schema": { "type": "integer", "format": "int32", "maximum": 100, "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "`nextCursor` from the previous page.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of top-ups.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpPage" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "post": { "tags": [ "billing" ], "summary": "Start a top-up", "description": "Creates an invoice for `amount` US dollars at the payment processor and\nreturns its checkout page, where the customer picks a coin and pays. The\nbalance is credited when the processor reports the payment settled, at\nits rate: what arrived, whether short of the invoice or over it. No\nbilling details are needed. A suspended account adds no funds\n(`account_suspended`), and the owner's email address must be confirmed\nfirst (`email_unverified`, decision 0043). With the session's CSRF token.", "operationId": "createTopUp", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewTopUp" } } }, "required": true }, "responses": { "201": { "description": "The top-up, with its checkout page.", "headers": { "Location": { "schema": { "type": "string" }, "description": "The top-up's URL." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUp" } } } }, "403": { "description": "The account is suspended (`account_suspended`), or the owner's email address is not confirmed yet (`email_unverified`): open the link, or ask for another with `POST /v1/email-verification/resend`.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The amount is not whole cents, under $10, or over the maximum if one is set (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "No payment processor is configured, or it did not answer (`payments_unavailable`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/top-ups/{id}": { "get": { "tags": [ "billing" ], "summary": "Get a top-up", "description": "One top-up, with each payment it credited and that credit's receipt.", "operationId": "getTopUp", "parameters": [ { "name": "id", "in": "path", "description": "The top-up's ID.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The top-up.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopUpDetail" } } } }, "404": { "description": "No top-up of this account has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/usage": { "get": { "tags": [ "usage" ], "summary": "Usage per day", "description": "The account's tasks per UTC day, from `from` to `to`, both included: how\nmany it created, how many were solved and how many failed or expired, and\nwhat the solved ones cost, with every day in between, those without a\ntask too. Failed and expired tasks cost nothing. The last 30 days by\ndefault; 92 at most. Days whose task records were dropped, 90 days after\nthe end of their month, are read from the totals kept for them.", "operationId": "getUsage", "parameters": [ { "name": "from", "in": "query", "description": "The first day, such as 2026-09-01; 29 days before `to` by default.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "The last day, included; today (UTC) by default.", "required": false, "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "The account's usage per day.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "422": { "description": "A day is not valid, `from` is after `to`, or the span is longer than 92 days (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/usage/months": { "get": { "tags": [ "usage" ], "summary": "Usage per month", "description": "The account's tasks per UTC month, oldest first, from the month the\naccount was made in to the current one, months without a task too: how\nmany it created, how many were solved and how many failed or expired, and\nwhat the solved ones cost. Task records are dropped 90 days after the end\nof their month; the totals of their month are kept, so every month reads\nthe same before and after.", "operationId": "getUsageMonths", "responses": { "200": { "description": "The account's usage per month.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageMonths" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/email": { "put": { "tags": [ "account" ], "summary": "Change your email address", "description": "Moves the account to a new address once a link sent there is opened;\nuntil then it keeps the one it has, and the links and queued emails to\nany address asked for before stop working. An unverified account uses\nthis to start over with the right address. The reply is the same whether\nor not another account uses the new address; if one does, its owner is\ntold instead, and no link is sent. Needs a recent sign-in\n(`reauthentication_required` otherwise) and the session's CSRF token;\neach change counts against the emails a person may ask for.", "operationId": "changeEmail", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeEmail" } } }, "required": true }, "responses": { "202": { "description": "A link is on its way to the new address.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationSent" } } } }, "403": { "description": "The last sign-in is too old (`reauthentication_required`): re-authenticate, then retry.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Not an address, or the one the account already uses (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/passkeys": { "get": { "tags": [ "account" ], "summary": "Your passkeys", "description": "The signed-in person's passkeys, oldest first: each one's name, whether\nit syncs, when it was added and when it last signed in.", "operationId": "listPasskeys", "responses": { "200": { "description": "The passkeys.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyList" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] }, "post": { "tags": [ "account" ], "summary": "Register the passkey", "description": "Checks a new passkey against the challenge `POST /v1/user/passkeys/options`\nmade for this session, and keeps it: from then on it signs in alone, and\nis a second factor after the password. The account is emailed. With the\nsession's CSRF token.", "operationId": "addPasskey", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPasskeyBody" } } }, "required": true }, "responses": { "201": { "description": "The passkey, kept.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyView" } } } }, "409": { "description": "It is registered already, the person has 20, or a factor changed meanwhile (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "It fails WebAuthn's checks, its challenge expired or was used, or its name is not one (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/passkeys/options": { "post": { "tags": [ "account" ], "summary": "Add a passkey", "description": "A WebAuthn challenge to make a new passkey for the signed-in person, with\nuser verification and a discoverable credential preferred; the passkeys\nthey have are excluded. Asks every time, whatever the recent sign-in:\n`proof` is the password while no second factor is on, and a second\nfactor, never the password alone, once one is. Send the new passkey to\n`POST /v1/user/passkeys` from this session. A person may have 20. With the\nsession's CSRF token.", "operationId": "addPasskeyOptions", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPasskey" } } }, "required": true }, "responses": { "200": { "description": "The options for `navigator.credentials.create`.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyOptions" } } } }, "401": { "description": "The proof is wrong (`invalid_credentials`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The person has 20 passkeys already (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The proof's method cannot confirm this change (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts, as for log-in (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/passkeys/{id}": { "patch": { "tags": [ "account" ], "summary": "Rename a passkey", "description": "Changes the name one of the signed-in person's passkeys shows under.\nWith the session's CSRF token.", "operationId": "renamePasskey", "parameters": [ { "name": "id", "in": "path", "description": "The passkey's ID, from the list.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenamePasskey" } } }, "required": true }, "responses": { "200": { "description": "The passkey, renamed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyView" } } } }, "404": { "description": "No passkey of yours has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/passkeys/{id}/remove": { "post": { "tags": [ "account" ], "summary": "Remove a passkey", "description": "The passkey stops signing in at once. A second factor must confirm it: a\ncode from the authenticator app, a recovery code or a passkey, the one\nbeing removed included, never the password alone. The account keeps a\nway in: its last passkey stays while it has no password. With no second\nfactor left, the recovery codes go too. The account is emailed. With the\nsession's CSRF token.", "operationId": "removePasskey", "parameters": [ { "name": "id", "in": "path", "description": "The passkey's ID, from the list.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovePasskey" } } }, "required": true }, "responses": { "204": { "description": "The passkey is removed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } } }, "401": { "description": "The proof is wrong (`invalid_credentials`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No passkey of yours has this ID (`not_found`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "It is the account's last way in, or a factor changed meanwhile (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The proof is the password, which cannot confirm this change (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts, as for log-in (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/password": { "put": { "tags": [ "account" ], "summary": "Change your password", "description": "Sets a new password, given the current one, which counts as a log-in\nattempt against the same budgets (`invalid_credentials` when wrong).\nNeeds a recent sign-in (`reauthentication_required` otherwise) and the\nsession's CSRF token. Every other session signs out,\nevery reset link is revoked, other known devices are forgotten, and the\nowner is emailed. This session is replaced by a new one, whose cookie the\nreply sets, with a new CSRF token. A password changed by another request\nbetween the check and the change refuses it (`state_conflict`).", "operationId": "changePassword", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePassword" } } }, "required": true }, "responses": { "200": { "description": "The password is changed; the new session's cookie is set.", "headers": { "Set-Cookie": { "schema": { "type": "string" }, "description": "The new `__Host-zc_session`." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionView" } } } }, "401": { "description": "The current password is wrong (`invalid_credentials`); nothing changed.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The last sign-in is too old (`reauthentication_required`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The password, or a factor, changed meanwhile (`state_conflict`); nothing changed here.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The new password breaks a rule (`weak_password`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/two-factor": { "get": { "tags": [ "account" ], "summary": "Your two-factor", "description": "How the signed-in person signs in: whether two-factor is on, the\nauthenticator app and since when, the recovery codes left, the passkeys,\nand whether there is a password.", "operationId": "getTwoFactor", "responses": { "200": { "description": "Where two-factor stands.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwoFactorOverview" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/two-factor/recovery-codes": { "post": { "tags": [ "account" ], "summary": "Make new recovery codes", "description": "Replaces every recovery code with ten new ones, shown this once; the old\nones stop working. Needs two-factor on, and a second factor to confirm\nit: a code from the authenticator app, a recovery code or a passkey,\nnever the password alone. The account is emailed. With the session's\nCSRF token.", "operationId": "newRecoveryCodes", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewRecoveryCodes" } } }, "required": true }, "responses": { "201": { "description": "The new codes, shown this once.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryCodes" } } } }, "401": { "description": "The proof is wrong (`invalid_credentials`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Two-factor is off, or a factor changed meanwhile (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The proof is the password, which cannot confirm this change (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts, as for log-in (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/two-factor/totp": { "post": { "tags": [ "account" ], "summary": "Start an authenticator app", "description": "Makes a secret for an authenticator app and returns it this once, as the\nkey to type and the `otpauth://` URI to show as a QR code. Two-factor is\nnot on yet: confirm it with a code from the app, from this session,\nwithin 15 minutes (`POST /v1/user/two-factor/totp/confirm`). Asks every\ntime, whatever the recent sign-in: `proof` is the password, or a passkey\nor recovery code once a passkey guards the account. A new start replaces\nan unconfirmed one. With the session's CSRF token.", "operationId": "startTotp", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartTotp" } } }, "required": true }, "responses": { "201": { "description": "The secret, shown this once; nothing is on yet.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpEnrollment" } } } }, "401": { "description": "The proof is wrong (`invalid_credentials`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "An authenticator app is on already (`state_conflict`); turn it off first.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The proof's method cannot confirm this change (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts, as for log-in (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/two-factor/totp/confirm": { "post": { "tags": [ "account" ], "summary": "Turn on the authenticator app", "description": "Confirms the app started from this session with a code it shows, which\nturns two-factor on, and returns ten recovery codes this once; any older\ncodes stop working. From then on, logging in with the password asks for\na code. The account is emailed. A wrong code is `validation_failed` and\ncounts as a failed log-in. With the session's CSRF token.", "operationId": "confirmTotp", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmTotp" } } }, "required": true }, "responses": { "200": { "description": "Two-factor is on; the recovery codes, shown this once.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TotpEnabled" } } } }, "409": { "description": "No app was started from this session, or it expired (`state_conflict`); start again.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The code is not the app's (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts, as for log-in (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } }, "/v1/user/two-factor/totp/disable": { "post": { "tags": [ "account" ], "summary": "Turn off the authenticator app", "description": "Removes the authenticator app, which a second factor must confirm: a code\nfrom it, a recovery code or a passkey, never the password alone (\"Two-\nfactor changes always ask\"). Without a passkey left, two-factor is then\noff and the recovery codes go too. The account is emailed. With the\nsession's CSRF token.", "operationId": "disableTotp", "parameters": [ { "name": "X-CSRF-Token", "in": "header", "description": "Required with a session: its CSRF token, `csrfToken` in the session that `POST /v1/session` and `GET /v1/session` return. A change made with a session without it, or with another, is refused with `csrf_rejected`. An API key needs none.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableTotp" } } }, "required": true }, "responses": { "200": { "description": "The app is off; where two-factor stands now.", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TwoFactorOverview" } } } }, "401": { "description": "The proof is wrong (`invalid_credentials`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "No app is on, or a factor changed meanwhile (`state_conflict`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "The proof is the password, which cannot confirm this change (`validation_failed`).", "headers": { "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many attempts, as for log-in (`rate_limited`).", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Seconds to wait before trying again." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "An error, as RFC 9457 problem details.", "headers": { "Retry-After": { "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "When waiting can help, the seconds to wait before retrying: with `rate_limited`, `queue_full` and `idempotency_key_in_use`, and with `service_unavailable` when this instance is shedding load or has too many log-ins waiting." }, "X-Request-Id": { "schema": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "The request's ID: the caller's own `X-Request-Id` when it is well formed, otherwise a new one. A problem document repeats it as `request_id`; quote it when asking for support." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "session": [] } ] } } }, "components": { "schemas": { "AbuseReportReceipt": { "type": "object", "description": "A report, received.", "required": [ "id", "site", "receivedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "receivedAt": { "type": "string", "format": "date-time" }, "site": { "type": "string", "description": "The site as it is kept: its domain, in lowercase ASCII.", "example": "shop.example.com" } } }, "AcceptInvitation": { "type": "object", "description": "Accepting an invitation.", "required": [ "token", "password" ], "properties": { "password": { "type": "string", "format": "password", "description": "At least 8 characters; not the email address; not a common password.", "maxLength": 1024, "minLength": 8 }, "token": { "type": "string", "description": "The `token` from the link's fragment." } }, "additionalProperties": false }, "AccountDeleted": { "type": "object", "description": "A deleted account.", "required": [ "deletedAt", "keysRevoked", "tasksCancelled", "peopleErased", "balanceLost" ], "properties": { "balanceLost": { "$ref": "#/components/schemas/Usd", "description": "The balance that was left, lost with the account: top-ups are final." }, "deletedAt": { "type": "string", "format": "date-time" }, "keysRevoked": { "type": "integer", "format": "int64", "description": "Keys revoked by the deletion.", "minimum": 0 }, "peopleErased": { "type": "integer", "format": "int32", "description": "People whose sign-in and personal data were erased." }, "tasksCancelled": { "type": "integer", "format": "int64", "description": "Queued tasks cancelled, nothing charged for them.", "minimum": 0 } } }, "AccountExport": { "type": "object", "description": "A copy of the account's data, as JSON. An owner's covers the account;\na member's covers them alone, with the sections only owners manage\nnull. Amounts are US dollars with six decimals, as text; times are\nISO 8601.", "required": [ "format", "exportedAt", "account", "you", "supportMessages" ], "properties": { "account": { "type": "object", "description": "Its ID, name, standing and when it was made." }, "activity": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "The team's activity log. Null in a member's export." }, "balance": { "type": [ "object", "null" ], "description": "The balance now, available and held. Null in a member's export." }, "billingDetails": { "type": [ "object", "null" ], "description": "Billing details and the low-balance alert. Null when none were set,\nand in a member's export." }, "credits": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Money added: top-up credits and credits from staff. Task holds and\ncharges are in `usage`. Null in a member's export." }, "exportedAt": { "type": "string", "format": "date-time" }, "format": { "type": "string", "description": "`zerocaptcha-export/1`.", "example": "zerocaptcha-export/1" }, "keys": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Its keys: names, the visible part, scopes, allowlists, spend caps\nand use; never the key itself. Null in a member's export." }, "receipts": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Receipts, as issued. Null in a member's export." }, "supportMessages": { "type": "array", "items": { "type": "object" }, "description": "Messages to support from the dashboard, with staff's replies. A\nmember's export has their own." }, "tasks": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "The newest 1,000 tasks kept (task records are kept about 121 days\nat most), never a token or a proxy. Null in a member's export." }, "team": { "type": [ "object", "null" ], "description": "Its people and invitations. Null in a member's export." }, "topUps": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Top-ups, each with its invoice and state. Null in a member's export." }, "usage": { "type": [ "object", "null" ], "description": "Tasks, charges and spend per UTC day and per month. Null in a\nmember's export." }, "you": { "type": "object", "description": "The person who asked: their address, role, sign-in history, second\nfactors (never a secret), live sessions and the policies they\naccepted." } } }, "AccountOverview": { "type": "object", "description": "Your account.", "required": [ "id", "name", "createdAt", "status", "gettingStarted" ], "properties": { "appealedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When one of its people last appealed this suspension from the\ndashboard; null when none has, or when the account is active. Staff\nanswer by email." }, "createdAt": { "type": "string", "format": "date-time" }, "gettingStarted": { "$ref": "#/components/schemas/GettingStarted" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/AccountStatus" }, "suspendedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the suspension began; null when the account is active." } } }, "AccountPolicy": { "type": "object", "description": "The account policy.", "required": [ "verificationLinkLifetime", "resetLinkLifetime", "verificationResendCooldown", "reauthenticationWindow", "mailFrom", "passwordMinLength", "policies" ], "properties": { "mailFrom": { "type": "string", "format": "email", "description": "The address every email comes from, to search the inbox for." }, "passwordMinLength": { "type": "integer", "description": "The shortest password accepted, in characters.", "minimum": 0 }, "policies": { "$ref": "#/components/schemas/PolicyVersions", "description": "The policy versions signing up accepts." }, "reauthenticationWindow": { "type": "integer", "format": "int64", "description": "How long after signing in or re-authenticating a session may make\nchanges that need a recent sign-in, in seconds.", "minimum": 0 }, "resetLinkLifetime": { "type": "integer", "format": "int64", "description": "How long a password reset link works, in seconds.", "minimum": 0 }, "verificationLinkLifetime": { "type": "integer", "format": "int64", "description": "How long a verification link works, in seconds.", "minimum": 0 }, "verificationResendCooldown": { "type": "integer", "format": "int64", "description": "How long after a verification email another may be asked for, in\nseconds.", "minimum": 0 } } }, "AccountStatus": { "type": "string", "description": "Where an account stands.", "enum": [ "active", "suspended" ] }, "AccountView": { "type": "object", "required": [ "id", "name", "suspended" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "suspended": { "type": "boolean" } } }, "AddPasskey": { "type": "object", "description": "Adding a passkey: proof that it is the user, which a second factor must\ngive once one is on.", "required": [ "proof" ], "properties": { "proof": { "$ref": "#/components/schemas/Proof" } }, "additionalProperties": false }, "AttemptOutcome": { "type": "string", "description": "How one delivery attempt ended.", "enum": [ "delivered", "retry", "failed" ] }, "Balance": { "type": "object", "description": "Your balance.", "required": [ "available", "held", "currency" ], "properties": { "available": { "$ref": "#/components/schemas/Usd", "description": "What new tasks can be held against." }, "currency": { "type": "string", "example": "USD" }, "held": { "$ref": "#/components/schemas/Usd", "description": "Held for tasks that are queued or running." } } }, "BilledTo": { "type": "object", "description": "Whom a receipt was issued to, as they were then.", "required": [ "accountName" ], "properties": { "accountName": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "taxId": { "type": [ "string", "null" ] } } }, "BillingDetails": { "type": "object", "description": "What a receipt says about the account paid for. Every field but the\naccount's name is optional.", "properties": { "address": { "type": [ "string", "null" ], "description": "A postal address, on as many lines as it needs, up to 1,000\ncharacters.", "maxLength": 1000 }, "company": { "type": [ "string", "null" ], "description": "A company name, up to 200 characters.", "maxLength": 200 }, "taxId": { "type": [ "string", "null" ], "description": "A VAT number or other tax ID, up to 100 characters.", "maxLength": 100 } }, "additionalProperties": false }, "CallbackAttempt": { "type": "object", "description": "One delivery attempt.", "required": [ "attempt", "startedAt", "finishedAt", "outcome" ], "properties": { "attempt": { "type": "integer", "format": "int32", "description": "Counted over the callback's life: a re-send carries the count on." }, "error": { "type": [ "string", "null" ], "description": "Why it failed, as the worker saw it; null when it was delivered." }, "finishedAt": { "type": "string", "format": "date-time" }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next attempt is due, after this one failed; null otherwise." }, "outcome": { "$ref": "#/components/schemas/AttemptOutcome" }, "startedAt": { "type": "string", "format": "date-time" }, "statusCode": { "type": [ "integer", "null" ], "format": "int32", "description": "The HTTP status the endpoint answered; null when it gave none, such\nas a timeout or a refused connection." } } }, "CallbackSecret": { "type": "object", "description": "The secret that signs this account's callbacks.", "required": [ "secret", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "`zcsig_…`: the key of the HMAC-SHA256 in each call's\n`ZeroCaptcha-Signature`.", "example": "zcsig_ExampleCallbackSecretShownToOwnersOnly0Z", "pattern": "^zcsig_[0-9A-Za-z]{40}$" } } }, "CallbackStatus": { "type": "string", "description": "Where a task's callback stands.", "enum": [ "waiting", "pending", "delivered", "failed", "expired" ] }, "ChangeEmail": { "type": "object", "description": "A new address for the account.", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } }, "additionalProperties": false }, "ChangePassword": { "type": "object", "description": "A new password, while signed in.", "required": [ "currentPassword", "newPassword" ], "properties": { "currentPassword": { "type": "string", "format": "password", "maxLength": 1024 }, "newPassword": { "type": "string", "format": "password", "description": "At least 12 characters; not the email address; not a common\npassword.", "maxLength": 1024, "minLength": 12 } }, "additionalProperties": false }, "ClearanceCookie": { "type": "object", "description": "A challenge page's clearance cookie.", "required": [ "name", "value" ], "properties": { "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the site stops accepting it, if that is known; `null` when it\nis not. The site's own setting decides (its Challenge Passage,\nCloudflare's default being 30 minutes), and the solver does not\nlearn it, so it is `null` today. `tokenExpiresAt` says until when\nthis API serves the cookie." }, "name": { "type": "string", "description": "Always `cf_clearance`.", "example": "cf_clearance" }, "value": { "type": "string" } } }, "CompatAnyTask": { "oneOf": [ { "$ref": "#/components/schemas/CompatTask" }, { "$ref": "#/components/schemas/CompatChallengeTask" } ], "description": "A Turnstile task, or a Cloudflare challenge page's, told apart by `type`. A missing task or `type` is `ERROR_TASK_ABSENT`, another type, a proxyless challenge among them, `ERROR_TASK_NOT_SUPPORTED`, and any other invalid field `ERROR_INVALID_TASK_DATA`." }, "CompatBalance": { "type": "object", "description": "The available balance.", "required": [ "errorId", "balance" ], "properties": { "balance": { "type": "number", "format": "double", "description": "US dollars, printed exactly as a JSON number: 12.3456, 0, 0.0008." }, "errorId": { "type": "integer", "format": "int32", "description": "0 on success.", "maximum": 0, "minimum": 0 } } }, "CompatBalanceReply": { "oneOf": [ { "$ref": "#/components/schemas/CompatBalance" }, { "$ref": "#/components/schemas/CompatError" } ], "description": "getBalance's reply." }, "CompatBalanceRequest": { "type": "object", "description": "getBalance's body.", "required": [ "clientKey" ], "properties": { "clientKey": { "type": "string", "description": "Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`.", "maxLength": 41, "minLength": 41, "pattern": "^zc_live_[0-9A-Za-z]+$" } } }, "CompatChallengeTask": { "type": "object", "description": "A Cloudflare challenge page's task (`CloudflareChallengeTask`, or\nCapSolver's `AntiCloudflareTask`), in the spellings other providers'\nclients use: the page, in either spelling, and the proxy it needs, as\n`proxy` or the `proxyAddress` fields. A challenge page has no widget: a\n`websiteKey`, `action` or `cdata` is ignored, as are fields such as\n`userAgent` and `html` that other providers take for one.", "required": [ "type" ], "properties": { "proxy": { "type": [ "string", "null" ], "description": "Your proxy as a URL with its port, or give it as the `proxyAddress` fields: a challenge page needs one, as its clearance works only from the proxy's address.", "pattern": "^https?://[^/?#]+:[0-9]+(?:[/?#].*)?$" }, "proxyAddress": { "type": [ "string", "null" ], "description": "The proxy's host name or IP address, which must be public: with `proxyPort`, the alternative to `proxy`.", "maxLength": 253, "minLength": 1 }, "proxyLogin": { "type": [ "string", "null" ], "description": "The proxy's login: at most 255 bytes.", "maxLength": 255 }, "proxyPassword": { "type": [ "string", "null" ], "description": "The proxy's password: at most 255 bytes, and only with `proxyLogin`. Never logged, and deleted when the task finishes.", "maxLength": 255 }, "proxyPort": { "type": [ "integer", "null" ], "description": "The proxy's port, needed with `proxyAddress`; a string of digits works too. The server refuses a port another protocol reserves, such as 25.", "maximum": 65535, "minimum": 1 }, "proxyType": { "type": "string", "description": "How the solver talks to the proxy: `http`, the default, or `https`, in any case. SOCKS is not supported yet.", "enum": [ "http", "https" ] }, "type": { "type": "string", "description": "`CloudflareChallengeTask`, or CapSolver's `AntiCloudflareTask`, in any case: pass a Cloudflare challenge page (the WAF's managed, JS or interactive challenge) through your proxy, for its `cf_clearance` cookie. A clearance works only from the IP address and with the user agent that earned it, so there is no proxyless challenge task: `CloudflareChallengeTaskProxyless` is refused.", "enum": [ "CloudflareChallengeTask", "AntiCloudflareTask" ], "examples": [ "CloudflareChallengeTask" ] }, "websiteURL": { "type": [ "string", "null" ], "format": "uri", "description": "The page the widget is on, or behind the challenge: an http or https URL of at most 2048 characters, without credentials, on its scheme's default port. The server also checks that it names a public domain, not an IP address, a name of one label or one kept for local use such as `localhost`, `*.local` or `*.internal`; the task keeps the URL as the server normalizes it, such as with a lowercase host.", "examples": [ "https://example.com/login" ], "maxLength": 2048, "pattern": "^(?:http://[^/?#@:]+(?::80)?|https://[^/?#@:]+(?::443)?)(?:[/?#].*)?$" }, "websiteUrl": { "type": [ "string", "null" ], "format": "uri", "description": "`websiteURL`, as some clients spell it.", "examples": [ "https://example.com/login" ], "maxLength": 2048, "pattern": "^(?:http://[^/?#@:]+(?::80)?|https://[^/?#@:]+(?::443)?)(?:[/?#].*)?$" } } }, "CompatCreateReply": { "oneOf": [ { "$ref": "#/components/schemas/CompatCreated" }, { "$ref": "#/components/schemas/CompatError" } ], "description": "createTask's reply." }, "CompatCreateRequest": { "type": "object", "description": "createTask's body, as other providers take it.", "required": [ "clientKey", "task" ], "properties": { "callbackUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Where to POST the result once the task ends, signed with your callback secret (`ZeroCaptcha-Signature`): an http or https URL of at most 2048 characters, without credentials, naming a public domain or a public IP address on a port no other protocol reserves. A call that is not answered 2xx is retried with backoff, eight attempts in all over roughly 65 to 95 minutes; one to a name that resolves to a private address is not made. `callbackUrl` in this dialect.", "maxLength": 2048 }, "clientKey": { "type": "string", "description": "Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`.", "maxLength": 41, "minLength": 41, "pattern": "^zc_live_[0-9A-Za-z]+$" }, "task": { "$ref": "#/components/schemas/CompatAnyTask" } } }, "CompatCreated": { "type": "object", "description": "A created task.", "required": [ "errorId", "taskId" ], "properties": { "errorId": { "type": "integer", "format": "int32", "description": "0 on success.", "maximum": 0, "minimum": 0 }, "taskId": { "type": "string", "format": "uuid" } } }, "CompatEnded": { "type": "string", "description": "How a task without a usable token ended.", "enum": [ "ready", "failed" ] }, "CompatError": { "type": "object", "description": "A failed call, in the dialect's shape. When the call found a task that\nended without a usable token, the reply also names the task, how it ended\nand what it cost.", "required": [ "errorId", "errorCode", "errorDescription" ], "properties": { "cost": { "$ref": "#/components/schemas/Usd", "description": "What the task cost: its price when it succeeded, 0.000000 when it did\nnot." }, "errorCode": { "type": "string", "description": "A stable code, such as `ERROR_KEY_DOES_NOT_EXIST`." }, "errorDescription": { "type": "string" }, "errorId": { "type": "integer", "format": "int32", "description": "1 on every failure.", "maximum": 1, "minimum": 1 }, "status": { "$ref": "#/components/schemas/CompatEnded", "description": "`ready` when the task succeeded but its token is no longer usable,\n`failed` when it did not succeed." }, "taskId": { "type": "string", "format": "uuid", "description": "The task, when the failure is the task's own." } } }, "CompatFeedbackRequest": { "type": "object", "description": "CapSolver's feedbackTask body: the task, and whether its token worked.", "required": [ "clientKey", "taskId", "result" ], "properties": { "clientKey": { "type": "string", "description": "Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`.", "maxLength": 41, "minLength": 41, "pattern": "^zc_live_[0-9A-Za-z]+$" }, "result": { "$ref": "#/components/schemas/CompatFeedbackResult" }, "taskId": { "type": "string", "format": "uuid", "description": "The task's ID, as createTask gave it." } } }, "CompatFeedbackResult": { "type": "object", "description": "What the site made of the token.", "required": [ "invalid" ], "properties": { "code": { "type": [ "integer", "null" ], "format": "int64", "description": "Accepted and ignored." }, "invalid": { "type": "boolean", "description": "`true` when the site refused the token, `false` when it took it." }, "message": { "type": [ "string", "null" ], "description": "Accepted and ignored." } } }, "CompatProcessing": { "type": "object", "description": "A task that is waiting or running.", "required": [ "errorId", "taskId", "status" ], "properties": { "errorId": { "type": "integer", "format": "int32", "description": "0 on success.", "maximum": 0, "minimum": 0 }, "status": { "type": "string", "description": "Always `processing`.", "enum": [ "processing" ] }, "taskId": { "type": "string", "format": "uuid" } } }, "CompatReady": { "type": "object", "description": "A solved task, with its token.", "required": [ "errorId", "taskId", "status", "solution", "cost", "createTime", "endTime", "solveCount", "expiresAt" ], "properties": { "cost": { "$ref": "#/components/schemas/Usd", "description": "The price charged for the task." }, "createTime": { "type": "integer", "format": "int64", "description": "When the task was created, in Unix seconds." }, "endTime": { "type": "integer", "format": "int64", "description": "When it was solved, in Unix seconds." }, "errorId": { "type": "integer", "format": "int32", "description": "0 on success.", "maximum": 0, "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the token stops being accepted." }, "solution": { "$ref": "#/components/schemas/CompatSolution" }, "solveCount": { "type": "integer", "format": "int32", "description": "The solve attempts it took." }, "status": { "type": "string", "description": "Always `ready`.", "enum": [ "ready" ] }, "taskId": { "type": "string", "format": "uuid" } } }, "CompatReportReply": { "oneOf": [ { "$ref": "#/components/schemas/CompatReported" }, { "$ref": "#/components/schemas/CompatError" } ], "description": "A report's reply." }, "CompatReportRequest": { "type": "object", "description": "A report's body: the task whose token the site took or refused.", "required": [ "clientKey", "taskId" ], "properties": { "clientKey": { "type": "string", "description": "Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`.", "maxLength": 41, "minLength": 41, "pattern": "^zc_live_[0-9A-Za-z]+$" }, "taskId": { "type": "string", "format": "uuid", "description": "The task's ID, as createTask gave it. One that names no task of this\nkey's account is `ERROR_NO_SUCH_CAPCHA_ID`." } } }, "CompatReported": { "type": "object", "description": "A report, recorded.", "required": [ "errorId", "status" ], "properties": { "errorId": { "type": "integer", "format": "int32", "description": "0 on success.", "maximum": 0, "minimum": 0 }, "status": { "type": "string", "description": "Always `success`.", "enum": [ "success" ] } } }, "CompatResultReply": { "oneOf": [ { "$ref": "#/components/schemas/CompatReady" }, { "$ref": "#/components/schemas/CompatProcessing" }, { "$ref": "#/components/schemas/CompatError" } ], "description": "getTaskResult's reply." }, "CompatResultRequest": { "type": "object", "description": "getTaskResult's body.", "required": [ "clientKey", "taskId" ], "properties": { "clientKey": { "type": "string", "description": "Your API key, `zc_live_…`. A missing or unknown one is `ERROR_KEY_DOES_NOT_EXIST`.", "maxLength": 41, "minLength": 41, "pattern": "^zc_live_[0-9A-Za-z]+$" }, "taskId": { "type": "string", "format": "uuid", "description": "The task's ID, as createTask gave it. One that names no task of this\nkey's account is `ERROR_NO_SUCH_CAPCHA_ID`." } } }, "CompatSolution": { "type": "object", "description": "The token, for the site's form or verification call; for a challenge\npage, its clearance, in the shape CapSolver's `AntiCloudflareTask` gives.", "required": [ "token", "type" ], "properties": { "cookies": { "type": "object", "description": "A challenge page's only: the cookies to send to the site, by name:\n`cf_clearance`.", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "token": { "type": "string", "description": "The Turnstile token; for a challenge page, the `cf_clearance`\ncookie's value." }, "type": { "type": "string", "description": "`turnstile` for a Turnstile token, `cloudflare` for a challenge page's\nclearance.", "enum": [ "turnstile", "cloudflare" ] }, "userAgent": { "type": "string", "description": "A challenge page's only: the `User-Agent` its clearance was earned\nwith. The site accepts the cookie only with it, from your proxy's\naddress." } } }, "CompatTask": { "type": "object", "description": "A Turnstile task, in the spellings other providers' clients use. Where a\nfield has more than one, the first sent wins: `websiteURL`, then\n`websiteUrl`; `action`, then `pageAction` and `metadata.action`; `cdata`,\nthen `cData`, `data`, `turnstileCData` and `metadata.cdata`; `proxy`, then\nthe `proxyAddress` fields. A task needs a `websiteURL` in one spelling.", "required": [ "type", "websiteKey" ], "properties": { "action": { "type": [ "string", "null" ], "description": "The widget's action, if it sets one: up to 32 ASCII letters, digits, `_` and `-`.", "maxLength": 32, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "cData": { "type": [ "string", "null" ], "description": "`cdata`, as some clients name it.", "maxLength": 255, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "cdata": { "type": [ "string", "null" ], "description": "The widget's cData, if it sets one: up to 255 ASCII letters, digits, `_` and `-`.", "maxLength": 255, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "cloudflareTaskType": { "type": "string", "description": "CapMonster Cloud's mode: `token`, or absent, for the widget's token. Its `cf_clearance` and `wait_room` modes are `ERROR_TASK_NOT_SUPPORTED`: use `CloudflareChallengeTask` with your proxy, whose reply gives the clearance and the user agent to send it with.", "enum": [ "token" ] }, "data": { "type": [ "string", "null" ], "description": "`cdata`, as some clients name it.", "maxLength": 255, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "metadata": { "oneOf": [ { "$ref": "#/components/schemas/CompatTaskMetadata" }, { "type": "null" } ] }, "pageAction": { "type": [ "string", "null" ], "description": "`action`, as CapMonster Cloud's clients name it.", "maxLength": 32, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "proxy": { "type": [ "string", "null" ], "description": "Your proxy as a URL with its port, such as `http://user:pass@proxy.example.net:8080`: http or https, as SOCKS is not supported yet. `TurnstileTask` needs one, and `TurnstileTaskProxyless` takes none. The server also checks that the host is public, that the port is not one another protocol reserves, such as 25, and that the login and password are at most 255 bytes each, a password only with a login. Never logged, and deleted when the task finishes.", "pattern": "^(?:https?://[^/?#]+:[0-9]+(?:[/?#].*)?)?$" }, "proxyAddress": { "type": [ "string", "null" ], "description": "The proxy's host name or IP address, which must be public: with `proxyPort`, the alternative to `proxy`.", "maxLength": 253, "minLength": 1 }, "proxyLogin": { "type": [ "string", "null" ], "description": "The proxy's login: at most 255 bytes.", "maxLength": 255 }, "proxyPassword": { "type": [ "string", "null" ], "description": "The proxy's password: at most 255 bytes, and only with `proxyLogin`. Never logged, and deleted when the task finishes.", "maxLength": 255 }, "proxyPort": { "type": [ "integer", "null" ], "description": "The proxy's port, needed with `proxyAddress`; a string of digits works too. The server refuses a port another protocol reserves, such as 25.", "maximum": 65535, "minimum": 1 }, "proxyType": { "type": "string", "description": "How the solver talks to the proxy: `http`, the default, or `https`, in any case. SOCKS is not supported yet.", "enum": [ "http", "https" ] }, "turnstileCData": { "type": [ "string", "null" ], "description": "`cdata`, as some clients name it.", "maxLength": 255, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "type": { "type": "string", "description": "`TurnstileTaskProxyless`, or `TurnstileTask` to solve the widget through your proxy. The same names with CapSolver's `Anti` prefix work too, and case does not matter.", "enum": [ "TurnstileTaskProxyless", "TurnstileTask", "AntiTurnstileTaskProxyLess", "AntiTurnstileTask" ], "examples": [ "TurnstileTaskProxyless" ] }, "websiteKey": { "type": "string", "description": "The widget's site key: 1 to 100 ASCII letters, digits, `_` and `-`.", "examples": [ "0x4AAAAAAAB1cD2eF3gH4iJ5" ], "maxLength": 100, "minLength": 1, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "websiteURL": { "type": [ "string", "null" ], "format": "uri", "description": "The page the widget is on, or behind the challenge: an http or https URL of at most 2048 characters, without credentials, on its scheme's default port. The server also checks that it names a public domain, not an IP address, a name of one label or one kept for local use such as `localhost`, `*.local` or `*.internal`; the task keeps the URL as the server normalizes it, such as with a lowercase host.", "examples": [ "https://example.com/login" ], "maxLength": 2048, "pattern": "^(?:http://[^/?#@:]+(?::80)?|https://[^/?#@:]+(?::443)?)(?:[/?#].*)?$" }, "websiteUrl": { "type": [ "string", "null" ], "format": "uri", "description": "`websiteURL`, as some clients spell it.", "examples": [ "https://example.com/login" ], "maxLength": 2048, "pattern": "^(?:http://[^/?#@:]+(?::80)?|https://[^/?#@:]+(?::443)?)(?:[/?#].*)?$" } } }, "CompatTaskMetadata": { "type": "object", "description": "The widget's action and cData, as some clients nest them.", "properties": { "action": { "type": [ "string", "null" ], "description": "The widget's action, if it sets one: up to 32 ASCII letters, digits, `_` and `-`.", "maxLength": 32, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "cdata": { "type": [ "string", "null" ], "description": "The widget's cData, if it sets one: up to 255 ASCII letters, digits, `_` and `-`.", "maxLength": 255, "pattern": "^[\\-0-9A-Z_a-z]*$" } } }, "ConfirmTotp": { "type": "object", "description": "The code that confirms an authenticator app.", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "The six digits the app shows now.", "pattern": "^[0-9]{6}$" } }, "additionalProperties": false }, "CreateChallengeTask": { "type": "object", "description": "A new Cloudflare challenge page's task, through your proxy: a challenge\npage has no widget, so no `websiteKey`, `action` or `cdata`. Surrounding\nwhitespace is trimmed from every field, and an empty optional field\ncounts as absent.", "required": [ "type", "websiteURL", "proxy" ], "properties": { "callbackUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Where to POST the result once the task ends, signed with your callback secret (`ZeroCaptcha-Signature`): an http or https URL of at most 2048 characters, without credentials, naming a public domain or a public IP address on a port no other protocol reserves. A call that is not answered 2xx is retried with backoff, eight attempts in all over roughly 65 to 95 minutes; one to a name that resolves to a private address is not made. `callbackUrl` in this dialect.", "maxLength": 2048 }, "proxy": { "type": "string", "description": "Your proxy as a URL with its port, such as `http://user:pass@proxy.example.net:8080`: http or https, as SOCKS is not supported yet. The clearance is earned through it and works only from its address. The server also checks that the host is public, that the port is not one another protocol reserves, such as 25, and that the login and password are at most 255 bytes each, a password only with a login. Never logged, and deleted when the task finishes.", "pattern": "^https?://[^/?#]+:[0-9]+(?:[/?#].*)?$" }, "type": { "type": "string", "description": "`CloudflareChallengeTask`, or CapSolver's `AntiCloudflareTask`, in any case: pass a Cloudflare challenge page (the WAF's managed, JS or interactive challenge) through your proxy, for its `cf_clearance` cookie. A clearance works only from the IP address and with the user agent that earned it, so there is no proxyless challenge task: `CloudflareChallengeTaskProxyless` is refused.", "enum": [ "CloudflareChallengeTask", "AntiCloudflareTask" ], "examples": [ "CloudflareChallengeTask" ] }, "websiteURL": { "type": "string", "format": "uri", "description": "The page the widget is on, or behind the challenge: an http or https URL of at most 2048 characters, without credentials, on its scheme's default port. The server also checks that it names a public domain, not an IP address, a name of one label or one kept for local use such as `localhost`, `*.local` or `*.internal`; the task keeps the URL as the server normalizes it, such as with a lowercase host.", "examples": [ "https://example.com/login" ], "maxLength": 2048, "pattern": "^(?:http://[^/?#@:]+(?::80)?|https://[^/?#@:]+(?::443)?)(?:[/?#].*)?$" } }, "additionalProperties": false }, "CreateKey": { "type": "object", "description": "A new key.", "required": [ "name", "scopes" ], "properties": { "allowedIps": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Up to 100 IP addresses or CIDR networks, IPv4 or IPv6, it works from,\nsuch as `203.0.113.24` or `198.51.100.0/24`. A network is written with\nno bits set past its prefix. Absent, `null` or empty: any address.", "example": [ "203.0.113.24", "198.51.100.0/24" ], "maxItems": 100 }, "name": { "type": "string", "description": "A name to tell it apart by, 1 to 100 characters, such as where it\nruns. Surrounding whitespace is trimmed.", "example": "price-monitor", "maxLength": 100, "minLength": 1 }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/KeyScope" }, "description": "What it may do: `tasks`, to create and read tasks, and `balance`, to\nread the balance.", "minItems": 1 } }, "additionalProperties": false }, "CreateTask": { "oneOf": [ { "$ref": "#/components/schemas/CreateTurnstileTask" }, { "$ref": "#/components/schemas/CreateChallengeTask" } ], "description": "A new task: a Turnstile widget's, or a Cloudflare challenge page's, told apart by `type`. Surrounding whitespace is trimmed from every field, and an empty optional field counts as absent." }, "CreateTurnstileTask": { "type": "object", "description": "A new Turnstile task. Surrounding whitespace is trimmed from every\nfield, and an empty optional field counts as absent.", "required": [ "type", "websiteURL", "websiteKey" ], "properties": { "action": { "type": [ "string", "null" ], "description": "The widget's action, if it sets one: up to 32 ASCII letters, digits, `_` and `-`.", "maxLength": 32, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "callbackUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Where to POST the result once the task ends, signed with your callback secret (`ZeroCaptcha-Signature`): an http or https URL of at most 2048 characters, without credentials, naming a public domain or a public IP address on a port no other protocol reserves. A call that is not answered 2xx is retried with backoff, eight attempts in all over roughly 65 to 95 minutes; one to a name that resolves to a private address is not made. `callbackUrl` in this dialect.", "maxLength": 2048 }, "cdata": { "type": [ "string", "null" ], "description": "The widget's cData, if it sets one: up to 255 ASCII letters, digits, `_` and `-`.", "maxLength": 255, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "proxy": { "type": [ "string", "null" ], "description": "Your proxy as a URL with its port, such as `http://user:pass@proxy.example.net:8080`: http or https, as SOCKS is not supported yet. `TurnstileTask` needs one, and `TurnstileTaskProxyless` takes none. The server also checks that the host is public, that the port is not one another protocol reserves, such as 25, and that the login and password are at most 255 bytes each, a password only with a login. Never logged, and deleted when the task finishes.", "pattern": "^(?:https?://[^/?#]+:[0-9]+(?:[/?#].*)?)?$" }, "type": { "type": "string", "description": "`TurnstileTaskProxyless`, or `TurnstileTask` to solve the widget through your proxy. The same names with CapSolver's `Anti` prefix work too, and case does not matter.", "enum": [ "TurnstileTaskProxyless", "TurnstileTask", "AntiTurnstileTaskProxyLess", "AntiTurnstileTask" ], "examples": [ "TurnstileTaskProxyless" ] }, "websiteKey": { "type": "string", "description": "The widget's site key: 1 to 100 ASCII letters, digits, `_` and `-`.", "examples": [ "0x4AAAAAAAB1cD2eF3gH4iJ5" ], "maxLength": 100, "minLength": 1, "pattern": "^[\\-0-9A-Z_a-z]*$" }, "websiteURL": { "type": "string", "format": "uri", "description": "The page the widget is on, or behind the challenge: an http or https URL of at most 2048 characters, without credentials, on its scheme's default port. The server also checks that it names a public domain, not an IP address, a name of one label or one kept for local use such as `localhost`, `*.local` or `*.internal`; the task keeps the URL as the server normalizes it, such as with a lowercase host.", "examples": [ "https://example.com/login" ], "maxLength": 2048, "pattern": "^(?:http://[^/?#@:]+(?::80)?|https://[^/?#@:]+(?::443)?)(?:[/?#].*)?$" } }, "additionalProperties": false }, "CreatedKey": { "type": "object", "description": "A key just made, and the key itself: the only time it is shown.", "required": [ "key", "secret" ], "properties": { "key": { "$ref": "#/components/schemas/KeyView" }, "secret": { "type": "string", "description": "The whole key. Store it now, in a secret manager: only its hash is\nkept, so it can never be shown again.", "example": "zc_live_ExampleKeyShownOnceInThisReply0Zp", "pattern": "^zc_live_[0-9A-Za-z]{33}$" } } }, "Credit": { "type": "object", "description": "One payment's credit to the balance, with its receipt.", "required": [ "amount", "processorStatus", "creditedAt", "receiptId", "receiptNumber" ], "properties": { "amount": { "$ref": "#/components/schemas/Usd" }, "coin": { "type": [ "string", "null" ], "description": "The coin paid with, and how much of it arrived, as the processor\nreported them." }, "coinAmount": { "type": [ "string", "null" ] }, "creditedAt": { "type": "string", "format": "date-time" }, "processorStatus": { "type": "string", "description": "The processor's word for the payment when it was credited, such as\n`finished` or `partially_paid`." }, "receiptId": { "type": "string", "format": "uuid" }, "receiptNumber": { "type": "integer", "format": "int64" } } }, "DeleteAccount": { "type": "object", "description": "An owner's confirmation that the account is to be deleted.", "required": [ "proof" ], "properties": { "proof": { "$ref": "#/components/schemas/Proof", "description": "The owner's password, or a passkey's answer to\n`POST /v1/session/reauthentication/passkey-options`. A code from an\nauthenticator app or a recovery code cannot confirm this." } }, "additionalProperties": false }, "DemoClearance": { "type": "object", "description": "Whether a request carried a Cloudflare clearance.", "required": [ "clearance", "cloudflare" ], "properties": { "clearance": { "type": "boolean", "description": "Whether the request carried a `cf_clearance` cookie. Only Cloudflare\ncan tell whether it is still valid; its value is never read out." }, "cloudflare": { "type": "boolean", "description": "Whether the request came through Cloudflare's network (it carried a\n`CF-Ray` header)." } } }, "DemoVerdict": { "type": "object", "description": "Cloudflare's verdict on a token, as siteverify gave it.", "required": [ "widget", "success", "hostname", "challengeTs", "action", "cdata", "errorCodes", "testSecret" ], "properties": { "action": { "type": [ "string", "null" ], "description": "The widget's action, if it set one." }, "cdata": { "type": [ "string", "null" ], "description": "The widget's cData, if it set one." }, "challengeTs": { "type": [ "string", "null" ], "format": "date-time", "description": "When the widget was solved." }, "errorCodes": { "type": "array", "items": { "type": "string" }, "description": "Cloudflare's error codes, such as `timeout-or-duplicate` for a token\nalready checked or older than 300 seconds; empty on success." }, "hostname": { "type": [ "string", "null" ], "description": "The hostname of the page the widget was solved on." }, "success": { "type": "boolean", "description": "Whether Cloudflare accepted the token." }, "testSecret": { "type": "boolean", "description": "Whether the token was checked with Cloudflare's test secret, which\npasses every token, because this server has no secret for the widget." }, "widget": { "$ref": "#/components/schemas/DemoWidget" } }, "example": { "action": "login", "cdata": "session-42", "challengeTs": "2026-10-01T12:00:00Z", "errorCodes": [], "hostname": "www.example.com", "success": true, "testSecret": false, "widget": "managed" } }, "DemoVerification": { "type": "object", "description": "A token to check.", "required": [ "widget", "token" ], "properties": { "token": { "type": "string", "description": "The token: the widget's `cf-turnstile-response`, or the `token` a\nCloudflare Turnstile task returned for the page, up to 2,048\ncharacters.", "maxLength": 2048, "minLength": 1 }, "widget": { "$ref": "#/components/schemas/DemoWidget", "description": "The demo widget the token came from." } }, "additionalProperties": false }, "DemoWidget": { "type": "string", "description": "One of the demo pages' Cloudflare Turnstile widgets, each a widget of its\nown in the owner's Cloudflare account.", "enum": [ "managed", "non-interactive", "invisible", "pre-clearance" ] }, "DisableTotp": { "type": "object", "description": "Turning the authenticator app off: proof by a second factor.", "required": [ "proof" ], "properties": { "proof": { "$ref": "#/components/schemas/Proof" } }, "additionalProperties": false }, "EmailVerification": { "type": "object", "description": "A verification email still needed.", "required": [ "address", "resendAvailableAt" ], "properties": { "address": { "type": "string", "format": "email", "description": "Where the link goes: the account's own address while unverified, or\nthe one it is moving to." }, "resendAvailableAt": { "type": "string", "format": "date-time", "description": "When another email may be asked for (the resend cooldown)." } } }, "ErrorCode": { "type": "string", "description": "A stable, machine-readable error code. Each one has its own section in\nthe error reference, and renaming one is a breaking API change.", "enum": [ "bad_request", "not_found", "method_not_allowed", "payload_too_large", "internal_error", "service_unavailable", "request_timeout", "unauthorized", "invalid_credentials", "key_revoked", "key_limit_reached", "key_state_conflict", "csrf_rejected", "insufficient_scope", "ip_not_allowed", "account_suspended", "insufficient_funds", "domain_blocked", "validation_failed", "idempotency_key_reused", "idempotency_key_in_use", "queue_full", "rate_limited", "reauthentication_required", "link_invalid", "link_expired", "link_used", "weak_password", "state_conflict", "role_required", "spend_cap_reached", "payments_unavailable", "email_taken", "email_unverified" ] }, "GettingStarted": { "type": "object", "description": "The first steps with a new account, as the Overview's checklist shows\nthem: each is done once, and stays done.", "required": [ "keyCreated", "fundsAdded", "firstTaskSolved", "done" ], "properties": { "done": { "type": "boolean", "description": "All three: the checklist is done, and the Overview hides it." }, "firstTaskSolved": { "type": "boolean", "description": "A task ever succeeded." }, "fundsAdded": { "type": "boolean", "description": "Money was ever added: a top-up credited, or a credit from staff." }, "keyCreated": { "type": "boolean", "description": "An API key was ever created, even one revoked since." } } }, "HealthStatus": { "type": "object", "description": "The body of a passing probe.", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } } }, "InboundOutcome": { "type": "string", "description": "What became of an inbound email.", "enum": [ "stored", "duplicate" ] }, "InboundReceipt": { "type": "object", "description": "An inbound email, received.", "required": [ "outcome", "mailbox", "threadId" ], "properties": { "mailbox": { "$ref": "#/components/schemas/Mailbox" }, "outcome": { "$ref": "#/components/schemas/InboundOutcome" }, "threadId": { "type": "string", "format": "uuid", "description": "The thread it is in." } } }, "Invitation": { "type": "object", "description": "What an invitation offers.", "required": [ "email", "accountName", "role", "expiresAt" ], "properties": { "accountName": { "type": "string" }, "email": { "type": "string", "format": "email", "description": "The address that joins: the one the invitation went to." }, "expiresAt": { "type": "string", "format": "date-time" }, "role": { "$ref": "#/components/schemas/Role" } } }, "InvitationToken": { "type": "object", "description": "An invitation's link, as the join page read it from its fragment.", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "The `token` from the link's fragment." } }, "additionalProperties": false }, "KeyOrigin": { "type": "string", "description": "How a key was made.", "enum": [ "created", "rotation" ] }, "KeyPage": { "type": "object", "description": "One page of keys, newest first.", "required": [ "data", "activeLimit" ], "properties": { "activeLimit": { "type": "integer", "format": "int32", "description": "How many active keys the account may have; keys expiring or revoked\ndo not count.", "minimum": 0 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/KeyView" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; absent on the last page." } } }, "KeyScope": { "type": "string", "description": "What a key may do, as its owner grants it: each stands for the scopes the\nAPI checks for one kind of work.", "enum": [ "tasks", "balance" ] }, "KeyState": { "type": "string", "description": "Where a key stands.", "enum": [ "active", "expiring", "revoked" ] }, "KeyView": { "type": "object", "description": "An API key, as its owner sees it. The key itself is never here: it is\nshown once, when it is made.", "required": [ "id", "name", "scopes", "displayPrefix", "state", "createdAt", "origin" ], "properties": { "allowedIps": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "The addresses and CIDR networks it works from, such as `203.0.113.24`\nor `198.51.100.0/24`; absent: any address.", "example": [ "203.0.113.24", "198.51.100.0/24" ] }, "createdAt": { "type": "string", "format": "date-time" }, "dailyCap": { "oneOf": [ { "$ref": "#/components/schemas/Usd", "description": "Its daily spend cap: the most its tasks may spend in one UTC day;\nnull when it has none, as keys start (`PUT /v1/keys/{id}/spend-cap`)." }, { "type": "null" } ] }, "displayPrefix": { "type": "string", "description": "The key's first characters, such as `zc_live_8K2p`.", "example": "zc_live_8K2p", "pattern": "^zc_live_[0-9A-Za-z]{4}$" }, "displaySuffix": { "type": [ "string", "null" ], "description": "The key's last four characters, such as `f41c`; absent for a key made\nbefore they were kept.", "example": "f41c", "pattern": "^[0-9A-Za-z]{4}$" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "While it is expiring: when it stops working." }, "id": { "type": "string", "format": "uuid" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it last passed authentication. Written in batches, so it can be\nup to half a minute behind by default." }, "lastUsedIp": { "type": [ "string", "null" ], "description": "The address its last authenticated request came from.", "example": "203.0.113.24" }, "name": { "type": "string", "description": "Its owner's name for it.", "example": "price-monitor" }, "origin": { "$ref": "#/components/schemas/KeyOrigin" }, "replacedBy": { "type": [ "string", "null" ], "format": "uuid", "description": "The key made by rotating it, which replaces it." }, "replaces": { "type": [ "string", "null" ], "format": "uuid", "description": "The key it replaced, when it was made by rotation." }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Once it is revoked: when it stopped working." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/KeyScope" }, "description": "What it may do: `tasks`, to create and read tasks, and `balance`, to\nread the balance." }, "state": { "$ref": "#/components/schemas/KeyState" } } }, "LinkToken": { "type": "object", "description": "A token from an email link.", "required": [ "token" ], "properties": { "token": { "type": "string", "description": "The token in the link's fragment: what follows `#token=`.", "maxLength": 43, "minLength": 43, "pattern": "^[0-9A-Za-z]{43}$" } }, "additionalProperties": false }, "LogIn": { "type": "object", "description": "Log-in details.", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "password": { "type": "string", "format": "password", "maxLength": 1024 } }, "additionalProperties": false }, "LowBalanceAlert": { "type": "object", "description": "The low-balance email's setting.", "properties": { "notifiedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the last one went out, if it has not been re-armed by a top-up\nsince." }, "threshold": { "oneOf": [ { "$ref": "#/components/schemas/Usd", "description": "The email goes out when the available balance falls below this; null\nwhen the email is off, as it is until set." }, { "type": "null" } ] } } }, "Mailbox": { "type": "string", "description": "A role mailbox: the address a thread was written to.", "enum": [ "support", "billing", "security", "privacy", "abuse", "legal", "hello", "postmaster", "dmarc" ] }, "NewAbuseReport": { "type": "object", "description": "A report of abuse.", "required": [ "site", "what" ], "properties": { "email": { "type": "string", "format": "email", "description": "Where staff may answer you, if you want an answer.", "maxLength": 320 }, "evidenceUrl": { "type": "string", "format": "uri", "description": "A link to evidence, such as logs or a screenshot: `http` or `https`,\nup to 2,048 characters.", "maxLength": 2048 }, "site": { "type": "string", "description": "The site ZeroCaptcha was used against: its domain, such as\n`shop.example.com`, or an address on it.", "example": "shop.example.com", "maxLength": 2048 }, "what": { "type": "string", "description": "What happened: 1 to 5,000 characters.", "maxLength": 5000, "minLength": 1 } }, "additionalProperties": false }, "NewContactMessage": { "type": "object", "description": "A message to support from the public contact form.", "required": [ "email", "message" ], "properties": { "email": { "type": "string", "format": "email", "description": "Where staff answer you.", "example": "you@example.com", "maxLength": 320 }, "message": { "type": "string", "description": "The message: 1 to 5,000 characters.", "maxLength": 5000, "minLength": 1 }, "subject": { "type": "string", "description": "What it is about, in a line: up to 200 characters. Left out, it is\n\"Message from the contact form\".", "maxLength": 200 } }, "additionalProperties": false }, "NewInvite": { "type": "object", "description": "An invitation to make.", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "role": { "$ref": "#/components/schemas/Role" } }, "additionalProperties": false }, "NewLowBalanceAlert": { "type": "object", "description": "A new setting.", "properties": { "threshold": { "type": [ "string", "null" ], "description": "US dollars in whole cents, such as `\"5.00\"`; null turns the email off.", "example": "5.00", "pattern": "^\\d{1,9}(\\.\\d{1,2})?$" } }, "additionalProperties": false }, "NewOptOutRequest": { "type": "object", "description": "A site owner's request to have their domain excluded.", "required": [ "domain", "email" ], "properties": { "domain": { "type": "string", "description": "The domain to exclude, such as `example.com`; everything under it is\nexcluded with it. An internationalized one is kept in ASCII.", "example": "example.com", "maxLength": 253 }, "email": { "type": "string", "format": "email", "description": "Where staff answer you.", "example": "owner@example.com", "maxLength": 320 }, "message": { "type": "string", "description": "Anything staff should know, such as how they can confirm you run the\nsite: up to 2,000 characters.", "maxLength": 2000 } }, "additionalProperties": false }, "NewPasskeyBody": { "type": "object", "description": "A new passkey, answering `POST /v1/user/passkeys/options`.", "required": [ "credential" ], "properties": { "credential": { "type": "object", "description": "The new passkey (`RegistrationResponseJSON`, WebAuthn Level 3), as\n`PublicKeyCredential.toJSON()` gives it." }, "name": { "type": "string", "description": "A name to tell it apart by, 1 to 100 characters; by default its\nauthenticator's model when known, or \"Passkey\".", "maxLength": 100, "minLength": 1 } }, "additionalProperties": false }, "NewPassword": { "type": "object", "description": "A new password, by a reset link.", "required": [ "token", "password" ], "properties": { "password": { "type": "string", "format": "password", "description": "At least 12 characters; not the email address; not a common\npassword.", "maxLength": 1024, "minLength": 12 }, "token": { "type": "string", "maxLength": 43, "minLength": 43, "pattern": "^[0-9A-Za-z]{43}$" } }, "additionalProperties": false }, "NewRecoveryCodes": { "type": "object", "description": "A new set of codes: proof by a second factor.", "required": [ "proof" ], "properties": { "proof": { "$ref": "#/components/schemas/Proof" } }, "additionalProperties": false }, "NewSpendCap": { "type": "object", "description": "A new cap.", "properties": { "dailyCap": { "type": [ "string", "null" ], "description": "US dollars a day in whole cents, such as `\"20.00\"`; null removes the\ncap.", "example": "20.00", "pattern": "^\\d{1,9}(\\.\\d{1,2})?$" } }, "additionalProperties": false }, "NewSupportMessage": { "type": "object", "description": "A message to support from the dashboard. The answer goes to the signed-in\nperson's email address.", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "The message: 1 to 5,000 characters. Task IDs help.", "maxLength": 5000, "minLength": 1 }, "subject": { "type": "string", "description": "What it is about, in a line: up to 200 characters. Left out, it is\n\"Question from the dashboard\".", "example": "A charge I don't recognise", "maxLength": 200 }, "topic": { "$ref": "#/components/schemas/SupportTopic", "description": "`question`, the default, or `appeal`: an appeal of the account's\nsuspension, which only a suspended account may send. Left out, a\nquestion. An appeal without a subject is \"Appeal of a suspension\"." } }, "additionalProperties": false }, "NewTaskReport": { "type": "object", "description": "A report on a task.", "required": [ "verdict" ], "properties": { "verdict": { "$ref": "#/components/schemas/Verdict", "description": "`bad` when the site refused the token, `good` when it accepted it." } }, "additionalProperties": false }, "NewTopUp": { "type": "object", "description": "A top-up to start.", "required": [ "amount" ], "properties": { "amount": { "type": "string", "description": "US dollars in whole cents, such as `\"25\"` or `\"25.50\"`: at least 10,\nand at most the configured maximum, if one is set (none by default).", "example": "25.00", "pattern": "^\\d{1,9}(\\.\\d{1,2})?$" } }, "additionalProperties": false }, "OptOutReceipt": { "type": "object", "description": "A request, received: staff answer it by email.", "required": [ "id", "domain", "receivedAt" ], "properties": { "domain": { "type": "string", "description": "The domain as it is kept: lowercase ASCII.", "example": "example.com" }, "id": { "type": "string", "format": "uuid" }, "receivedAt": { "type": "string", "format": "date-time" } } }, "Overlap": { "type": "string", "description": "How long the old key keeps working after a rotation.", "enum": [ "1h", "24h", "7d" ] }, "PasskeyAnswer": { "type": "object", "description": "A passkey's answer.", "required": [ "credential" ], "properties": { "credential": { "type": "object", "description": "The `PublicKeyCredential` as JSON (`AuthenticationResponseJSON`,\nWebAuthn Level 3), as `PublicKeyCredential.toJSON()` gives it." } }, "additionalProperties": false }, "PasskeyList": { "type": "object", "description": "The signed-in person's passkeys.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PasskeyView" }, "description": "Oldest first, as Settings lists them." } } }, "PasskeyOptions": { "type": "object", "description": "A WebAuthn challenge, for the browser to answer.", "required": [ "publicKey", "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time", "description": "When the challenge stops working." }, "publicKey": { "type": "object", "description": "`PublicKeyCredentialCreationOptionsJSON` or\n`PublicKeyCredentialRequestOptionsJSON` (WebAuthn Level 3): read it\nwith `PublicKeyCredential.parseCreationOptionsFromJSON` or\n`parseRequestOptionsFromJSON`, and pass it as `publicKey` to\n`navigator.credentials.create` or `get`. User verification is always\nrequired." } } }, "PasskeySignUp": { "type": "object", "description": "A new account with a passkey instead of a password.", "required": [ "email", "credential" ], "properties": { "credential": { "type": "object", "description": "The new passkey (`RegistrationResponseJSON`, WebAuthn Level 3), as\n`PublicKeyCredential.toJSON()` gives it." }, "email": { "type": "string", "format": "email", "description": "The address the challenge was asked for.", "maxLength": 320 } }, "additionalProperties": false }, "PasskeySignUpStart": { "type": "object", "description": "The address a passkey sign-up is for.", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } }, "additionalProperties": false }, "PasskeyView": { "type": "object", "description": "One of the signed-in person's passkeys.", "required": [ "id", "name", "synced", "createdAt" ], "properties": { "createdAt": { "type": "string", "format": "date-time", "description": "\"Added 4 Sep\"." }, "id": { "type": "string", "format": "uuid" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "\"Last used today\"; null until it signs in." }, "name": { "type": "string", "description": "Its owner's name for it, such as \"Touch ID on my laptop\"." }, "synced": { "type": "boolean", "description": "Whether it may be synced to the owner's other devices (backup\neligible), as passkeys in a password manager are." } } }, "PasswordReset": { "type": "object", "description": "The password is set; every session is signed out.", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The account's address, to log in with." } } }, "PolicyVersions": { "type": "object", "required": [ "terms", "acceptableUse" ], "properties": { "acceptableUse": { "type": "string" }, "terms": { "type": "string" } } }, "PriceList": { "type": "object", "description": "The prices of every task type the API takes.", "required": [ "data", "currency" ], "properties": { "currency": { "type": "string", "example": "USD" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskPrice" }, "description": "One entry per task type and mode, in a fixed order." } }, "example": { "currency": "USD", "data": [ { "current": { "approved": true, "effectiveFrom": "2026-10-01T00:00:00Z", "price": "0.000800" }, "mode": "proxyless", "next": { "approved": true, "effectiveFrom": "2027-01-01T00:00:00Z", "price": "0.000900" }, "type": "TurnstileTaskProxyless" }, { "current": { "approved": true, "effectiveFrom": "2026-10-01T00:00:00Z", "price": "0.000700" }, "mode": "proxy", "next": null, "type": "TurnstileTask" }, { "current": { "approved": true, "effectiveFrom": "2026-10-01T00:00:00Z", "price": "0.001200" }, "mode": "proxy", "next": null, "type": "CloudflareChallengeTask" } ] } }, "PricePoint": { "type": "object", "description": "A price, and when it takes effect.", "required": [ "price", "effectiveFrom", "approved" ], "properties": { "approved": { "type": "boolean", "description": "Whether an admin approved it. Production publishes approved prices\nonly; local development and staging publish drafts too, as `false`." }, "effectiveFrom": { "type": "string", "format": "date-time", "description": "When it takes effect, or took effect.", "example": "2026-10-01T00:00:00Z" }, "price": { "$ref": "#/components/schemas/Usd", "description": "The price of one solved task, exact to the micro-dollar." } } }, "Problem": { "type": "object", "description": "Problem details (RFC 9457), sent as `application/problem+json` with every\n4xx and 5xx response.", "required": [ "type", "title", "status", "instance", "code", "request_id" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode", "description": "The stable, machine-readable error code." }, "detail": { "type": "string", "description": "What went wrong in this occurrence. Never present on 5xx responses." }, "instance": { "type": "string", "format": "uri-reference", "description": "The path of the request that failed." }, "request_id": { "type": "string", "description": "The request's ID, also sent in the `x-request-id` header; quote it\nwhen asking for support." }, "status": { "type": "integer", "format": "int32", "description": "The HTTP status code of the response.", "maximum": 599, "minimum": 400 }, "title": { "type": "string", "description": "A short summary of the problem type." }, "type": { "type": "string", "format": "uri", "description": "Identifies the problem type: a link to its section of the error\nreference, which ends in `#` and the `code`." } } }, "Proof": { "oneOf": [ { "type": "object", "description": "The account's password.", "required": [ "password", "method" ], "properties": { "method": { "type": "string", "enum": [ "password" ] }, "password": { "type": "string", "format": "password", "maxLength": 1024 } } }, { "type": "object", "description": "A code from the authenticator app.", "required": [ "code", "method" ], "properties": { "code": { "type": "string", "pattern": "^[0-9]{6}$" }, "method": { "type": "string", "enum": [ "totp" ] } } }, { "type": "object", "description": "One of the recovery codes, which it uses up.", "required": [ "code", "method" ], "properties": { "code": { "type": "string", "maxLength": 64, "minLength": 1 }, "method": { "type": "string", "enum": [ "recoveryCode" ] } } }, { "type": "object", "description": "A passkey's answer to `POST /v1/session/reauthentication/passkey-options`:\nthe `AuthenticationResponseJSON` of WebAuthn Level 3, as\n`PublicKeyCredential.toJSON()` gives it.", "required": [ "credential", "method" ], "properties": { "credential": { "type": "object" }, "method": { "type": "string", "enum": [ "passkey" ] } } } ], "description": "Proof that the person at a session is its user, sent with a change that\nmust always ask." }, "Reauthenticated": { "type": "object", "description": "The session, freshly authenticated.", "required": [ "authenticatedAt", "recentAuthUntil" ], "properties": { "authenticatedAt": { "type": "string", "format": "date-time" }, "recentAuthUntil": { "type": "string", "format": "date-time", "description": "Until when changes that need a recent sign-in go through." } } }, "Reauthentication": { "oneOf": [ { "type": "object", "description": "The account's password.", "required": [ "password", "method" ], "properties": { "method": { "type": "string", "enum": [ "password" ] }, "password": { "type": "string", "format": "password", "maxLength": 1024 } } }, { "type": "object", "description": "A code from the authenticator app.", "required": [ "code", "method" ], "properties": { "code": { "type": "string", "pattern": "^[0-9]{6}$" }, "method": { "type": "string", "enum": [ "totp" ] } } }, { "type": "object", "description": "A passkey's answer to `POST /v1/session/reauthentication/passkey-options`:\nthe `AuthenticationResponseJSON` of WebAuthn Level 3.", "required": [ "credential", "method" ], "properties": { "credential": { "type": "object" }, "method": { "type": "string", "enum": [ "passkey" ] } } } ], "description": "How the person proves it is them." }, "Receipt": { "type": "object", "description": "A receipt for money credited to the balance.", "required": [ "id", "number", "issuedAt", "amount", "invoiceAmount", "outcome", "method", "topUpId", "billedTo" ], "properties": { "amount": { "$ref": "#/components/schemas/Usd", "description": "What was credited to the balance." }, "billedTo": { "$ref": "#/components/schemas/BilledTo" }, "id": { "type": "string", "format": "uuid" }, "invoiceAmount": { "$ref": "#/components/schemas/Usd", "description": "The amount of the invoice it paid." }, "issuedAt": { "type": "string", "format": "date-time" }, "method": { "type": "string", "description": "How it was paid, such as \"USDTTRC20 via NOWPayments\"." }, "number": { "type": "integer", "format": "int64", "description": "Its number: receipts are numbered 1, 2, 3 ... without gaps." }, "outcome": { "$ref": "#/components/schemas/ReceiptOutcome" }, "topUpId": { "type": "string", "format": "uuid" } } }, "ReceiptOutcome": { "type": "string", "description": "How the payment behind a receipt compared with its invoice.", "enum": [ "paid", "underpaid", "overpaid" ] }, "ReceiptPage": { "type": "object", "description": "One page of receipts, newest first.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Receipt" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; absent on the last page." } } }, "Received": { "type": "string", "description": "What became of a webhook.", "enum": [ "credited", "recorded", "duplicate", "unmatched", "ignored" ] }, "RecoveryCodes": { "type": "object", "description": "A new set of recovery codes, shown this once.", "required": [ "recoveryCodes" ], "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string" }, "description": "Ten codes, each good for one log-in without the second factor. Only\ntheir digests are kept: this is the only time they are shown.", "example": [ "7kq2-x9mf-c4tn", "2wpa-h8rz-v3ld" ] } } }, "RemovePasskey": { "type": "object", "description": "Removing a passkey: proof by a second factor.", "required": [ "proof" ], "properties": { "proof": { "$ref": "#/components/schemas/Proof" } }, "additionalProperties": false }, "RenamePasskey": { "type": "object", "description": "A passkey's new name.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "1 to 100 characters; surrounding whitespace is trimmed.", "maxLength": 100, "minLength": 1 } }, "additionalProperties": false }, "ResetLink": { "type": "object", "description": "What a live reset link is for.", "required": [ "email", "expiresAt" ], "properties": { "email": { "type": "string", "format": "email", "description": "The account's address, for \"For alex@example.com\" and a password\nmanager's username field." }, "expiresAt": { "type": "string", "format": "date-time" } } }, "ResetRequest": { "type": "object", "description": "Whom to send a reset link.", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 } }, "additionalProperties": false }, "ResetRequested": { "type": "object", "description": "A reset link asked for.", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The address, as the service reads it. A link goes there only if an\naccount uses it; the reply is the same either way." } } }, "Revoked": { "type": "object", "description": "Sessions ended.", "required": [ "revoked" ], "properties": { "revoked": { "type": "integer", "format": "int64", "minimum": 0 } } }, "Role": { "type": "string", "description": "What a user may do in their account.", "enum": [ "owner", "member" ] }, "RoleChange": { "type": "object", "description": "A new role.", "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/Role" } }, "additionalProperties": false }, "RotateKey": { "type": "object", "description": "A rotation.", "required": [ "overlap" ], "properties": { "overlap": { "$ref": "#/components/schemas/Overlap", "description": "How long the old key keeps working while the new one is deployed." } }, "additionalProperties": false }, "RotatedKey": { "type": "object", "description": "A rotation: the new key, the key itself, shown this once, and the old key,\nwhich now expires.", "required": [ "key", "secret", "previous" ], "properties": { "key": { "$ref": "#/components/schemas/KeyView" }, "previous": { "$ref": "#/components/schemas/KeyView", "description": "The key it replaces, which works until its `expiresAt`." }, "secret": { "type": "string", "description": "The whole new key. Store it now: only its hash is kept.", "example": "zc_live_ExampleKeyShownOnceInThisReply0Zp", "pattern": "^zc_live_[0-9A-Za-z]{33}$" } } }, "SecondFactor": { "oneOf": [ { "type": "object", "description": "A code from the authenticator app.", "required": [ "code", "method" ], "properties": { "code": { "type": "string", "pattern": "^[0-9]{6}$" }, "method": { "type": "string", "enum": [ "totp" ] } } }, { "type": "object", "description": "One of the recovery codes: dashes and capitals do not matter. It is\nused up.", "required": [ "code", "method" ], "properties": { "code": { "type": "string", "maxLength": 64, "minLength": 1 }, "method": { "type": "string", "enum": [ "recoveryCode" ] } } }, { "type": "object", "description": "A passkey's answer to `POST /v1/session/second-factor/passkey-options`:\nthe `AuthenticationResponseJSON` of WebAuthn Level 3.", "required": [ "credential", "method" ], "properties": { "credential": { "type": "object" }, "method": { "type": "string", "enum": [ "passkey" ] } } } ], "description": "The second factor that finishes a log-in." }, "SecondFactorMethod": { "type": "string", "description": "A way to finish a log-in.", "enum": [ "totp", "recoveryCode", "passkey" ] }, "SecondFactorRequired": { "type": "object", "description": "A correct password, and two-factor on: what finishes the log-in.", "required": [ "methods", "expiresAt" ], "properties": { "expiresAt": { "type": "string", "format": "date-time", "description": "When the pending log-in ends, and the password must be sent again." }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/SecondFactorMethod" }, "description": "The methods this account can finish with: the app's code, a recovery\ncode while any are left, a passkey when it has one." } } }, "SessionList": { "type": "object", "description": "The signed-in person's live sessions.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummary" }, "description": "This session first, then the most recently active." } } }, "SessionSummary": { "type": "object", "description": "One of the signed-in person's sessions.", "required": [ "id", "client", "createdAt", "lastActiveAt", "current" ], "properties": { "client": { "type": "string", "description": "The browser it was opened in, such as \"Chrome on Windows\"." }, "createdAt": { "type": "string", "format": "date-time" }, "current": { "type": "boolean", "description": "The session making this request: \"this device\"." }, "id": { "type": "string", "format": "uuid" }, "ip": { "type": [ "string", "null" ], "description": "The client's address when it was opened; null if unknown." }, "lastActiveAt": { "type": "string", "format": "date-time", "description": "Its last request, to within five minutes." } } }, "SessionView": { "type": "object", "description": "The signed-in person and their account.", "required": [ "user", "account", "csrfToken", "expiresAt", "authenticatedAt", "recentAuthUntil" ], "properties": { "account": { "$ref": "#/components/schemas/AccountView" }, "authenticatedAt": { "type": "string", "format": "date-time", "description": "When its holder last proved the password: signing in, or\nre-authenticating since." }, "csrfToken": { "type": "string", "description": "Send it back as `X-CSRF-Token` on every change made with this session." }, "emailVerification": { "oneOf": [ { "$ref": "#/components/schemas/EmailVerification", "description": "The verification still needed: the address its link went to, and\nwhen another email may be asked for. Null once the address is verified\nand no change of address is pending." }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the session ends at the latest, whatever the activity." }, "recentAuthUntil": { "type": "string", "format": "date-time", "description": "Until when changes that need a recent sign-in go through without\nasking again. After it they answer `reauthentication_required`, until\nthe holder re-authenticates." }, "user": { "$ref": "#/components/schemas/UserView" } } }, "SignUp": { "type": "object", "description": "A new account.", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 320 }, "password": { "type": "string", "format": "password", "description": "At least 8 characters; not the email address; not a common password.", "maxLength": 1024, "minLength": 8 } }, "additionalProperties": false }, "Solution": { "type": "object", "description": "What a solved task yields.", "required": [ "token" ], "properties": { "cookie": { "oneOf": [ { "$ref": "#/components/schemas/ClearanceCookie", "description": "A challenge page's only: the cookie to send to the site. `null` for a\nTurnstile token." }, { "type": "null" } ] }, "token": { "type": "string", "description": "The Turnstile token, valid once, until tokenExpiresAt; for a\nchallenge page, the value of its `cf_clearance` cookie, as in\n`cookie`." }, "userAgent": { "type": [ "string", "null" ], "description": "A challenge page's only: the `User-Agent` its clearance was earned\nwith. Cloudflare accepts the cookie only with this user agent, from\nthe address of the proxy that earned it, and from a client whose TLS\nlooks like the browser this names. `null` for a Turnstile token." } } }, "SpendCap": { "type": "object", "description": "A key's daily spend cap.", "required": [ "keyId", "spentToday", "resetsAt" ], "properties": { "dailyCap": { "oneOf": [ { "$ref": "#/components/schemas/Usd", "description": "The most the key may spend in one UTC day; null when it has no cap,\nas keys have none until one is set." }, { "type": "null" } ] }, "keyId": { "type": "string", "format": "uuid" }, "resetsAt": { "type": "string", "format": "date-time", "description": "When the day ends and the count starts again: midnight UTC." }, "spentToday": { "$ref": "#/components/schemas/Usd", "description": "Held for and charged to the key's tasks created this UTC day." } } }, "StartTotp": { "type": "object", "description": "Starting an authenticator app: proof that it is the user, which a\nsecond factor must give once one is on.", "required": [ "proof" ], "properties": { "proof": { "$ref": "#/components/schemas/Proof" } }, "additionalProperties": false }, "Status": { "type": "string", "description": "Where a task is in its life. Only these moves happen: queued to running,\nrunning back to queued for a retry, and running or queued to one of the\nthree final states.", "enum": [ "queued", "running", "succeeded", "failed", "expired" ] }, "StatusReport": { "type": "object", "description": "The platform's figures over the last 24 hours.", "required": [ "generatedAt", "windowHours", "taskSuccessRate", "medianSolveSeconds", "apiAvailability" ], "properties": { "apiAvailability": { "type": [ "number", "null" ], "format": "double", "description": "The share of the window's whole minutes in which the API was serving,\nfrom 0 to 1, to four decimal places; since it first started when that\nwas less than 24 hours ago. `null` before its first whole minute.", "maximum": 1, "minimum": 0 }, "generatedAt": { "type": "string", "format": "date-time", "description": "When the figures were read." }, "medianSolveSeconds": { "type": [ "number", "null" ], "format": "double", "description": "The median time from creating a task to its token, over the tasks\nthat succeeded in the window, in seconds to one decimal place. `null`\nwhen fewer than 20 succeeded.", "minimum": 0 }, "taskSuccessRate": { "type": [ "number", "null" ], "format": "double", "description": "The share of tasks that finished in the window and succeeded, from 0\nto 1, to four decimal places. `null` when fewer than 20 finished.", "maximum": 1, "minimum": 0 }, "windowHours": { "type": "integer", "format": "int32", "description": "The hours every figure covers: always 24.", "example": 24, "minimum": 0 } }, "example": { "apiAvailability": 0.9993, "generatedAt": "2026-10-01T12:00:00Z", "medianSolveSeconds": 3.1, "taskSuccessRate": 0.9612, "windowHours": 24 } }, "SupportReceipt": { "type": "object", "description": "A message, received: staff answer it by email.", "required": [ "id", "replyTo", "receivedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "receivedAt": { "type": "string", "format": "date-time" }, "replyTo": { "type": "string", "format": "email", "description": "Where the answer will go." } } }, "SupportTopic": { "type": "string", "description": "What a message to support is about.", "enum": [ "question", "appeal" ] }, "TaskCallback": { "type": "object", "description": "A task's callback: where it goes, where it stands, and each attempt.", "required": [ "url", "status", "maxAttempts", "attempts" ], "properties": { "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/CallbackAttempt" }, "description": "Each attempt, oldest first." }, "maxAttempts": { "type": "integer", "format": "int32", "description": "Attempts it may make in all: eight, and eight more with each re-send." }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next attempt is due, while it is pending." }, "resentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was last sent again, if ever." }, "status": { "$ref": "#/components/schemas/CallbackStatus" }, "url": { "type": "string", "description": "The URL the task named." } } }, "TaskMode": { "type": "string", "description": "Whether the solver uses its own network or the customer's proxy.", "enum": [ "proxyless", "proxy" ] }, "TaskPage": { "type": "object", "description": "One page of tasks, newest first.", "required": [ "data", "liveCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskView" }, "description": "Tasks without their tokens; read one task to get its token." }, "liveCursor": { "type": "string", "description": "Pass as `since` to the live updates, so none are missed after this\npage was read." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; absent on the last page." } } }, "TaskPrice": { "type": "object", "description": "What one task type costs now, and the change scheduled next.", "required": [ "type", "mode", "current", "next" ], "properties": { "current": { "oneOf": [ { "$ref": "#/components/schemas/PricePoint", "description": "What a task created now is charged if it succeeds. `null` while no\nprice is in effect, when tasks of this type are refused." }, { "type": "null" } ] }, "mode": { "$ref": "#/components/schemas/TaskMode" }, "next": { "oneOf": [ { "$ref": "#/components/schemas/PricePoint", "description": "The next change already scheduled, if there is one." }, { "type": "null" } ] }, "type": { "type": "string", "description": "The task type as `POST /v1/tasks` takes it: `TurnstileTaskProxyless`, `TurnstileTask` to solve a widget through your proxy, or `CloudflareChallengeTask` to pass a challenge page through your proxy.", "enum": [ "TurnstileTaskProxyless", "TurnstileTask", "CloudflareChallengeTask" ], "examples": [ "TurnstileTaskProxyless" ] } } }, "TaskReport": { "type": "object", "description": "A report, recorded.", "required": [ "taskId", "verdict", "reportedAt" ], "properties": { "reportedAt": { "type": "string", "format": "date-time" }, "taskId": { "type": "string", "format": "uuid" }, "verdict": { "$ref": "#/components/schemas/Verdict" } } }, "TaskType": { "type": "string", "description": "What kind of challenge a task solves.", "enum": [ "turnstile", "cloudflare" ] }, "TaskView": { "type": "object", "description": "A task, as the REST API shows it.", "required": [ "id", "type", "kind", "status", "websiteURL", "usesProxy", "price", "held", "cost", "attempts", "maxAttempts", "tokenState", "createdAt", "deadline", "updatedAt", "version" ], "properties": { "action": { "type": [ "string", "null" ] }, "attempts": { "type": "integer", "format": "int32", "description": "Solve attempts made so far, each one a solver node took on and\nfinished. Waiting for a node with room, however long, is none." }, "callback": { "oneOf": [ { "$ref": "#/components/schemas/TaskCallback", "description": "The callback the task named, where it stands and each delivery\nattempt; null when it named none. Filled on `GET /v1/tasks/{id}`\nonly: null in lists, live events and callback payloads." }, { "type": "null" } ] }, "cdata": { "type": [ "string", "null" ] }, "cost": { "$ref": "#/components/schemas/Usd", "description": "What the task has cost: its price once it succeeds, otherwise zero." }, "createdAt": { "type": "string", "format": "date-time" }, "deadline": { "type": "string", "format": "date-time", "description": "Unsolved by this time, the task expires and nothing is charged." }, "errorCode": { "type": [ "string", "null" ] }, "errorDescription": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "held": { "$ref": "#/components/schemas/Usd", "description": "Held on the balance while the task is queued or running." }, "id": { "type": "string", "format": "uuid" }, "idempotencyKey": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/TaskType", "description": "What it solves, whichever name it was sent with: `turnstile`, a\nwidget's token, or `cloudflare`, a challenge page's clearance." }, "maxAttempts": { "type": "integer", "format": "int32", "description": "The most solve attempts the task gets." }, "price": { "$ref": "#/components/schemas/Usd", "description": "What the task is charged if it succeeds." }, "solution": { "oneOf": [ { "$ref": "#/components/schemas/Solution", "description": "Present while the token is available, and only on single-task reads." }, { "type": "null" } ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "$ref": "#/components/schemas/Status" }, "tokenExpiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "tokenIssuedAt": { "type": [ "string", "null" ], "format": "date-time" }, "tokenState": { "$ref": "#/components/schemas/TokenState" }, "type": { "type": "string", "description": "The task type as it was sent, such as `TurnstileTaskProxyless`." }, "updatedAt": { "type": "string", "format": "date-time" }, "usesProxy": { "type": "boolean", "description": "Whether the task runs through the customer's proxy." }, "version": { "type": "integer", "format": "int32", "description": "Raised on every change; a newer version replaces an older one." }, "websiteKey": { "type": [ "string", "null" ], "description": "The widget's site key; `null` for a challenge page." }, "websiteURL": { "type": "string" } } }, "Team": { "type": "object", "description": "The account's team.", "required": [ "members", "invites" ], "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/TeamInvite" }, "description": "Open invitations whose links still work, newest first." }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" }, "description": "Owners first, then members, each by when they joined." } } }, "TeamAction": { "type": "string", "description": "What changed on a team.", "enum": [ "team.invite", "team.invite_revoke", "team.join", "team.role_change", "team.remove", "team.leave", "callbacks.secret_rotate" ] }, "TeamActivity": { "type": "object", "description": "The team's latest changes, newest first.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamEvent" }, "description": "The latest 100." } } }, "TeamEvent": { "type": "object", "description": "One change to the team.", "required": [ "id", "at", "actorEmail", "action" ], "properties": { "action": { "$ref": "#/components/schemas/TeamAction" }, "actorEmail": { "type": "string", "format": "email", "description": "Who did it, by the address they had then." }, "at": { "type": "string", "format": "date-time" }, "id": { "type": "integer", "format": "int64" }, "roleAfter": { "oneOf": [ { "$ref": "#/components/schemas/Role" }, { "type": "null" } ] }, "roleBefore": { "oneOf": [ { "$ref": "#/components/schemas/Role" }, { "type": "null" } ] }, "subject": { "type": [ "string", "null" ], "description": "The address it was about, if any." } } }, "TeamInvite": { "type": "object", "description": "An invitation not yet accepted.", "required": [ "id", "email", "role", "invitedAt", "expiresAt" ], "properties": { "email": { "type": "string", "format": "email" }, "expiresAt": { "type": "string", "format": "date-time", "description": "After this, the link no longer works." }, "id": { "type": "string", "format": "uuid" }, "invitedAt": { "type": "string", "format": "date-time" }, "role": { "$ref": "#/components/schemas/Role" } } }, "TeamMember": { "type": "object", "description": "Someone on the team.", "required": [ "id", "email", "role", "joinedAt", "you" ], "properties": { "email": { "type": "string", "format": "email" }, "id": { "type": "string", "format": "uuid" }, "joinedAt": { "type": "string", "format": "date-time", "description": "When they joined: signed up, or accepted their invitation." }, "lastSignInAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When they last signed in; null if they never have since joining." }, "role": { "$ref": "#/components/schemas/Role" }, "you": { "type": "boolean", "description": "Whether this is the person asking." } } }, "TokenState": { "type": "string", "description": "Whether a task's token can still be used.", "enum": [ "pending", "available", "expired", "deleted", "none" ] }, "TopUp": { "type": "object", "description": "A top-up.", "required": [ "id", "amount", "credited", "status", "checkoutUrl", "createdAt" ], "properties": { "amount": { "$ref": "#/components/schemas/Usd", "description": "The invoice's amount." }, "checkoutUrl": { "type": "string", "description": "The processor's checkout page, where the invoice is paid." }, "createdAt": { "type": "string", "format": "date-time" }, "credited": { "$ref": "#/components/schemas/Usd", "description": "What its payments credited to the balance so far." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the invoice stops taking payment, if the processor says; its\ncheckout page shows it either way." }, "id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/TopUpStatus" } } }, "TopUpDetail": { "allOf": [ { "$ref": "#/components/schemas/TopUp" }, { "type": "object", "required": [ "credits" ], "properties": { "credits": { "type": "array", "items": { "$ref": "#/components/schemas/Credit" } } } } ], "description": "A top-up with each credit it made." }, "TopUpPage": { "type": "object", "description": "One page of top-ups, newest first.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TopUp" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; absent on the last page." } } }, "TopUpStatus": { "type": "string", "description": "Where a top-up stands.", "enum": [ "pending", "paid", "expired", "underpaid", "overpaid" ] }, "TotpEnabled": { "type": "object", "description": "Two-factor is on: the recovery codes, shown this once.", "required": [ "enabledAt", "recoveryCodes" ], "properties": { "enabledAt": { "type": "string", "format": "date-time" }, "recoveryCodes": { "type": "array", "items": { "type": "string" }, "description": "Ten codes, each good for one log-in without the app. Only their\ndigests are kept: this is the only time they are shown.", "example": [ "7kq2-x9mf-c4tn", "2wpa-h8rz-v3ld" ] } } }, "TotpEnrollment": { "type": "object", "description": "A new authenticator app's secret, shown this once.", "required": [ "secret", "uri", "digits", "period", "expiresAt" ], "properties": { "digits": { "type": "integer", "format": "int32", "description": "The code's settings, for an app that asks: SHA-1, 6 digits, 30\nseconds.", "minimum": 0 }, "expiresAt": { "type": "string", "format": "date-time", "description": "Until when a code from the app can confirm it." }, "period": { "type": "integer", "format": "int32", "minimum": 0 }, "secret": { "type": "string", "description": "The key to type into the app: base32, in groups of four.", "example": "JBSW Y3DP EHPK 3PXP JBSW Y3DP EHPK 3PXP" }, "uri": { "type": "string", "format": "uri", "description": "The `otpauth://totp/` URI the dashboard draws as a QR code." } } }, "TotpStatus": { "type": "object", "description": "The authenticator app.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "enabledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was turned on: \"On since 4 Sep\"." } } }, "TwoCaptchaReply": { "type": "object", "description": "A reply with `json=1`.", "required": [ "status", "request" ], "properties": { "error_text": { "type": "string", "description": "On a failure, what it means and what to do." }, "price": { "type": "string", "description": "With `action=get2`: what the task cost, in US dollars." }, "request": { "type": "string", "description": "On success the task's ID, its token or the balance; otherwise the\ncode, such as `CAPCHA_NOT_READY` or `ERROR_ZERO_BALANCE`." }, "status": { "type": "integer", "format": "int32", "description": "1 on success, 0 on failure and while the task is not ready.", "maximum": 1, "minimum": 0 } } }, "TwoCaptchaSubmit": { "type": "object", "description": "in.php's parameters for a Turnstile task, as 2Captcha documents them.", "required": [ "key", "method", "sitekey", "pageurl" ], "properties": { "action": { "type": [ "string", "null" ], "description": "The widget's action, if it sets one." }, "data": { "type": [ "string", "null" ], "description": "The widget's cData, if it sets one." }, "header_acao": { "type": [ "integer", "null" ], "format": "int32", "description": "Accepted and ignored: this service sends no CORS headers.", "minimum": 0 }, "json": { "type": [ "integer", "null" ], "format": "int32", "description": "`1` for JSON replies; `0`, the default, for plain text.", "minimum": 0 }, "key": { "type": "string", "description": "Your API key, `zc_live_…`. A missing or malformed one is\n`ERROR_WRONG_USER_KEY`, an unknown or revoked one\n`ERROR_KEY_DOES_NOT_EXIST`." }, "method": { "type": "string", "description": "`turnstile`; any other method is `ERROR_BAD_PARAMETERS`.", "example": "turnstile" }, "pagedata": { "type": [ "string", "null" ], "description": "Accepted and ignored: Cloudflare challenge pages are not supported." }, "pageurl": { "type": "string", "description": "The page the widget is on: a public http or https page, as\n`websiteURL` is on REST. Missing or invalid, `ERROR_PAGEURL`." }, "pingback": { "type": [ "string", "null" ], "description": "Where to POST the result once the task ends: 2Captcha's pingback\nform, `id` and `code`, signed with your callback secret. Any public\nURL, with no registration." }, "proxy": { "type": [ "string", "null" ], "description": "Your proxy as `login:password@host:port` or `host:port`; the task then\nruns through it." }, "proxytype": { "type": [ "string", "null" ], "description": "`HTTP`, the default, or `HTTPS`. SOCKS is not supported yet\n(`ERROR_PROXY_FORMAT`)." }, "sitekey": { "type": "string", "description": "The widget's site key." }, "soft_id": { "type": [ "string", "null" ], "description": "Accepted and ignored." }, "userAgent": { "type": [ "string", "null" ], "description": "Accepted and ignored." } } }, "TwoFactorOverview": { "type": "object", "description": "How the signed-in person signs in, for Settings.", "required": [ "enabled", "password", "totp", "recoveryCodesLeft", "recoveryCodesTotal", "passkeys" ], "properties": { "enabled": { "type": "boolean", "description": "Whether log-in asks for a second factor: an authenticator app or a\npasskey is set up. Optional, and suggested." }, "passkeys": { "type": "integer", "format": "int32", "description": "Passkeys registered.", "minimum": 0 }, "password": { "type": "boolean", "description": "Whether the account has a password; one signed up with a passkey has\nnone until a reset link sets one." }, "recoveryCodesLeft": { "type": "integer", "format": "int32", "description": "Recovery codes not used yet: \"8 of 10 left\". 0 when none were made.", "minimum": 0 }, "recoveryCodesTotal": { "type": "integer", "format": "int32", "description": "Codes in a new set.", "minimum": 0 }, "totp": { "$ref": "#/components/schemas/TotpStatus" } } }, "UpdateKey": { "type": "object", "description": "A change to a working key: its name, where it works from, or both.", "properties": { "allowedIps": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Its new allowlist, which replaces the old one: up to 100 IP addresses\nor CIDR networks. `null` or empty: any address. Absent: unchanged.", "maxItems": 100 }, "name": { "type": "string", "description": "Its new name, 1 to 100 characters. Surrounding whitespace is trimmed.", "maxLength": 100, "minLength": 1 } }, "additionalProperties": false }, "Usage": { "type": "object", "description": "The account's usage, one entry per day from `from` to `to`, both\nincluded, days without a task too.", "required": [ "from", "to", "days" ], "properties": { "days": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDay" } }, "from": { "type": "string", "format": "date", "example": "2026-09-01" }, "to": { "type": "string", "format": "date", "example": "2026-09-30" } } }, "UsageDay": { "type": "object", "description": "One UTC day of an account's tasks.", "required": [ "day", "tasks", "solved", "failed", "spend" ], "properties": { "day": { "type": "string", "format": "date", "description": "The day, such as `2026-09-29`.", "example": "2026-09-29" }, "failed": { "type": "integer", "format": "int64", "description": "Of those, the ones that failed or expired, which cost nothing. The\nrest are still queued or running." }, "solved": { "type": "integer", "format": "int64", "description": "Of those, the ones that succeeded: the only ones charged." }, "spend": { "$ref": "#/components/schemas/Usd", "description": "What the solved ones cost." }, "tasks": { "type": "integer", "format": "int64", "description": "Tasks created that day." } } }, "UsageMonth": { "type": "object", "description": "One UTC month of an account's tasks.", "required": [ "month", "tasks", "solved", "failed", "spend" ], "properties": { "failed": { "type": "integer", "format": "int64", "description": "Of those, the ones that failed or expired, which cost nothing." }, "month": { "type": "string", "description": "The month, such as `2026-09`.", "example": "2026-09", "pattern": "^\\d{4}-\\d{2}$" }, "solved": { "type": "integer", "format": "int64", "description": "Of those, the ones that succeeded: the only ones charged." }, "spend": { "$ref": "#/components/schemas/Usd", "description": "What the solved ones cost." }, "tasks": { "type": "integer", "format": "int64", "description": "Tasks created that month." } } }, "UsageMonths": { "type": "object", "description": "The account's usage per month, oldest first: every month from the one\nthe account was made in to the current one, months without a task too.", "required": [ "months" ], "properties": { "months": { "type": "array", "items": { "$ref": "#/components/schemas/UsageMonth" } } } }, "Usd": { "type": "string", "description": "US dollars as an exact decimal string with six decimals.", "examples": [ "0.000800" ], "pattern": "^-?\\d+\\.\\d{6}$" }, "UserView": { "type": "object", "required": [ "id", "email", "passwordChangedAt", "role" ], "properties": { "email": { "type": "string", "description": "The address the account signs in with." }, "emailVerifiedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the address was verified; null until it is. Creating an API key\nand starting a top-up wait for it (`email_unverified`); while a change\nof address is pending, it stays the old address's." }, "id": { "type": "string", "format": "uuid" }, "passwordChangedAt": { "type": "string", "format": "date-time", "description": "When the password was last set." }, "pendingEmail": { "type": [ "string", "null" ], "description": "An address the person asked to move to, which the account uses once\nthe link sent there is opened; null when none is." }, "role": { "$ref": "#/components/schemas/Role", "description": "What they may do in the account: an owner also manages its keys,\nbilling and team." } } }, "Verdict": { "type": "string", "description": "What the customer says of a solved task's token.", "enum": [ "bad", "good" ] }, "VerificationSent": { "type": "object", "description": "A verification email on its way.", "required": [ "address", "resendAvailableAt" ], "properties": { "address": { "type": "string", "format": "email", "description": "Where its link goes." }, "resendAvailableAt": { "type": "string", "format": "date-time", "description": "When another may be asked for." } } }, "VerifiedEmail": { "type": "object", "description": "An address, now verified.", "required": [ "email", "verifiedAt" ], "properties": { "email": { "type": "string", "format": "email", "description": "The account's address, now proven." }, "verifiedAt": { "type": "string", "format": "date-time" } } }, "WebhookReply": { "type": "object", "required": [ "outcome" ], "properties": { "outcome": { "$ref": "#/components/schemas/Received" } } } }, "securitySchemes": { "api_key": { "type": "http", "scheme": "bearer", "bearerFormat": "zc_live_…", "description": "An API key sent as `Authorization: Bearer `: it starts with `zc_live_`, and every task it makes is real and charged. A key needs no CSRF token." }, "session": { "type": "apiKey", "in": "cookie", "name": "__Host-zc_session", "description": "The dashboard's session: an HttpOnly, Secure, SameSite cookie set at sign-in. A request that changes something (any method but GET, HEAD and OPTIONS) must also send the session's CSRF token, `csrfToken`, as `X-CSRF-Token`, and no `Sec-Fetch-Site` but `same-origin` or `none`; otherwise it is refused with `csrf_rejected`." } } }, "tags": [ { "name": "tasks", "description": "Create Turnstile tasks, read their results, and follow them live." }, { "name": "balance", "description": "The prepaid balance and what is held for tasks in progress." }, { "name": "keys", "description": "API keys, managed from a dashboard session in both environments at once: create, rename and restrict them, rotate them with an overlap, and revoke them. A key is shown whole only in the reply that makes it." }, { "name": "prices", "description": "What each task type costs now and the next change scheduled: public, with no key or session, and cacheable." }, { "name": "status", "description": "The platform's last 24 hours: task success rate, median solve time and API availability. Public, with no key or session, and cacheable." }, { "name": "opt-out", "description": "Site owners asking for their domain to be excluded: public, with no key or session. Staff check and decide each request by hand." }, { "name": "usage", "description": "The account's tasks per day: created, solved and failed, and what the solved ones cost." }, { "name": "support", "description": "Messages to support: from the dashboard with a session, or from the public contact form with none. Staff answer by email." }, { "name": "abuse", "description": "Reporting a site ZeroCaptcha was used against: public, with no key or session. Staff look into each report and act by hand." }, { "name": "inbound", "description": "Where the Cloudflare Email Worker posts the email that reaches the role addresses (support@, billing@ and the rest), signed with a secret it shares with the API, for the staff inbox. Not for customers." }, { "name": "demo", "description": "The public demo and CAPTCHA test pages: checking a token from one of their Cloudflare Turnstile widgets with Cloudflare's siteverify, and whether a request carried a Cloudflare clearance. Public, with no key or session; nothing here solves anything." }, { "name": "billing", "description": "Adding funds: top-ups paid through the payment processor and credited at its rate, receipts, optional billing details, and the low-balance email. Top-ups are final." }, { "name": "compatible", "description": "The createTask format other providers use, so existing clients work unchanged. Its errors come in its errorId shape, with HTTP 200; only a failure outside the endpoint, such as a body over the size limit, is a problem document." }, { "name": "2captcha", "description": "2Captcha's in.php and res.php for Turnstile, so a 2Captcha client works after changing only its base URL and key. Priced and charged as the other dialects are. Every reply is HTTP 200, as plain text or, with `json=1`, JSON; only a failure outside the endpoint is a problem document." }, { "name": "callbacks", "description": "The secret task callbacks are signed with. A task that names `callbackUrl` (or `pingback`) is POSTed to it once it ends, with `ZeroCaptcha-Signature: t=,v1=`, the HMAC-SHA256 of `.` under this secret." }, { "name": "team", "description": "Teams: an account's owners and members, invitations by email, roles, and the account's activity log. Members use the keys and see the tasks; owners also manage the keys, the billing and the team." }, { "name": "session", "description": "Dashboard sign-in: log in, the current session, re-authentication, the session list, log out." }, { "name": "account", "description": "Self-serve accounts: sign-up, email verification, changing the address or the password, password reset, and the account policy the screens show." }, { "name": "health", "description": "Liveness and readiness probes for load balancers and orchestrators." }, { "name": "meta", "description": "Documents about the API itself, such as this contract." } ] }