diff --git a/CHANGELOG.md b/CHANGELOG.md index 3fe9069..854c6fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## 0.5.0 (2026-11-12) + +Follows API 1.18.0. The saved spec has 145 operations and the models are regenerated from it. +No client method, argument or return type changed. An API key is sent as before. + +Breaking: the models `HTTPValidationError` and `ValidationError` are removed from `faxforagents.models`. +The server never sent that shape. A 422 is the error envelope and the client raises `InvalidRequestError`, as it did in 0.4.1. +Code that imported either model has to delete the import. Nothing replaces them. pydantic's own `ValidationError` is not affected. + +Breaking: `ErrorEnvelope.error` is the new model `ErrorBody`, where 0.4.1 declared a plain dict. Read `env.error.code`, not `env.error["code"]`. +`ErrorBody` has `code`, `message`, `retryable`, `correlation_id` and `details`. `correlation_id` may be `None`. +Raised errors are the same classes with the same attributes. + +`one_time_sends.create` can raise `RateLimitedError` with `details["cap"]` equal to `upload_queue`. Too many files are being read at once, so wait `retry_after` seconds. +Other model names, fields and optionality are kept. + ## 0.4.1 (2026-11-12) Follows API 1.17.0. The saved spec has 145 operations and the models are regenerated from it. diff --git a/README.md b/README.md index 786e3bf..ae3b4e4 100644 --- a/README.md +++ b/README.md @@ -152,6 +152,10 @@ except APIError as exc: `ServerError` (5xx) are all `APIError`. `APIConnectionError` and `APITimeoutError` mean the API was not reached. +Every refusal is the same envelope, a 422 for a field that fails validation included. A 413 +`payload_too_large` is a plain `APIError`: the body is over the limit of its route. The published +limits are in one table at . + ## Approvals A live send needs either a human approval bound to the quote or a delegated policy that allows it. @@ -295,7 +299,7 @@ ruff check src tests && mypy src sh scripts/truthcheck.sh ``` -`spec/openapi.yaml` follows the public document at API version 1.17.0 and keeps the schemas of the earlier live documents. +`spec/openapi.yaml` follows the public document at API version 1.18.0 and keeps the schemas of the earlier live documents. It also retains earlier public model names and route-documented response additions. To refresh it, merge the live schemas while preserving existing declarations, then run `uv run python scripts/gen_models.py`. Keep new response fields optional so older payloads and existing callers remain valid. diff --git a/pyproject.toml b/pyproject.toml index d8c1d77..76f72ec 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "faxforagents" -version = "0.4.1" +version = "0.5.0" description = "Python client for Fax for Agents: a fax API, a hosted MCP server and SDKs built so AI agents can send and receive faxes." readme = "README.md" requires-python = ">=3.10" diff --git a/spec/openapi.yaml b/spec/openapi.yaml index 6afc166..d61f8b9 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -1,4 +1,4 @@ -# Fax for Agents API, refreshed from the public document of https://github.com/faxforagents/openapi at API 1.17.0. +# Fax for Agents API, refreshed from the public document of https://github.com/faxforagents/openapi at API 1.18.0. # All earlier schemas are kept. Existing SDK routes, model names and serializer additions are retained. openapi: 3.1.0 info: @@ -26,7 +26,7 @@ info: x-logo: url: https://faxforagents.com/brand/logo-512.png altText: Fax for Agents - version: 1.17.0 + version: 1.18.0 servers: - url: https://api.faxforagents.com description: Production (live and test keys) @@ -87,23 +87,18 @@ paths: schema: $ref: '#/components/schemas/Me' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] x-llm: scope: any mutating: false @@ -123,29 +118,21 @@ paths: schema: $ref: '#/components/schemas/ApiKeyList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope key:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: key:admin x-llm: scope: key:admin mutating: false @@ -169,36 +156,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiKeyWithSecret' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope key:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -209,6 +182,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: key:admin x-llm: scope: key:admin mutating: true @@ -245,36 +222,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiKeyWithSecret' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope key:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: key:admin x-llm: scope: key:admin mutating: true @@ -309,36 +272,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Deleted' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope key:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: key:admin x-llm: scope: key:admin mutating: true @@ -363,36 +312,24 @@ paths: application/json: schema: $ref: '#/components/schemas/UploadSession' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '413': + $ref: '#/components/responses/PayloadTooLarge' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -403,6 +340,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:write x-llm: scope: document:write mutating: true @@ -455,24 +396,23 @@ paths: application/json: schema: $ref: '#/components/schemas/UploadSession' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '404': - description: No such resource, or the signed link expired. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '413': + $ref: '#/components/responses/PayloadTooLarge' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' + security: + - signedUrl: [] x-llm: scope: signed-url mutating: true idempotency_key: false agent_key_allowed: true - security: [] description: 'No API key: the `exp` and `sig` query values come from the signed URL the API minted. The link lives ten minutes.' /v1/uploads/{upload_id}/complete: @@ -510,36 +450,22 @@ paths: application/json: schema: $ref: '#/components/schemas/UploadSession' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:write x-llm: scope: document:write mutating: true @@ -574,36 +500,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Deleted' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:write x-llm: scope: document:write mutating: true @@ -628,36 +540,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Document' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '413': + $ref: '#/components/responses/PayloadTooLarge' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' parameters: - name: Idempotency-Key in: header @@ -668,6 +566,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:write x-llm: scope: document:write mutating: true @@ -705,36 +607,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DocumentPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:read x-llm: scope: document:read mutating: false @@ -760,36 +650,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Document' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:read x-llm: scope: document:read mutating: false @@ -823,36 +697,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Deleted' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:write x-llm: scope: document:write mutating: true @@ -878,36 +738,20 @@ paths: application/json: schema: $ref: '#/components/schemas/DocumentValidation' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:read x-llm: scope: document:read mutating: false @@ -933,36 +777,20 @@ paths: application/json: schema: $ref: '#/components/schemas/SignedUrl' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:read x-llm: scope: document:read mutating: false @@ -1000,24 +828,17 @@ paths: responses: '200': description: Successful Response - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '404': - description: No such resource, or the signed link expired. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' + security: + - signedUrl: [] x-llm: scope: signed-url mutating: false idempotency_key: false agent_key_allowed: true - security: [] description: 'No API key: the `exp` and `sig` query values come from the signed URL the API minted. The link lives ten minutes.' /v1/documents/{document_id}/pages: @@ -1040,36 +861,20 @@ paths: application/json: schema: $ref: '#/components/schemas/DocumentPages' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:read x-llm: scope: document:read mutating: false @@ -1113,24 +918,17 @@ paths: responses: '200': description: Successful Response - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '404': - description: No such resource, or the signed link expired. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' + security: + - signedUrl: [] x-llm: scope: signed-url mutating: false idempotency_key: false agent_key_allowed: true - security: [] description: 'No API key: the `exp` and `sig` query values come from the signed URL the API minted. The link lives ten minutes.' /v1/fax-quotes: @@ -1152,36 +950,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Quote' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:quote (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' '503': description: 'Live keys only: this server has no carrier configured, so live quotes, sends and number operations are refused (live_provider_unavailable, retryable false). Nothing was held or consumed. Test @@ -1200,6 +980,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:quote x-llm: scope: fax:quote mutating: true @@ -1226,36 +1010,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Quote' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:quote (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:quote x-llm: scope: fax:quote mutating: false @@ -1280,12 +1048,8 @@ paths: application/json: schema: $ref: '#/components/schemas/FaxJob' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' + '401': + $ref: '#/components/responses/Unauthorized' '402': description: The wallet does not cover this fax (insufficient_balance). details names available_micro and needed_micro, top_up_url where a person adds funds, and one_time_offer when the send can be paid @@ -1300,6 +1064,8 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + '404': + $ref: '#/components/responses/NotFound' '409': description: 'The quote expired (quote_expired), already created a fax (quote_consumed), belongs to a one-time order (quote_pricing_mismatch), or the document changed since the quote (document_hash_mismatch). @@ -1308,24 +1074,10 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' '503': description: 'Live keys only: this server has no carrier configured, so live quotes, sends and number operations are refused (live_provider_unavailable, retryable false). Nothing was held or consumed. Test @@ -1344,6 +1096,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:send x-llm: scope: fax:send mutating: true @@ -1403,36 +1159,24 @@ paths: application/json: schema: $ref: '#/components/schemas/FaxJobPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:read x-llm: scope: fax:read mutating: false @@ -1458,38 +1202,22 @@ paths: application/json: schema: $ref: '#/components/schemas/FaxJob' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - x-llm: - scope: fax:read + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:read + x-llm: + scope: fax:read mutating: false idempotency_key: false agent_key_allowed: true @@ -1514,36 +1242,20 @@ paths: application/json: schema: $ref: '#/components/schemas/EventPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:read x-llm: scope: fax:read mutating: false @@ -1569,36 +1281,20 @@ paths: application/json: schema: $ref: '#/components/schemas/AttemptPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:read x-llm: scope: fax:read mutating: false @@ -1624,36 +1320,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Receipt' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:read x-llm: scope: fax:read mutating: false @@ -1677,36 +1359,22 @@ paths: description: The receipt as a PDF content: application/pdf: {} - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:read x-llm: scope: fax:read mutating: false @@ -1741,36 +1409,18 @@ paths: application/json: schema: $ref: '#/components/schemas/FaxJob' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:cancel (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' '503': description: 'Live keys only: this server has no carrier configured, so live quotes, sends and number operations are refused (live_provider_unavailable, retryable false). Nothing was held or consumed. Test @@ -1779,6 +1429,10 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:cancel x-llm: scope: fax:cancel mutating: true @@ -1799,29 +1453,21 @@ paths: schema: $ref: '#/components/schemas/WebhookList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope webhook:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: webhook:admin x-llm: scope: webhook:admin mutating: false @@ -1845,36 +1491,22 @@ paths: application/json: schema: $ref: '#/components/schemas/WebhookWithSecret' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope webhook:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -1885,6 +1517,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: webhook:admin x-llm: scope: webhook:admin mutating: true @@ -1925,36 +1561,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Webhook' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope webhook:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: webhook:admin x-llm: scope: webhook:admin mutating: true @@ -1988,36 +1610,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Deleted' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope webhook:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: webhook:admin x-llm: scope: webhook:admin mutating: true @@ -2052,36 +1660,22 @@ paths: application/json: schema: $ref: '#/components/schemas/WebhookWithSecret' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope webhook:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: webhook:admin x-llm: scope: webhook:admin mutating: true @@ -2116,36 +1710,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Event' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope webhook:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: webhook:admin x-llm: scope: webhook:admin mutating: true @@ -2198,36 +1778,24 @@ paths: application/json: schema: $ref: '#/components/schemas/DeliveryPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope webhook:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: webhook:admin x-llm: scope: webhook:admin mutating: false @@ -2262,36 +1830,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Delivery' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope webhook:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: webhook:admin x-llm: scope: webhook:admin mutating: true @@ -2338,36 +1892,24 @@ paths: application/json: schema: $ref: '#/components/schemas/EventPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:read x-llm: scope: fax:read mutating: false @@ -2387,29 +1929,21 @@ paths: schema: $ref: '#/components/schemas/Balance' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -2446,36 +1980,24 @@ paths: application/json: schema: $ref: '#/components/schemas/LedgerPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -2495,29 +2017,17 @@ paths: schema: $ref: '#/components/schemas/BillingSettings' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -2541,36 +2051,18 @@ paths: application/json: schema: $ref: '#/components/schemas/BillingSettings' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' parameters: - name: Idempotency-Key in: header @@ -2581,6 +2073,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:write x-llm: scope: billing:write mutating: true @@ -2605,36 +2101,22 @@ paths: application/json: schema: $ref: '#/components/schemas/TopupSession' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '402': + $ref: '#/components/responses/PaymentRequired' '403': - description: The key lacks the scope billing:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' parameters: - name: Idempotency-Key in: header @@ -2645,6 +2127,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:write x-llm: scope: billing:write mutating: true @@ -2680,36 +2166,24 @@ paths: application/json: schema: $ref: '#/components/schemas/TopupSessionPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -2735,36 +2209,20 @@ paths: application/json: schema: $ref: '#/components/schemas/TopupSession' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -2789,36 +2247,22 @@ paths: application/json: schema: $ref: '#/components/schemas/AutoTopup' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '402': + $ref: '#/components/responses/PaymentRequired' '403': - description: The key lacks the scope billing:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' parameters: - name: Idempotency-Key in: header @@ -2829,6 +2273,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:write x-llm: scope: billing:write mutating: true @@ -2847,29 +2295,21 @@ paths: schema: $ref: '#/components/schemas/AutoTopupList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -2904,36 +2344,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Deleted' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:write x-llm: scope: billing:write mutating: true @@ -2953,29 +2379,21 @@ paths: schema: $ref: '#/components/schemas/BudgetList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -2999,36 +2417,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Budget' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' parameters: - name: Idempotency-Key in: header @@ -3039,6 +2439,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:write x-llm: scope: billing:write mutating: true @@ -3079,36 +2483,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Budget' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:write x-llm: scope: billing:write mutating: true @@ -3161,36 +2551,24 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageReport' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -3215,36 +2593,22 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageExport' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -3255,6 +2619,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: true @@ -3280,36 +2648,20 @@ paths: application/json: schema: $ref: '#/components/schemas/UsageExport' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -3347,24 +2699,17 @@ paths: responses: '200': description: Successful Response - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '404': - description: No such resource, or the signed link expired. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' + security: + - signedUrl: [] x-llm: scope: signed-url mutating: false idempotency_key: false agent_key_allowed: true - security: [] description: 'No API key: the `exp` and `sig` query values come from the signed URL the API minted. The link lives ten minutes.' /v1/invoices: @@ -3398,36 +2743,22 @@ paths: application/json: schema: $ref: '#/components/schemas/InvoicePage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -3453,36 +2784,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Invoice' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -3502,29 +2819,21 @@ paths: schema: $ref: '#/components/schemas/SubscriptionCheckout' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '402': + $ref: '#/components/responses/PaymentRequired' '403': - description: The key lacks the scope billing:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' parameters: - name: Idempotency-Key in: header @@ -3535,6 +2844,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:write x-llm: scope: billing:write mutating: true @@ -3554,29 +2867,17 @@ paths: schema: $ref: '#/components/schemas/SubscriptionList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope billing:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:read x-llm: scope: billing:read mutating: false @@ -3596,29 +2897,21 @@ paths: schema: $ref: '#/components/schemas/PortalSession' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '402': + $ref: '#/components/responses/PaymentRequired' '403': - description: The key lacks the scope billing:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' parameters: - name: Idempotency-Key in: header @@ -3629,6 +2922,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: billing:write x-llm: scope: billing:write mutating: true @@ -3648,23 +2945,18 @@ paths: schema: $ref: '#/components/schemas/Capabilities' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] x-llm: scope: any mutating: false @@ -3684,23 +2976,18 @@ paths: schema: $ref: '#/components/schemas/ServiceStatus' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] x-llm: scope: any mutating: false @@ -3720,29 +3007,21 @@ paths: schema: $ref: '#/components/schemas/SandboxScenarios' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope sandbox:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: sandbox:write x-llm: scope: sandbox:write mutating: false @@ -3766,36 +3045,22 @@ paths: application/json: schema: $ref: '#/components/schemas/SandboxFixture' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope sandbox:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -3806,6 +3071,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: sandbox:write x-llm: scope: sandbox:write mutating: true @@ -3834,36 +3103,22 @@ paths: application/json: schema: $ref: '#/components/schemas/InboxItemSummary' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope sandbox:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -3874,6 +3129,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: sandbox:write x-llm: scope: sandbox:write mutating: true @@ -3893,29 +3152,21 @@ paths: schema: $ref: '#/components/schemas/SandboxReset' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope sandbox:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -3926,6 +3177,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: sandbox:write x-llm: scope: sandbox:write mutating: true @@ -3946,23 +3201,14 @@ paths: schema: $ref: '#/components/schemas/OrganizationList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] x-llm: scope: any mutating: false @@ -3982,29 +3228,17 @@ paths: schema: $ref: '#/components/schemas/Organization' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope account:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: account:read x-llm: scope: account:read mutating: false @@ -4028,36 +3262,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Organization' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope member:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' parameters: - name: Idempotency-Key in: header @@ -4068,6 +3284,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: member:admin x-llm: scope: member:admin mutating: true @@ -4087,25 +3307,17 @@ paths: schema: $ref: '#/components/schemas/Requested' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '403': - description: The key lacks the scope org:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' + '404': + description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: @@ -4120,6 +3332,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: org:admin x-llm: scope: org:admin mutating: true @@ -4139,29 +3355,21 @@ paths: schema: $ref: '#/components/schemas/Requested' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope org:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -4172,6 +3380,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: org:admin x-llm: scope: org:admin mutating: true @@ -4209,24 +3421,17 @@ paths: responses: '200': description: Successful Response - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '404': - description: No such resource, or the signed link expired. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' + security: + - signedUrl: [] x-llm: scope: signed-url mutating: false idempotency_key: false agent_key_allowed: true - security: [] description: 'No API key: the `exp` and `sig` query values come from the signed URL the API minted. The link lives 72 hours.' /v1/members: @@ -4243,29 +3448,21 @@ paths: schema: $ref: '#/components/schemas/MemberList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope account:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: account:read x-llm: scope: account:read mutating: false @@ -4306,36 +3503,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Member' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope member:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: member:admin x-llm: scope: member:admin mutating: true @@ -4365,36 +3548,22 @@ paths: responses: '204': description: Successful Response - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope org:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: org:admin x-llm: scope: org:admin mutating: true @@ -4414,29 +3583,21 @@ paths: schema: $ref: '#/components/schemas/InvitationList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope member:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: member:admin x-llm: scope: member:admin mutating: false @@ -4460,36 +3621,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Invitation' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope member:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -4500,6 +3647,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: member:admin x-llm: scope: member:admin mutating: true @@ -4530,36 +3681,22 @@ paths: responses: '204': description: Successful Response - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope member:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: member:admin x-llm: scope: member:admin mutating: true @@ -4584,36 +3721,18 @@ paths: application/json: schema: $ref: '#/components/schemas/ApprovalRequest' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope approval:request (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' parameters: - name: Idempotency-Key in: header @@ -4624,6 +3743,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: approval:request x-llm: scope: approval:request mutating: true @@ -4668,36 +3791,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ApprovalRequestPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope approval:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: approval:read x-llm: scope: approval:read mutating: false @@ -4723,38 +3834,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ApprovalRequest' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope approval:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - x-llm: - scope: approval:read + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: approval:read + x-llm: + scope: approval:read mutating: false idempotency_key: false agent_key_allowed: true @@ -4793,36 +3888,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ApprovalRequest' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope approval:decide (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: approval:decide x-llm: scope: approval:decide mutating: true @@ -4863,36 +3944,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ApprovalRequest' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope approval:decide (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: approval:decide x-llm: scope: approval:decide mutating: true @@ -4933,36 +4000,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ApprovalRequest' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope approval:decide (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: approval:decide x-llm: scope: approval:decide mutating: true @@ -4982,29 +4035,21 @@ paths: schema: $ref: '#/components/schemas/PolicyList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope policy:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: policy:read x-llm: scope: policy:read mutating: false @@ -5028,36 +4073,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Policy' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope policy:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -5068,6 +4099,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: policy:admin x-llm: scope: policy:admin mutating: true @@ -5125,36 +4160,20 @@ paths: application/json: schema: $ref: '#/components/schemas/EffectivePolicies' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope policy:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: policy:read x-llm: scope: policy:read mutating: false @@ -5175,29 +4194,21 @@ paths: schema: $ref: '#/components/schemas/AutoSendSetting' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope policy:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: policy:read x-llm: scope: policy:read mutating: false @@ -5227,36 +4238,22 @@ paths: application/json: schema: $ref: '#/components/schemas/AutoSendSetting' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope org:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -5267,6 +4264,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: org:admin x-llm: scope: org:admin mutating: true @@ -5293,36 +4294,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Policy' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope policy:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: policy:read x-llm: scope: policy:read mutating: false @@ -5362,36 +4347,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Policy' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope policy:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: policy:admin x-llm: scope: policy:admin mutating: true @@ -5417,36 +4388,20 @@ paths: application/json: schema: $ref: '#/components/schemas/PolicyVersionList' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope policy:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: policy:read x-llm: scope: policy:read mutating: false @@ -5471,36 +4426,18 @@ paths: application/json: schema: $ref: '#/components/schemas/PolicyEvaluation' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope policy:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' parameters: - name: Idempotency-Key in: header @@ -5511,6 +4448,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: policy:read x-llm: scope: policy:read mutating: true @@ -5531,29 +4472,21 @@ paths: schema: $ref: '#/components/schemas/AgentList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope agent:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: agent:read x-llm: scope: agent:read mutating: false @@ -5577,36 +4510,18 @@ paths: application/json: schema: $ref: '#/components/schemas/Agent' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope agent:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' parameters: - name: Idempotency-Key in: header @@ -5617,6 +4532,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: agent:admin x-llm: scope: agent:admin mutating: true @@ -5642,36 +4561,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Agent' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope agent:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: agent:read x-llm: scope: agent:read mutating: false @@ -5711,36 +4614,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Agent' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope agent:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: agent:admin x-llm: scope: agent:admin mutating: true @@ -5781,36 +4670,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ApiKeyWithSecret' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope agent:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: agent:admin x-llm: scope: agent:admin mutating: true @@ -5853,36 +4728,20 @@ paths: application/json: schema: $ref: '#/components/schemas/AgentActivityPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope agent:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: agent:read x-llm: scope: agent:read mutating: false @@ -5931,36 +4790,24 @@ paths: application/json: schema: $ref: '#/components/schemas/InboxPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope inbox:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: inbox:read x-llm: scope: inbox:read mutating: false @@ -5986,36 +4833,20 @@ paths: application/json: schema: $ref: '#/components/schemas/InboxItemDetail' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope inbox:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: inbox:read x-llm: scope: inbox:read mutating: false @@ -6057,36 +4888,22 @@ paths: application/json: schema: $ref: '#/components/schemas/InboxItem' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope inbox:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: inbox:write x-llm: scope: inbox:write mutating: true @@ -6120,36 +4937,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Deleted' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope inbox:write (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: inbox:write x-llm: scope: inbox:write mutating: true @@ -6175,36 +4978,22 @@ paths: application/json: schema: $ref: '#/components/schemas/SignedUrl' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope inbox:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: inbox:read x-llm: scope: inbox:read mutating: false @@ -6242,24 +5031,17 @@ paths: responses: '200': description: Successful Response - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '404': - description: No such resource, or the signed link expired. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' + security: + - signedUrl: [] x-llm: scope: signed-url mutating: false idempotency_key: false agent_key_allowed: true - security: [] description: 'No API key: the `exp` and `sig` query values come from the signed URL the API minted. The link lives ten minutes.' /v1/coverage: @@ -6276,29 +5058,21 @@ paths: schema: $ref: '#/components/schemas/Coverage' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:read x-llm: scope: number:read mutating: false @@ -6355,44 +5129,28 @@ paths: application/json: schema: $ref: '#/components/schemas/Inventory' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' '503': - description: 'Live keys only: this server has no carrier configured, so live quotes, sends and number - operations are refused (live_provider_unavailable, retryable false). Nothing was held or consumed. Test - keys keep working against the sandbox.' + $ref: '#/components/responses/ServiceUnavailable' + '404': + description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:read x-llm: scope: number:read mutating: false @@ -6421,36 +5179,20 @@ paths: application/json: schema: $ref: '#/components/schemas/NumberOrder' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '402': + $ref: '#/components/responses/PaymentRequired' '403': - description: The key lacks the scope number:buy (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' '503': description: 'Live keys only: this server has no carrier configured, so live quotes, sends and number operations are refused (live_provider_unavailable, retryable false). Nothing was held or consumed. Test @@ -6469,6 +5211,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:buy x-llm: scope: number:buy mutating: true @@ -6488,29 +5234,21 @@ paths: schema: $ref: '#/components/schemas/NumberOrderList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:read x-llm: scope: number:read mutating: false @@ -6536,36 +5274,20 @@ paths: application/json: schema: $ref: '#/components/schemas/NumberOrder' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:read x-llm: scope: number:read mutating: false @@ -6592,36 +5314,24 @@ paths: application/json: schema: $ref: '#/components/schemas/NumberList' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:read x-llm: scope: number:read mutating: false @@ -6647,36 +5357,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Number' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:read x-llm: scope: number:read mutating: false @@ -6716,36 +5410,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Number' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:buy (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:buy x-llm: scope: number:buy mutating: true @@ -6786,44 +5466,24 @@ paths: application/json: schema: $ref: '#/components/schemas/Number' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:buy (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' '503': - description: 'Live keys only: this server has no carrier configured, so live quotes, sends and number - operations are refused (live_provider_unavailable, retryable false). Nothing was held or consumed. Test - keys keep working against the sandbox.' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/ServiceUnavailable' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:buy x-llm: scope: number:buy mutating: true @@ -6848,40 +5508,20 @@ paths: application/json: schema: $ref: '#/components/schemas/PortabilityCheck' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' '503': - description: 'Live keys only: this server has no carrier configured, so live quotes, sends and number - operations are refused (live_provider_unavailable, retryable false). Nothing was held or consumed. Test - keys keep working against the sandbox.' + $ref: '#/components/responses/ServiceUnavailable' + '404': + description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: @@ -6896,6 +5536,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:read x-llm: scope: number:read mutating: true @@ -6920,44 +5564,20 @@ paths: application/json: schema: $ref: '#/components/schemas/PortOrder' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:buy (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' '503': - description: 'Live keys only: this server has no carrier configured, so live quotes, sends and number - operations are refused (live_provider_unavailable, retryable false). Nothing was held or consumed. Test - keys keep working against the sandbox.' - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/ServiceUnavailable' parameters: - name: Idempotency-Key in: header @@ -6968,6 +5588,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:buy x-llm: scope: number:buy mutating: true @@ -6986,29 +5610,21 @@ paths: schema: $ref: '#/components/schemas/PortOrderList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:read x-llm: scope: number:read mutating: false @@ -7034,36 +5650,20 @@ paths: application/json: schema: $ref: '#/components/schemas/PortOrder' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:read x-llm: scope: number:read mutating: false @@ -7088,36 +5688,20 @@ paths: application/json: schema: $ref: '#/components/schemas/PortOrder' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:buy (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' parameters: - name: Idempotency-Key in: header @@ -7128,6 +5712,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:buy x-llm: scope: number:buy mutating: true @@ -7152,36 +5740,22 @@ paths: application/json: schema: $ref: '#/components/schemas/SenderVerification' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope number:buy (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -7192,6 +5766,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: number:buy x-llm: scope: number:buy mutating: true @@ -7216,36 +5794,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Extraction' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '402': + $ref: '#/components/responses/PaymentRequired' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' parameters: - name: Idempotency-Key in: header @@ -7256,6 +5818,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: true @@ -7309,36 +5875,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ExtractionPageList' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: false @@ -7364,37 +5918,21 @@ paths: application/json: schema: $ref: '#/components/schemas/Extraction' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - x-llm: + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract + x-llm: scope: document:extract mutating: false idempotency_key: false @@ -7434,36 +5972,22 @@ paths: application/json: schema: $ref: '#/components/schemas/Correction' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: true @@ -7488,36 +6012,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Extraction' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '402': + $ref: '#/components/responses/PaymentRequired' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' parameters: - name: Idempotency-Key in: header @@ -7528,6 +6036,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: true @@ -7579,36 +6091,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ExtractionPageList' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: false @@ -7634,36 +6134,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Extraction' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: false @@ -7688,36 +6172,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Extraction' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' + '402': + $ref: '#/components/responses/PaymentRequired' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' parameters: - name: Idempotency-Key in: header @@ -7728,6 +6196,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: true @@ -7779,36 +6251,24 @@ paths: application/json: schema: $ref: '#/components/schemas/ExtractionPageList' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: false @@ -7834,36 +6294,20 @@ paths: application/json: schema: $ref: '#/components/schemas/Extraction' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: false @@ -7883,29 +6327,21 @@ paths: schema: $ref: '#/components/schemas/ExtractionSchemaList' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: false @@ -7929,36 +6365,22 @@ paths: application/json: schema: $ref: '#/components/schemas/ExtractionSchema' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' parameters: - name: Idempotency-Key in: header @@ -7969,6 +6391,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: true @@ -7994,36 +6420,20 @@ paths: application/json: schema: $ref: '#/components/schemas/ExtractionSchema' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope document:extract (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: document:extract x-llm: scope: document:extract mutating: false @@ -8043,18 +6453,14 @@ paths: schema: $ref: '#/components/schemas/OneTimeConfig' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: [] x-llm: scope: none mutating: false idempotency_key: false agent_key_allowed: true hint: Read enabled first. The routes and their prices are present only while the product is open here. - security: [] description: No API key is needed. /v1/one-time-sends: post: @@ -8072,12 +6478,18 @@ paths: application/json: schema: $ref: '#/components/schemas/OneTimeOrderCreated' + '401': + $ref: '#/components/responses/Unauthorized' '403': description: A key was sent and lacks fax:send (scope_missing), or the destination is blocked (blocked_destination). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + '404': + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' '422': description: 'The form was refused (invalid_request), the number is not a fax destination (invalid_destination), the route is not sold one fax at a time (unsupported_destination), or the document is too large (document_too_large). @@ -8086,19 +6498,16 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '503': - description: One-time sends are switched off on this server (one_time_unavailable). Nothing was created - or charged. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. + '429': + description: 'Rate limit reached (rate_limited). details.cap names the limit: email, destination or address + for a daily limit of the one-time send, upload_queue when too many files are being read at once. Retry + after the seconds in Retry-After.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + '503': + $ref: '#/components/responses/ServiceUnavailable' parameters: - name: Idempotency-Key in: header @@ -8275,6 +6684,11 @@ paths: - accept_aup - text type: object + security: + - {} + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:send x-llm: scope: fax:send mutating: true @@ -8283,10 +6697,6 @@ paths: hint: 'Charges nothing and sends nothing. Keep status_token: it is answered once. Next is the checkout, then a person pays on checkout_url and clicks the mailed confirmation link.' key_optional: true - security: - - {} - - bearerAuth: [] - - apiKeyHeader: [] get: tags: - one-time-sends @@ -8338,36 +6748,24 @@ paths: application/json: schema: $ref: '#/components/schemas/OneTimeOrderPage' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope fax:read (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' + '422': + $ref: '#/components/responses/UnprocessableContent' + '429': + $ref: '#/components/responses/TooManyRequests' '404': description: Not an id of this organization, or it was deleted (not_found). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:read x-llm: scope: fax:read mutating: false @@ -8396,12 +6794,8 @@ paths: application/json: schema: $ref: '#/components/schemas/OneTimeOrderCreated' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' + '401': + $ref: '#/components/responses/Unauthorized' '403': description: The key lacks fax:send (scope_missing), or the send has no approval and no policy allows it (approval_required). @@ -8409,37 +6803,20 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + '404': + $ref: '#/components/responses/NotFound' '409': description: The quote expired (quote_expired), or the document changed since the quote (document_hash_mismatch). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '503': - description: One-time sends are switched off on this server (one_time_unavailable). Nothing was created - or charged. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' parameters: - name: Idempotency-Key in: header @@ -8450,6 +6827,10 @@ paths: description: 'Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay.' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: fax:send x-llm: scope: fax:send mutating: true @@ -8480,30 +6861,22 @@ paths: application/json: schema: $ref: '#/components/schemas/OneTimeConfirmSummary' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '404': description: The confirmation link is not valid (link_invalid). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: [] x-llm: scope: none mutating: false idempotency_key: false agent_key_allowed: true - security: [] /v1/one-time-sends/by-token/{token}: get: tags: @@ -8529,30 +6902,22 @@ paths: application/json: schema: $ref: '#/components/schemas/OneTimeConfirmSummary' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '404': description: The confirmation link is not valid (link_invalid). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: [] x-llm: scope: none mutating: false idempotency_key: false agent_key_allowed: true - security: [] /v1/one-time-sends/{one_time_order_id}: get: tags: @@ -8589,25 +6954,21 @@ paths: application/json: schema: $ref: '#/components/schemas/OneTimeOrder' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' '404': - description: No such order. A wrong token, another organization's key and an unknown id all answer this - (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + - orderToken: [] + x-required-scope: fax:read x-llm: scope: fax:read mutating: false @@ -8615,10 +6976,6 @@ paths: agent_key_allowed: true hint: Poll this. next names the step that is waiting, fax carries the job and its evidence once released. order_token: true - security: - - bearerAuth: [] - - apiKeyHeader: [] - - orderToken: [] /v1/one-time-sends/{one_time_order_id}/receipt.pdf: get: tags: @@ -8657,41 +7014,33 @@ paths: description: The receipt as a PDF content: application/pdf: {} - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' '409': description: 'No receipt yet: the order has no fax, or the fax has not ended (conflict).' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '404': - description: No such order. A wrong token, another organization's key and an unknown id all answer this - (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + - orderToken: [] + x-required-scope: fax:read x-llm: scope: fax:read mutating: false idempotency_key: false agent_key_allowed: true order_token: true - security: - - bearerAuth: [] - - apiKeyHeader: [] - - orderToken: [] /v1/one-time-sends/{one_time_order_id}/checkout: post: tags: @@ -8741,38 +7090,26 @@ paths: application/json: schema: $ref: '#/components/schemas/OneTimeCheckout' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' + '401': + $ref: '#/components/responses/Unauthorized' + '402': + $ref: '#/components/responses/PaymentRequired' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' '409': description: The order is already paid (already_paid), or it ended (order_closed). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '503': - description: One-time sends are switched off on this server (one_time_unavailable). Nothing was created - or charged. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '404': - description: No such order. A wrong token, another organization's key and an unknown id all answer this - (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' requestBody: required: false content: @@ -8788,6 +7125,11 @@ paths: type: boolean title: OneTimeCheckoutRequest type: object + security: + - bearerAuth: [] + - apiKeyHeader: [] + - orderToken: [] + x-required-scope: fax:send x-llm: scope: fax:send mutating: true @@ -8796,10 +7138,6 @@ paths: hint: The card is authorized on the hosted page and charged only when the carrier confirms delivery. A person pays, never the agent. order_token: true - security: - - bearerAuth: [] - - apiKeyHeader: [] - - orderToken: [] /v1/one-time-sends/{one_time_order_id}/confirm: post: tags: @@ -8830,12 +7168,6 @@ paths: application/json: schema: $ref: '#/components/schemas/OneTimeConfirmed' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '404': description: The confirmation link is not valid for this order (link_invalid). content: @@ -8849,26 +7181,19 @@ paths: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '503': - description: One-time sends are switched off on this server (one_time_unavailable). Nothing was created - or charged. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' + security: [] x-llm: scope: none mutating: true idempotency_key: false agent_key_allowed: true hint: The token comes from the mailed link and works once. This releases the fax. - security: [] /v1/one-time-sends/{one_time_order_id}/resend-confirmation: post: tags: @@ -8915,38 +7240,29 @@ paths: application/json: schema: $ref: '#/components/schemas/OneTimeOrder' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' + '401': + $ref: '#/components/responses/Unauthorized' + '403': + $ref: '#/components/responses/Forbidden' + '404': + $ref: '#/components/responses/NotFound' '409': description: The order is not waiting for its confirmation (order_closed). content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' - '503': - description: One-time sends are switched off on this server (one_time_unavailable). Nothing was created - or charged. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' - '404': - description: No such order. A wrong token, another organization's key and an unknown id all answer this - (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + '503': + $ref: '#/components/responses/ServiceUnavailable' + security: + - bearerAuth: [] + - apiKeyHeader: [] + - orderToken: [] + x-required-scope: fax:send x-llm: scope: fax:send mutating: true @@ -8954,10 +7270,6 @@ paths: agent_key_allowed: true hint: At most three times per order and once in ten minutes. order_token: true - security: - - bearerAuth: [] - - apiKeyHeader: [] - - orderToken: [] /v1/oauth/grants: get: tags: @@ -8990,36 +7302,20 @@ paths: application/json: schema: $ref: '#/components/schemas/GrantList' - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope key:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: key:admin x-llm: scope: key:admin mutating: false @@ -9051,36 +7347,22 @@ paths: responses: '204': description: Successful Response - '422': - description: Validation Error - content: - application/json: - schema: - $ref: '#/components/schemas/HTTPValidationError' '401': - description: No key, or a key that was revoked or expired (invalid_token). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Unauthorized' '403': - description: The key lacks the scope key:admin (scope_missing). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/Forbidden' '404': - description: Not an id of this organization, or it was deleted (not_found). - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/NotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableContent' '429': - description: Rate limit reached (rate_limited). Retry after the seconds in Retry-After. - content: - application/json: - schema: - $ref: '#/components/schemas/ErrorEnvelope' + $ref: '#/components/responses/TooManyRequests' + security: + - bearerAuth: [] + - apiKeyHeader: [] + x-required-scope: key:admin x-llm: scope: key:admin mutating: true @@ -9104,79 +7386,205 @@ components: description: The status token of one one-time order, answered once by the create. It reads that order, opens its checkout and mails its confirmation link again, for a caller with no key. The same value is accepted as the query parameter `t`. + signedUrl: + type: apiKey + in: query + name: sig + description: A short-lived signed URL the API handed out, with `exp` and `sig` in the query. Use the URL as + it was given. No API key is sent with it. + responses: + Unauthorized: + description: 'No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where + a signed-in session is needed. error.details.reason says why a key was refused.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + PaymentRequired: + description: 'The prepaid balance does not cover the call: insufficient_balance.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + Forbidden: + description: The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. + Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + NotFound: + description: 'not_found: no such resource for this credential. A resource of another organization answers + the same.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + Conflict: + description: The resource is in a state that refuses the call, or the Idempotency-Key was used with a different + request (idempotency_key_conflict). error.code names the state. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + PayloadTooLarge: + description: 'The body is larger than the limit of this call: payload_too_large.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + UnprocessableContent: + description: 'A field failed validation: invalid_request, with one entry per field in error.details, or a + code that names the rule.' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + TooManyRequests: + description: rate_limited. Retry-After and the RateLimit-* headers say when to try again. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' + ServiceUnavailable: + description: Something this call depends on is not available or not set up here, for example billing_unavailable + or provider_unavailable. error.retryable says whether to send the same call again. + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorEnvelope' schemas: - AbuseReview: + Agent: properties: id: type: string title: Id - org_id: + name: type: string - title: Org Id - key_id: + title: Name + purpose: anyOf: - type: string - type: 'null' - title: Key Id + title: Purpose + enabled: + type: boolean + title: Enabled status: type: string - enum: - - open - - resolved title: Status - action: + project_id: + anyOf: + - type: string + - type: 'null' + title: Project Id + policy_ids: + items: + type: string + type: array + title: Policy Ids + contact_email: + anyOf: + - type: string + - type: 'null' + title: Contact Email + budget_id: + anyOf: + - type: string + - type: 'null' + title: Budget Id + budgets: + items: + additionalProperties: true + type: object + type: array + title: Budgets + keys: + items: + $ref: '#/components/schemas/ApiKey' + type: array + title: Keys + created_by: type: string - enum: - - none - - suspended - title: Action - opened_by: + title: Created By + created_at: type: string - title: Opened By + title: Created At + updated_at: + type: string + title: Updated At + disabled_at: + anyOf: + - type: string + - type: 'null' + title: Disabled At additionalProperties: true type: object required: - id - - org_id + - name + - purpose + - enabled - status - - action - - opened_by - title: AbuseReview - AbuseReviewCreate: + - project_id + - policy_ids + - contact_email + - budget_id + - budgets + - keys + - created_by + - created_at + - updated_at + - disabled_at + title: Agent + AgentActivity: properties: - org_id: + id: type: string - maxLength: 64 - minLength: 3 - title: Org Id - key_id: + title: Id + actor: + type: string + title: Actor + action: + type: string + title: Action + resource_type: + type: string + title: Resource Type + resource_id: anyOf: - type: string - maxLength: 64 - type: 'null' - title: Key Id - reason: + title: Resource Id + data: + additionalProperties: true + type: object + title: Data + correlation_id: + anyOf: + - type: string + - type: 'null' + title: Correlation Id + created_at: type: string - maxLength: 500 - minLength: 3 - title: Reason - description: 'Why: recorded on the audit row' - suspend: - type: boolean - title: Suspend - description: Suspend sends for the organization or key at once - default: false - additionalProperties: false + title: Created At + additionalProperties: true type: object required: - - org_id - - reason - title: AbuseReviewCreate - AbuseReviewPage: + - id + - actor + - action + - resource_type + - resource_id + - data + - correlation_id + - created_at + title: AgentActivity + AgentActivityPage: properties: items: items: - $ref: '#/components/schemas/AbuseReview' + $ref: '#/components/schemas/AgentActivity' type: array title: Items next_cursor: @@ -9188,418 +7596,469 @@ components: type: object required: - items - title: AbuseReviewPage - AbuseReviewPatch: + title: AgentActivityPage + AgentCreate: properties: - action: - type: string - enum: - - suspend - - unsuspend - - resolve - title: Action - reason: + name: type: string - maxLength: 500 - minLength: 3 - title: Reason - description: 'Why: recorded on the audit row' + maxLength: 120 + minLength: 1 + title: Name + purpose: + anyOf: + - type: string + maxLength: 500 + - type: 'null' + title: Purpose + description: Shown to humans, never evaluated. + policy_ids: + items: + type: string + type: array + title: Policy Ids + contact_email: + anyOf: + - type: string + maxLength: 254 + - type: 'null' + title: Contact Email + description: Where decided approvals are mailed. additionalProperties: false type: object required: - - action - - reason - title: AbuseReviewPatch - Accepted: - properties: - organization: - $ref: '#/components/schemas/OrganizationSummary' - additionalProperties: true - type: object - required: - - organization - title: Accepted - Adjustment: + - name + title: AgentCreate + AgentKeyCreate: properties: - id: - type: string - title: Id - org_id: + label: type: string - title: Org Id + maxLength: 120 + minLength: 1 + title: Label + default: agent key environment: type: string + enum: + - live + - test title: Environment - direction: - type: string - title: Direction - amount_micro: - type: integer - title: Amount Micro - status: - type: string - title: Status - proposed_by: - type: string - title: Proposed By - applied_by: + default: test + scopes: anyOf: - - type: string + - items: + type: string + type: array - type: 'null' - title: Applied By - txn_id: + title: Scopes + description: Omit for the default agent set. Never approval:decide, key:admin, policy:admin, agent:admin. + expires_in_days: anyOf: - - type: string + - type: integer + maximum: 3650.0 + minimum: 1.0 - type: 'null' - title: Txn Id - additionalProperties: true + title: Expires In Days + additionalProperties: false type: object - required: - - id - - org_id - - environment - - direction - - amount_micro - - status - - proposed_by - title: Adjustment - AdjustmentApply: - properties: - reason: - type: string - maxLength: 500 - minLength: 3 - title: Reason - description: 'Why: recorded on the audit row' - confirm: - type: boolean - title: Confirm - description: Required when the proposer applies their own adjustment - default: false - additionalProperties: false - type: object - required: - - reason - title: AdjustmentApply - AdjustmentCreate: - properties: - org_id: - type: string - maxLength: 64 - minLength: 3 - title: Org Id - environment: - type: string - enum: - - live - - test - title: Environment - default: live - direction: - type: string - enum: - - credit - - debit - title: Direction - amount_micro: - type: integer - maximum: 10000000000.0 - exclusiveMinimum: 0.0 - title: Amount Micro - description: Integer micro-USD; at most 10,000.00 - reason: - type: string - maxLength: 500 - minLength: 3 - title: Reason - description: 'Why: recorded on the audit row' - additionalProperties: false - type: object - required: - - org_id - - direction - - amount_micro - - reason - title: AdjustmentCreate - AdjustmentPage: + title: AgentKeyCreate + AgentList: properties: items: items: - $ref: '#/components/schemas/Adjustment' + $ref: '#/components/schemas/Agent' type: array title: Items - next_cursor: - anyOf: - - type: string - - type: 'null' - title: Next Cursor additionalProperties: true type: object required: - items - title: AdjustmentPage - AdminAction: - properties: - reason: - type: string - maxLength: 500 - minLength: 3 - title: Reason - description: 'Why: recorded on the audit row' - additionalProperties: false - type: object - required: - - reason - title: AdminAction - AdminBrief: + title: AgentList + AgentUpdate: properties: - utc_day: + name: anyOf: - type: string + maxLength: 120 + minLength: 1 - type: 'null' - title: Utc Day - text: + title: Name + purpose: anyOf: - type: string + maxLength: 500 - type: 'null' - title: Text - posted_at: + title: Purpose + enabled: + anyOf: + - type: boolean + - type: 'null' + title: Enabled + description: false revokes every key of the agent. + policy_ids: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Policy Ids + contact_email: anyOf: - type: string + maxLength: 254 - type: 'null' - title: Posted At - channel: + title: Contact Email + additionalProperties: false + type: object + title: AgentUpdate + ApiKey: + properties: + id: + type: string + title: Id + label: + type: string + title: Label + prefix: + type: string + title: Prefix + environment: + type: string + enum: + - live + - test + title: Environment + project_id: anyOf: - type: string - type: 'null' - title: Channel - status: + title: Project Id + agent_id: anyOf: - type: string - enum: - - posted - - failed - - gave_up - type: 'null' - title: Status - attempts: - type: integer - title: Attempts - default: 0 - local_day: + title: Agent Id + scopes: + items: + type: string + type: array + title: Scopes + created_at: + type: string + title: Created At + last_used_at: anyOf: - type: string - type: 'null' - title: Local Day - attempted_at: + title: Last Used At + expires_at: anyOf: - type: string - type: 'null' - title: Attempted At - attempt_utc_day: + title: Expires At + revoked_at: anyOf: - type: string - type: 'null' - title: Attempt Utc Day - retry_after_s: - type: integer - title: Retry After S - default: 600 - waiting_day: + title: Revoked At + rotated_from_id: anyOf: - type: string - type: 'null' - title: Waiting Day - additionalProperties: true - type: object - title: AdminBrief - AdminDaily: - properties: - metric: - type: string - title: Metric - description: - type: string - title: Description - days: - type: integer - title: Days - items: - items: - $ref: '#/components/schemas/AdminDailyPoint' - type: array - title: Items + title: Rotated From Id + connected_app: + type: boolean + title: Connected App + description: The key belongs to a connected app used over stdio, such as the Gemini CLI extension. The + organization's auto-send setting (Settings, Connected apps) binds it like an OAuth connection. + default: false additionalProperties: true type: object required: - - metric - - description - - days - - items - title: AdminDaily - AdminDailyPoint: + - id + - label + - prefix + - environment + - project_id + - agent_id + - scopes + - created_at + - last_used_at + - expires_at + - revoked_at + - rotated_from_id + title: ApiKey + ApiKeyCreate: properties: - day: + label: type: string - title: Day + maxLength: 120 + minLength: 1 + title: Label environment: type: string + enum: + - live + - test title: Environment - dims: - additionalProperties: true - type: object - title: Dims - value_num: + default: test + scopes: anyOf: - - type: integer + - items: + type: string + type: array - type: 'null' - title: Value Num - value_json: - title: Value Json - computed_at: - type: string - title: Computed At + title: Scopes + description: Omit for the default agent set; '*' for all. + expires_in_days: + anyOf: + - type: integer + maximum: 3650.0 + minimum: 1.0 + - type: 'null' + title: Expires In Days + connected_app: + type: boolean + title: Connected App + description: 'This key is for a connected app such as the Gemini CLI extension: the auto-send setting + binds it. Not available on an agent''s key.' + default: false + additionalProperties: false + type: object + required: + - label + title: ApiKeyCreate + ApiKeyList: + properties: + items: + items: + $ref: '#/components/schemas/ApiKey' + type: array + title: Items additionalProperties: true type: object required: - - day - - environment - - dims - - computed_at - title: AdminDailyPoint - AdminJob: + - items + title: ApiKeyList + ApiKeyWithSecret: properties: id: type: string title: Id - org_id: - type: string - title: Org Id - state: + label: type: string - title: State - route: + title: Label + prefix: type: string - title: Route + title: Prefix environment: type: string enum: - live - test title: Environment - age_s: - type: integer - title: Age S + project_id: + anyOf: + - type: string + - type: 'null' + title: Project Id + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + scopes: + items: + type: string + type: array + title: Scopes + created_at: + type: string + title: Created At + last_used_at: + anyOf: + - type: string + - type: 'null' + title: Last Used At + expires_at: + anyOf: + - type: string + - type: 'null' + title: Expires At + revoked_at: + anyOf: + - type: string + - type: 'null' + title: Revoked At + rotated_from_id: + anyOf: + - type: string + - type: 'null' + title: Rotated From Id + connected_app: + type: boolean + title: Connected App + description: The key belongs to a connected app used over stdio, such as the Gemini CLI extension. The + organization's auto-send setting (Settings, Connected apps) binds it like an OAuth connection. + default: false + secret: + type: string + title: Secret + description: Shown once. Store it now; it cannot be read back. additionalProperties: true type: object required: - id - - org_id - - state - - route + - label + - prefix - environment - - age_s - title: AdminJob - AdminJobPage: + - project_id + - agent_id + - scopes + - created_at + - last_used_at + - expires_at + - revoked_at + - rotated_from_id + - secret + title: ApiKeyWithSecret + ApprovalDecision: properties: - items: - items: - $ref: '#/components/schemas/AdminJob' - type: array - title: Items - next_cursor: + reason: anyOf: - type: string + maxLength: 500 - type: 'null' - title: Next Cursor - additionalProperties: true + title: Reason + additionalProperties: false type: object - required: - - items - title: AdminJobPage - AdminOrganization: + title: ApprovalDecision + ApprovalRequest: properties: id: type: string title: Id - name: + kind: type: string - title: Name - suspended_at: + enum: + - send + - help + title: Kind + status: + type: string + enum: + - pending + - approved + - rejected + - revoked + - expired + title: Status + quote_id: anyOf: - type: string - type: 'null' - title: Suspended At - internal: - type: boolean - title: Internal - default: false - balances_micro: + title: Quote Id + bound: additionalProperties: true type: object - title: Balances Micro - counts: - additionalProperties: - type: integer - type: object - title: Counts + title: Bound + message: + anyOf: + - type: string + - type: 'null' + title: Message + requested_by: + type: string + title: Requested By + decided_by: + anyOf: + - type: string + - type: 'null' + title: Decided By + reason: + anyOf: + - type: string + - type: 'null' + title: Reason + consumed_by_job_id: + anyOf: + - type: string + - type: 'null' + title: Consumed By Job Id + created_at: + type: string + title: Created At + expires_at: + anyOf: + - type: string + - type: 'null' + title: Expires At + decided_at: + anyOf: + - type: string + - type: 'null' + title: Decided At + notified: + anyOf: + - type: boolean + - type: 'null' + title: Notified + description: 'On creation: whether the organization was mailed. false when the request repeats a pending + one or the organization''s daily cap of request mails is reached; the request is still shown in the + dashboard.' additionalProperties: true type: object required: - id - - name - - balances_micro - - counts - title: AdminOrganization - AdminOrganizationDetail: + - kind + - status + - quote_id + - bound + - message + - requested_by + - decided_by + - reason + - consumed_by_job_id + - created_at + - expires_at + - decided_at + title: ApprovalRequest + ApprovalRequestCreate: properties: - organization: - additionalProperties: true - type: object - title: Organization - members: - items: - additionalProperties: true - type: object - type: array - title: Members - keys: - items: - additionalProperties: true - type: object - type: array - title: Keys - recent_jobs: - items: - additionalProperties: true - type: object - type: array - title: Recent Jobs - ledger: - additionalProperties: true - type: object - title: Ledger - open_reviews: - items: - additionalProperties: true - type: object - type: array - title: Open Reviews - additionalProperties: true + kind: + type: string + enum: + - send + - help + title: Kind + default: send + quote_id: + anyOf: + - type: string + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ + - type: 'null' + title: Quote Id + description: The quote to bind (kind send). + message: + anyOf: + - type: string + maxLength: 2000 + - type: 'null' + title: Message + description: What the person should know (kind help). Shown as data. + fax_job_id: + anyOf: + - type: string + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ + - type: 'null' + title: Fax Job Id + additionalProperties: false type: object - required: - - organization - - members - - keys - - recent_jobs - - ledger - - open_reviews - title: AdminOrganizationDetail - AdminOrganizationPage: + title: ApprovalRequestCreate + ApprovalRequestPage: properties: items: items: - $ref: '#/components/schemas/AdminOrganization' + $ref: '#/components/schemas/ApprovalRequest' type: array title: Items next_cursor: @@ -9611,776 +8070,364 @@ components: type: object required: - items - title: AdminOrganizationPage - AdminRevenue: - properties: - computed_at: - type: string - title: Computed At - days: - type: integer - title: Days - captured: - additionalProperties: true - type: object - title: Captured - funded: - additionalProperties: true - type: object - title: Funded - refunded: - additionalProperties: true - type: object - title: Refunded - recurring: - additionalProperties: true - type: object - title: Recurring - balances_micro: - additionalProperties: - additionalProperties: - type: integer - type: object - type: object - title: Balances Micro - by_day: - items: - additionalProperties: true - type: object - type: array - title: By Day - data_age: - additionalProperties: true - type: object - title: Data Age - sources: - items: - additionalProperties: true - type: object - type: array - title: Sources - additionalProperties: true - type: object - required: - - computed_at - - days - - captured - - funded - - refunded - - recurring - - balances_micro - - by_day - - data_age - - sources - title: AdminRevenue - AdminStats: - properties: - computed_at: - type: string - title: Computed At - jobs_by_state: - additionalProperties: - type: integer - type: object - title: Jobs By State - by_environment: - additionalProperties: true - type: object - title: By Environment - live_sends: - additionalProperties: true - type: object - title: Live Sends - needs_you: - additionalProperties: true - type: object - title: Needs You - window: - additionalProperties: true - type: object - title: Window - totals: - additionalProperties: true - type: object - title: Totals - money_live_micro: - additionalProperties: - type: integer - type: object - title: Money Live Micro - additionalProperties: true - type: object - required: - - computed_at - - jobs_by_state - - by_environment - - live_sends - - needs_you - - window - - totals - - money_live_micro - title: AdminStats - AdminWhoami: - properties: - kind: - type: string - enum: - - user - - service - - dev - title: Kind - identity: - type: string - title: Identity - actor: - type: string - title: Actor - read_only: - type: boolean - title: Read Only - additionalProperties: true - type: object - required: - - kind - - identity - - actor - - read_only - title: AdminWhoami - Agent: + title: ApprovalRequestPage + Attempt: properties: id: type: string title: Id - name: + fax_job_id: type: string - title: Name - purpose: + title: Fax Job Id + attempt_number: + type: integer + title: Attempt Number + provider: + type: string + title: Provider + provider_ref: anyOf: - type: string - type: 'null' - title: Purpose - enabled: - type: boolean - title: Enabled + title: Provider Ref status: type: string title: Status - project_id: + pages_sent: + type: integer + title: Pages Sent + failure_code: anyOf: - type: string - type: 'null' - title: Project Id - policy_ids: - items: - type: string - type: array - title: Policy Ids - contact_email: + title: Failure Code + evidence: anyOf: - - type: string + - additionalProperties: true + type: object - type: 'null' - title: Contact Email - budget_id: + title: Evidence + error: anyOf: - type: string - type: 'null' - title: Budget Id - budgets: - items: - additionalProperties: true - type: object - type: array - title: Budgets - keys: - items: - $ref: '#/components/schemas/ApiKey' - type: array - title: Keys - created_by: - type: string - title: Created By - created_at: - type: string - title: Created At - updated_at: + title: Error + started_at: type: string - title: Updated At - disabled_at: + title: Started At + finished_at: anyOf: - type: string - type: 'null' - title: Disabled At + title: Finished At additionalProperties: true type: object required: - id - - name - - purpose - - enabled + - fax_job_id + - attempt_number + - provider + - provider_ref - status - - project_id - - policy_ids - - contact_email - - budget_id - - budgets - - keys - - created_by - - created_at - - updated_at - - disabled_at - title: Agent - AgentActivity: - properties: - id: - type: string - title: Id - actor: - type: string - title: Actor - action: - type: string - title: Action - resource_type: - type: string - title: Resource Type - resource_id: - anyOf: - - type: string - - type: 'null' - title: Resource Id - data: - additionalProperties: true - type: object - title: Data - correlation_id: - anyOf: - - type: string - - type: 'null' - title: Correlation Id - created_at: - type: string - title: Created At - additionalProperties: true - type: object - required: - - id - - actor - - action - - resource_type - - resource_id - - data - - correlation_id - - created_at - title: AgentActivity - AgentActivityPage: + - pages_sent + - failure_code + - evidence + - error + - started_at + - finished_at + title: Attempt + AttemptPage: properties: items: items: - $ref: '#/components/schemas/AgentActivity' + $ref: '#/components/schemas/Attempt' type: array title: Items - next_cursor: - anyOf: - - type: string - - type: 'null' - title: Next Cursor additionalProperties: true type: object required: - items - title: AgentActivityPage - AgentCreate: + title: AttemptPage + AutoSendSetting: properties: - name: + environment: type: string - maxLength: 120 - minLength: 1 - title: Name - purpose: + enum: + - live + - test + title: Environment + enabled: + type: boolean + title: Enabled + max_amount_micro: + type: integer + title: Max Amount Micro + description: Amount per fax, at most, in micro-units of USD. + daily_max_jobs: + type: integer + title: Daily Max Jobs + description: Faxes per UTC day, at most, across every connected app. + policy_id: anyOf: - type: string - maxLength: 500 - type: 'null' - title: Purpose - description: Shown to humans, never evaluated. - policy_ids: - items: - type: string - type: array - title: Policy Ids - contact_email: + title: Policy Id + description: The managed policy; null before the first enable. + version: anyOf: - - type: string - maxLength: 254 + - type: integer - type: 'null' - title: Contact Email - description: Where decided approvals are mailed. + title: Version + additionalProperties: true + type: object + required: + - environment + - enabled + - max_amount_micro + - daily_max_jobs + - policy_id + - version + title: AutoSendSetting + description: |- + The organization's auto-send setting for one environment: Settings, Connected apps, "Let connected + apps send without asking". Stored as the managed policy ``policy_id`` (docs/APPROVALS.md). + AutoSendUpdate: + properties: + enabled: + type: boolean + title: Enabled + max_amount_micro: + type: integer + maximum: 1000000000000.0 + minimum: 0.0 + title: Max Amount Micro + description: Amount per fax, at most, in micro-units of USD (5000000 is five US dollars). + default: 5000000 + daily_max_jobs: + type: integer + maximum: 100000.0 + minimum: 1.0 + title: Daily Max Jobs + description: Faxes per UTC day. + default: 20 additionalProperties: false type: object required: - - name - title: AgentCreate - AgentKeyCreate: + - enabled + title: AutoSendUpdate + AutoTopup: properties: - label: + id: type: string - maxLength: 120 - minLength: 1 - title: Label - default: agent key + title: Id environment: type: string enum: - live - test title: Environment - default: test - scopes: - anyOf: - - items: - type: string - type: array - - type: 'null' - title: Scopes - description: Omit for the default agent set. Never approval:decide, key:admin, policy:admin, agent:admin. - expires_in_days: - anyOf: - - type: integer - maximum: 3650.0 - minimum: 1.0 - - type: 'null' - title: Expires In Days - additionalProperties: false - type: object - title: AgentKeyCreate - AgentList: - properties: - items: - items: - $ref: '#/components/schemas/Agent' - type: array - title: Items - additionalProperties: true - type: object - required: - - items - title: AgentList - AgentUpdate: - properties: - name: + status: + type: string + enum: + - pending_setup + - active + - disabled + title: Status + threshold_micro: + type: integer + title: Threshold Micro + amount_micro: + type: integer + title: Amount Micro + daily_cap_micro: + type: integer + title: Daily Cap Micro + payment_method_saved: + type: boolean + title: Payment Method Saved + setup_session_id: anyOf: - type: string - maxLength: 120 - minLength: 1 - type: 'null' - title: Name - purpose: + title: Setup Session Id + setup_url: anyOf: - type: string - maxLength: 500 - - type: 'null' - title: Purpose - enabled: - anyOf: - - type: boolean - type: 'null' - title: Enabled - description: false revokes every key of the agent. - policy_ids: + title: Setup Url + description: Where to save the card while status is pending_setup. + created_at: + type: string + title: Created At + updated_at: + type: string + title: Updated At + last_attempt_at: anyOf: - - items: - type: string - type: array + - type: string - type: 'null' - title: Policy Ids - contact_email: + title: Last Attempt At + disabled_at: anyOf: - type: string - maxLength: 254 - type: 'null' - title: Contact Email - additionalProperties: false + title: Disabled At + additionalProperties: true type: object - title: AgentUpdate - AnalyticsJourneys: + required: + - id + - environment + - status + - threshold_micro + - amount_micro + - daily_cap_micro + - payment_method_saved + - setup_session_id + - created_at + - updated_at + - last_attempt_at + - disabled_at + title: AutoTopup + AutoTopupCreate: properties: - computed_at: - type: string - title: Computed At - days: + threshold_micro: type: integer - title: Days - window: - additionalProperties: - type: string - type: object - title: Window - cohort: + minimum: 0.0 + title: Threshold Micro + description: Top up when the available balance drops below this. + amount_micro: type: integer - title: Cohort - funnel: - items: - additionalProperties: true - type: object - type: array - title: Funnel - leakiest: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Leakiest - doors: - items: - additionalProperties: true - type: object - type: array - title: Doors - topups: - additionalProperties: true - type: object - title: Topups - site: - additionalProperties: true - type: object - title: Site - organizations: - items: - additionalProperties: true - type: object - type: array - title: Organizations - listed: + maximum: 1000000000.0 + minimum: 10000000.0 + title: Amount Micro + description: Whole dollars, 10 to 1000 USD. + daily_cap_micro: type: integer - title: Listed - additionalProperties: true + minimum: 10000000.0 + title: Daily Cap Micro + description: Never more than this per UTC day. + additionalProperties: false type: object required: - - computed_at - - days - - window - - cohort - - funnel - - doors - - topups - - site - - organizations - - listed - title: AnalyticsJourneys - AnalyticsOrganization: + - threshold_micro + - amount_micro + - daily_cap_micro + title: AutoTopupCreate + AutoTopupList: properties: - computed_at: - type: string - title: Computed At - days: - type: integer - title: Days - window: - additionalProperties: - type: string - type: object - title: Window - organization: - additionalProperties: true - type: object - title: Organization - steps: - items: - additionalProperties: true - type: object - type: array - title: Steps - members: - items: - additionalProperties: true - type: object - type: array - title: Members - doors: - items: - additionalProperties: true - type: object - type: array - title: Doors - keys: - additionalProperties: true - type: object - title: Keys - jobs: - additionalProperties: true - type: object - title: Jobs - topups: - items: - additionalProperties: true - type: object - type: array - title: Topups - inbound: - additionalProperties: true - type: object - title: Inbound - numbers: - additionalProperties: true - type: object - title: Numbers - actions: - items: - additionalProperties: true - type: object - type: array - title: Actions - recent: - items: - additionalProperties: true - type: object - type: array - title: Recent - usage: - items: - additionalProperties: true - type: object - type: array - title: Usage - tools: + items: items: - additionalProperties: true - type: object + $ref: '#/components/schemas/AutoTopup' type: array - title: Tools + title: Items additionalProperties: true type: object required: - - computed_at - - days - - window - - organization - - steps - - members - - doors - - keys - - jobs - - topups - - inbound - - numbers - - actions - - recent - - usage - - tools - title: AnalyticsOrganization - AnalyticsSource: + - items + title: AutoTopupList + Balance: properties: - source: - type: string - title: Source - label: + environment: type: string - title: Label - status: + enum: + - live + - test + title: Environment + currency: type: string - title: Status - missing: - items: - type: string - type: array - title: Missing - step: + title: Currency + available_micro: type: integer - title: Step - error: - anyOf: - - type: string - - type: 'null' - title: Error - last_pulled_at: - anyOf: - - type: string - - type: 'null' - title: Last Pulled At - latest_day: + title: Available Micro + held_micro: + type: integer + title: Held Micro + top_up_url: anyOf: - type: string - type: 'null' - title: Latest Day + title: Top Up Url + description: The dashboard page where a person adds funds to the wallet. A key cannot top up. additionalProperties: true type: object required: - - source - - label - - status - - missing - - step - title: AnalyticsSource - AnalyticsSources: + - environment + - currency + - available_micro + - held_micro + title: Balance + BillingSettings: properties: - items: - items: - $ref: '#/components/schemas/AnalyticsSource' - type: array - title: Items - pull: - additionalProperties: true - type: object - title: Pull - additionalProperties: true - type: object - required: - - items - - pull - title: AnalyticsSources - AnalyticsUsage: - properties: - computed_at: - type: string - title: Computed At - days: - type: integer - title: Days - window: - additionalProperties: - type: string - type: object - title: Window org_id: + type: string + title: Org Id + billing_email: anyOf: - type: string - type: 'null' - title: Org Id - totals: - additionalProperties: true - type: object - title: Totals - by_day: - items: - additionalProperties: true - type: object - type: array - title: By Day - by_surface: - items: - additionalProperties: true - type: object - type: array - title: By Surface - by_family: - items: - additionalProperties: true - type: object - type: array - title: By Family - top_organizations: - items: - additionalProperties: true - type: object - type: array - title: Top Organizations - top_keys: - items: - additionalProperties: true - type: object - type: array - title: Top Keys - tools: - additionalProperties: true - type: object - title: Tools - data_age: - additionalProperties: true - type: object - title: Data Age + title: Billing Email + low_balance_threshold_micro: + type: integer + title: Low Balance Threshold Micro + low_balance_active: + type: boolean + title: Low Balance Active + workspace: + type: boolean + title: Workspace + disputed: + type: boolean + title: Disputed + stripe_customer: + type: boolean + title: Stripe Customer additionalProperties: true type: object required: - - computed_at - - days - - window - - totals - - by_day - - by_surface - - by_family - - top_organizations - - top_keys - - tools - - data_age - title: AnalyticsUsage - AnalyticsWebsite: + - org_id + - billing_email + - low_balance_threshold_micro + - low_balance_active + - workspace + - disputed + - stripe_customer + title: BillingSettings + BillingSettingsPatch: properties: - computed_at: - type: string - title: Computed At - days: - type: integer - title: Days - window: - additionalProperties: - type: string - type: object - title: Window - sources: - items: - $ref: '#/components/schemas/AnalyticsSource' - type: array - title: Sources - search: - additionalProperties: true - type: object - title: Search - traffic: - additionalProperties: true - type: object - title: Traffic - site: - additionalProperties: true - type: object - title: Site - ux: - additionalProperties: true - type: object - title: Ux - bing: - additionalProperties: true - type: object - title: Bing - authority: - additionalProperties: true - type: object - title: Authority - data_age: - additionalProperties: true - type: object - title: Data Age - additionalProperties: true + billing_email: + anyOf: + - type: string + maxLength: 254 + format: email + - type: 'null' + title: Billing Email + low_balance_threshold_micro: + anyOf: + - type: integer + minimum: 0.0 + - type: 'null' + title: Low Balance Threshold Micro + additionalProperties: false type: object - required: - - computed_at - - days - - window - - sources - - search - - traffic - - site - - ux - - bing - - authority - - data_age - title: AnalyticsWebsite - ApiKey: + title: BillingSettingsPatch + Budget: properties: id: type: string title: Id - label: - type: string - title: Label - prefix: - type: string - title: Prefix environment: type: string enum: - live - test title: Environment + scope: + type: string + enum: + - organization + - project + - agent + title: Scope project_id: anyOf: - type: string @@ -10391,458 +8438,453 @@ components: - type: string - type: 'null' title: Agent Id - scopes: - items: - type: string - type: array - title: Scopes + period: + type: string + enum: + - daily + - monthly + title: Period + limit_micro: + type: integer + title: Limit Micro + spent_micro: + type: integer + title: Spent Micro + remaining_micro: + type: integer + title: Remaining Micro + status: + type: string + enum: + - active + - disabled + title: Status + resets_at: + type: string + title: Resets At created_at: type: string title: Created At - last_used_at: - anyOf: - - type: string - - type: 'null' - title: Last Used At - expires_at: - anyOf: - - type: string - - type: 'null' - title: Expires At - revoked_at: - anyOf: - - type: string - - type: 'null' - title: Revoked At - rotated_from_id: - anyOf: - - type: string - - type: 'null' - title: Rotated From Id - connected_app: - type: boolean - title: Connected App - description: The key belongs to a connected app used over stdio, such as the Gemini CLI extension. The - organization's auto-send setting (Settings, Connected apps) binds it like an OAuth connection. - default: false + updated_at: + type: string + title: Updated At additionalProperties: true type: object required: - id - - label - - prefix - environment + - scope - project_id - agent_id - - scopes - - created_at - - last_used_at - - expires_at - - revoked_at - - rotated_from_id - title: ApiKey - ApiKeyCreate: + - period + - limit_micro + - spent_micro + - remaining_micro + - status + - resets_at + - created_at + - updated_at + title: Budget + BudgetCreate: properties: - label: - type: string - maxLength: 120 - minLength: 1 - title: Label - environment: + scope: type: string enum: - - live - - test - title: Environment - default: test - scopes: + - organization + - project + - agent + title: Scope + default: organization + project_id: anyOf: - - items: - type: string - type: array + - type: string - type: 'null' - title: Scopes - description: Omit for the default agent set; '*' for all. - expires_in_days: + title: Project Id + agent_id: anyOf: - - type: integer - maximum: 3650.0 - minimum: 1.0 + - type: string - type: 'null' - title: Expires In Days - connected_app: - type: boolean - title: Connected App - description: 'This key is for a connected app such as the Gemini CLI extension: the auto-send setting - binds it. Not available on an agent''s key.' - default: false + title: Agent Id + period: + type: string + enum: + - daily + - monthly + title: Period + limit_micro: + type: integer + minimum: 0.0 + title: Limit Micro additionalProperties: false type: object required: - - label - title: ApiKeyCreate - ApiKeyList: + - period + - limit_micro + title: BudgetCreate + BudgetList: properties: items: items: - $ref: '#/components/schemas/ApiKey' + $ref: '#/components/schemas/Budget' type: array title: Items additionalProperties: true type: object required: - items - title: ApiKeyList - ApiKeyWithSecret: + title: BudgetList + BudgetPatch: + properties: + limit_micro: + anyOf: + - type: integer + minimum: 0.0 + - type: 'null' + title: Limit Micro + status: + anyOf: + - type: string + enum: + - active + - disabled + - type: 'null' + title: Status + additionalProperties: false + type: object + title: BudgetPatch + Capabilities: properties: - id: - type: string - title: Id - label: - type: string - title: Label - prefix: - type: string - title: Prefix environment: type: string enum: - live - test title: Environment - project_id: - anyOf: - - type: string - - type: 'null' - title: Project Id - agent_id: - anyOf: - - type: string - - type: 'null' - title: Agent Id + provider: + type: string + title: Provider + send: + type: boolean + title: Send + receive: + type: boolean + title: Receive + numbers: + type: boolean + title: Numbers + routes: + items: + type: string + type: array + title: Routes + formats: + items: + type: string + type: array + title: Formats + max_pages: + type: integer + title: Max Pages + max_upload_bytes: + type: integer + title: Max Upload Bytes + price_version: + type: string + title: Price Version + rates: + additionalProperties: true + type: object + title: Rates scopes: items: type: string type: array title: Scopes - created_at: - type: string - title: Created At - last_used_at: - anyOf: - - type: string - - type: 'null' - title: Last Used At - expires_at: + approvals: + type: boolean + title: Approvals + extraction: + type: boolean + title: Extraction + extraction_pricing: + additionalProperties: true + type: object + title: Extraction Pricing + description: What POST /v1/extractions charges, in micro-units. page_micro is for every page read. escalated_page_micro + is added for a page the stronger model reads again. max_pages is the most pages one extraction reads. + Sandbox extractions are free. + limits: + additionalProperties: + type: integer + type: object + title: Limits + one_time: + additionalProperties: true + type: object + title: One Time + additionalProperties: true + type: object + required: + - environment + - provider + - send + - receive + - numbers + - routes + - formats + - max_pages + - max_upload_bytes + - price_version + - rates + - scopes + - approvals + - limits + title: Capabilities + ClassificationCreate: + properties: + inbox_item_id: anyOf: - type: string + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Expires At - revoked_at: + title: Inbox Item Id + document_id: anyOf: - type: string + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Revoked At - rotated_from_id: + title: Document Id + max_pages: anyOf: - - type: string + - type: integer + maximum: 200.0 + minimum: 1.0 - type: 'null' - title: Rotated From Id - connected_app: + title: Max Pages + strict: type: boolean - title: Connected App - description: The key belongs to a connected app used over stdio, such as the Gemini CLI extension. The - organization's auto-send setting (Settings, Connected apps) binds it like an OAuth connection. + title: Strict + description: Refuse with page_limit_exceeded when the document has more pages than would be read, instead + of reading the first ones and warning. default: false - secret: - type: string - title: Secret - description: Shown once. Store it now; it cannot be read back. - additionalProperties: true + document_types: + items: + type: string + type: array + maxItems: 30 + minItems: 1 + title: Document Types + abstain_below: + type: number + maximum: 1.0 + minimum: 0.0 + title: Abstain Below + default: 0.6 + strong_model_if_below: + type: number + maximum: 1.0 + minimum: 0.0 + title: Strong Model If Below + default: 0.75 + additionalProperties: false type: object required: - - id - - label - - prefix - - environment - - project_id - - agent_id - - scopes - - created_at - - last_used_at - - expires_at - - revoked_at - - rotated_from_id - - secret - title: ApiKeyWithSecret - ApprovalDecision: - properties: - reason: - anyOf: - - type: string - maxLength: 500 - - type: 'null' - title: Reason - additionalProperties: false - type: object - title: ApprovalDecision - ApprovalRequest: + - document_types + title: ClassificationCreate + Correction: properties: id: type: string title: Id - kind: + extraction_id: type: string - enum: - - send - - help - title: Kind - status: + title: Extraction Id + field: type: string - enum: - - pending - - approved - - rejected - - revoked - - expired - title: Status - quote_id: - anyOf: - - type: string - - type: 'null' - title: Quote Id - bound: - additionalProperties: true - type: object - title: Bound - message: + title: Field + value: + title: Value + note: anyOf: - type: string - type: 'null' - title: Message - requested_by: + title: Note + created_by: type: string - title: Requested By - decided_by: - anyOf: - - type: string - - type: 'null' - title: Decided By - reason: - anyOf: - - type: string - - type: 'null' - title: Reason - consumed_by_job_id: - anyOf: - - type: string - - type: 'null' - title: Consumed By Job Id + title: Created By created_at: type: string title: Created At - expires_at: - anyOf: - - type: string - - type: 'null' - title: Expires At - decided_at: - anyOf: - - type: string - - type: 'null' - title: Decided At - notified: - anyOf: - - type: boolean - - type: 'null' - title: Notified - description: 'On creation: whether the organization was mailed. false when the request repeats a pending - one or the organization''s daily cap of request mails is reached; the request is still shown in the - dashboard.' additionalProperties: true type: object required: - id - - kind - - status - - quote_id - - bound - - message - - requested_by - - decided_by - - reason - - consumed_by_job_id + - extraction_id + - field + - value + - note + - created_by - created_at - - expires_at - - decided_at - title: ApprovalRequest - ApprovalRequestCreate: + title: Correction + CorrectionCreate: properties: - kind: - type: string - enum: - - send - - help - title: Kind - default: send - quote_id: - anyOf: - - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - - type: 'null' - title: Quote Id - description: The quote to bind (kind send). - message: + field: anyOf: - type: string - maxLength: 2000 + maxLength: 120 - type: 'null' - title: Message - description: What the person should know (kind help). Shown as data. - fax_job_id: + title: Field + value: + title: Value + note: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ + maxLength: 1000 - type: 'null' - title: Fax Job Id + title: Note additionalProperties: false type: object - title: ApprovalRequestCreate - ApprovalRequestPage: + title: CorrectionCreate + Coverage: properties: - items: + coverage_version: + anyOf: + - type: string + - type: 'null' + title: Coverage Version + generated_at: + anyOf: + - type: string + - type: 'null' + title: Generated At + orderable_now: items: - $ref: '#/components/schemas/ApprovalRequest' + type: string type: array - title: Items - next_cursor: + title: Orderable Now + outbound: + additionalProperties: true + type: object + title: Outbound + inbound: + additionalProperties: true + type: object + title: Inbound + excluded: + additionalProperties: true + type: object + title: Excluded + note: anyOf: - type: string - type: 'null' - title: Next Cursor + title: Note additionalProperties: true type: object required: - - items - title: ApprovalRequestPage - Attempt: + - coverage_version + - generated_at + - orderable_now + - outbound + - inbound + - excluded + - note + title: Coverage + Deleted: properties: id: type: string title: Id - fax_job_id: + deleted: + type: boolean + title: Deleted + default: true + additionalProperties: true + type: object + required: + - id + title: Deleted + Delivery: + properties: + id: type: string - title: Fax Job Id - attempt_number: - type: integer - title: Attempt Number - provider: + title: Id + webhook_id: type: string - title: Provider - provider_ref: - anyOf: - - type: string - - type: 'null' - title: Provider Ref + title: Webhook Id + event_id: + type: string + title: Event Id + event_type: + type: string + title: Event Type + attempt: + type: integer + title: Attempt status: type: string title: Status - pages_sent: - type: integer - title: Pages Sent - failure_code: - anyOf: - - type: string - - type: 'null' - title: Failure Code - evidence: + response_status: anyOf: - - additionalProperties: true - type: object + - type: integer - type: 'null' - title: Evidence + title: Response Status error: anyOf: - type: string - type: 'null' title: Error - started_at: - type: string - title: Started At - finished_at: + duration_ms: + anyOf: + - type: integer + - type: 'null' + title: Duration Ms + replay_of: anyOf: - type: string - type: 'null' - title: Finished At - additionalProperties: true - type: object - required: - - id - - fax_job_id - - attempt_number - - provider - - provider_ref - - status - - pages_sent - - failure_code - - evidence - - error - - started_at - - finished_at - title: Attempt - AttemptPage: - properties: - items: + title: Replay Of + schedule_s: items: - $ref: '#/components/schemas/Attempt' + type: integer type: array - title: Items - additionalProperties: true - type: object - required: - - items - title: AttemptPage - AuditEvent: - properties: - id: - type: string - title: Id - org_id: + title: Schedule S + next_attempt_at: anyOf: - type: string - type: 'null' - title: Org Id - actor: - type: string - title: Actor - action: - type: string - title: Action - resource_type: + title: Next Attempt At + created_at: type: string - title: Resource Type - resource_id: + title: Created At + delivered_at: anyOf: - type: string - type: 'null' - title: Resource Id - created_at: - type: string - title: Created At + title: Delivered At additionalProperties: true type: object required: - id - - actor - - action - - resource_type + - webhook_id + - event_id + - event_type + - attempt + - status + - response_status + - error + - duration_ms + - replay_of + - schedule_s + - next_attempt_at - created_at - title: AuditEvent - AuditEventPage: + - delivered_at + title: Delivery + DeliveryPage: properties: items: items: - $ref: '#/components/schemas/AuditEvent' + $ref: '#/components/schemas/Delivery' type: array title: Items next_cursor: @@ -10854,75 +8896,8 @@ components: type: object required: - items - title: AuditEventPage - AutoSendSetting: - properties: - environment: - type: string - enum: - - live - - test - title: Environment - enabled: - type: boolean - title: Enabled - max_amount_micro: - type: integer - title: Max Amount Micro - description: Amount per fax, at most, in micro-units of USD. - daily_max_jobs: - type: integer - title: Daily Max Jobs - description: Faxes per UTC day, at most, across every connected app. - policy_id: - anyOf: - - type: string - - type: 'null' - title: Policy Id - description: The managed policy; null before the first enable. - version: - anyOf: - - type: integer - - type: 'null' - title: Version - additionalProperties: true - type: object - required: - - environment - - enabled - - max_amount_micro - - daily_max_jobs - - policy_id - - version - title: AutoSendSetting - description: |- - The organization's auto-send setting for one environment: Settings, Connected apps, "Let connected - apps send without asking". Stored as the managed policy ``policy_id`` (docs/APPROVALS.md). - AutoSendUpdate: - properties: - enabled: - type: boolean - title: Enabled - max_amount_micro: - type: integer - maximum: 1000000000000.0 - minimum: 0.0 - title: Max Amount Micro - description: Amount per fax, at most, in micro-units of USD (5000000 is five US dollars). - default: 5000000 - daily_max_jobs: - type: integer - maximum: 100000.0 - minimum: 1.0 - title: Daily Max Jobs - description: Faxes per UTC day. - default: 20 - additionalProperties: false - type: object - required: - - enabled - title: AutoSendUpdate - AutoTopup: + title: DeliveryPage + Document: properties: id: type: string @@ -10935,752 +8910,716 @@ components: title: Environment status: type: string - enum: - - pending_setup - - active - - disabled title: Status - threshold_micro: - type: integer - title: Threshold Micro - amount_micro: + source: + type: string + title: Source + filename: + type: string + title: Filename + content_type: + type: string + title: Content Type + size_bytes: type: integer - title: Amount Micro - daily_cap_micro: + title: Size Bytes + sha256: + type: string + title: Sha256 + page_count: type: integer - title: Daily Cap Micro - payment_method_saved: - type: boolean - title: Payment Method Saved - setup_session_id: + title: Page Count + render_status: + type: string + title: Render Status + render_reason: anyOf: - type: string - type: 'null' - title: Setup Session Id - setup_url: + title: Render Reason + validation: + additionalProperties: true + type: object + title: Validation + upload_id: anyOf: - type: string - type: 'null' - title: Setup Url - description: Where to save the card while status is pending_setup. + title: Upload Id created_at: type: string title: Created At - updated_at: - type: string - title: Updated At - last_attempt_at: + expires_at: anyOf: - type: string - type: 'null' - title: Last Attempt At - disabled_at: + title: Expires At + deleted_at: anyOf: - type: string - type: 'null' - title: Disabled At + title: Deleted At additionalProperties: true type: object required: - id - environment - status - - threshold_micro - - amount_micro - - daily_cap_micro - - payment_method_saved - - setup_session_id + - source + - filename + - content_type + - size_bytes + - sha256 + - page_count + - render_status + - render_reason + - validation + - upload_id - created_at - - updated_at - - last_attempt_at - - disabled_at - title: AutoTopup - AutoTopupCreate: - properties: - threshold_micro: - type: integer - minimum: 0.0 - title: Threshold Micro - description: Top up when the available balance drops below this. - amount_micro: - type: integer - maximum: 1000000000.0 - minimum: 10000000.0 - title: Amount Micro - description: Whole dollars, 10 to 1000 USD. - daily_cap_micro: - type: integer - minimum: 10000000.0 - title: Daily Cap Micro - description: Never more than this per UTC day. - additionalProperties: false - type: object - required: - - threshold_micro - - amount_micro - - daily_cap_micro - title: AutoTopupCreate - AutoTopupList: + - expires_at + - deleted_at + title: Document + DocumentCreate: properties: - items: - items: - $ref: '#/components/schemas/AutoTopup' - type: array - title: Items + upload_id: + anyOf: + - type: string + - type: 'null' + title: Upload Id + text: + anyOf: + - type: string + - type: 'null' + title: Text + description: Plain text rendered to a letter PDF. + examples: + - Hello from Fax for Agents + markdown: + anyOf: + - type: string + - type: 'null' + title: Markdown + description: Markdown (headings, lists, emphasis, code) rendered to PDF. + html: + anyOf: + - type: string + - type: 'null' + title: Html + description: 'HTML rendered to PDF by a headless browser with scripts off and no network: inline CSS and + data: images print, external resources are counted as blocked. US letter unless @page says otherwise. + At most 2 MiB.' + filename: + anyOf: + - type: string + maxLength: 255 + - type: 'null' + title: Filename + additionalProperties: false + type: object + title: DocumentCreate + description: Send exactly one of text, markdown, html or upload_id. + DocumentPage: + properties: + items: + items: + $ref: '#/components/schemas/Document' + type: array + title: Items + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor additionalProperties: true type: object required: - items - title: AutoTopupList - Balance: + title: DocumentPage + DocumentPages: properties: - environment: - type: string - enum: - - live - - test - title: Environment - currency: + document_id: type: string - title: Currency - available_micro: - type: integer - title: Available Micro - held_micro: + title: Document Id + page_count: type: integer - title: Held Micro - top_up_url: + title: Page Count + render_status: + type: string + title: Render Status + render_reason: anyOf: - type: string - type: 'null' - title: Top Up Url - description: The dashboard page where a person adds funds to the wallet. A key cannot top up. + title: Render Reason + items: + items: + $ref: '#/components/schemas/PagePreview' + type: array + title: Items additionalProperties: true type: object required: - - environment - - currency - - available_micro - - held_micro - title: Balance - BillingSettings: + - document_id + - page_count + - render_status + - render_reason + - items + title: DocumentPages + DocumentValidation: properties: - org_id: + id: type: string - title: Org Id - billing_email: + title: Id + status: + type: string + title: Status + page_count: + type: integer + title: Page Count + render_status: + type: string + title: Render Status + render_reason: anyOf: - type: string - type: 'null' - title: Billing Email - low_balance_threshold_micro: - type: integer - title: Low Balance Threshold Micro - low_balance_active: - type: boolean - title: Low Balance Active - workspace: + title: Render Reason + warnings: + items: + additionalProperties: true + type: object + type: array + title: Warnings + additionalProperties: true + type: object + required: + - id + - status + - page_count + - render_status + - render_reason + - warnings + title: DocumentValidation + EffectivePolicies: + properties: + actor: + type: string + title: Actor + environment: + type: string + enum: + - live + - test + title: Environment + under_policy: type: boolean - title: Workspace - disputed: + title: Under Policy + approval_required_without_policy: type: boolean - title: Disputed - stripe_customer: + title: Approval Required Without Policy + requires_human_approval: type: boolean - title: Stripe Customer + title: Requires Human Approval + description: 'Server-set for hosted integration clients and their keys: every send needs a person''s approval, + whatever the policies say.' + default: false + policies: + items: + $ref: '#/components/schemas/Policy' + type: array + title: Policies + rules_order: + items: + type: string + type: array + title: Rules Order additionalProperties: true type: object required: - - org_id - - billing_email - - low_balance_threshold_micro - - low_balance_active - - workspace - - disputed - - stripe_customer - title: BillingSettings - BillingSettingsPatch: + - actor + - environment + - under_policy + - approval_required_without_policy + - policies + - rules_order + title: EffectivePolicies + ErrorBody: properties: - billing_email: + code: + type: string + title: Code + description: A stable code such as invalid_token, scope_missing, not_found, quote_expired, insufficient_balance, + approval_required, rate_limited, live_provider_unavailable, one_time_unavailable. + message: + type: string + title: Message + description: One sentence a person can act on. + retryable: + type: boolean + title: Retryable + correlation_id: anyOf: - type: string - maxLength: 254 - format: email - - type: 'null' - title: Billing Email - low_balance_threshold_micro: - anyOf: - - type: integer - minimum: 0.0 - type: 'null' - title: Low Balance Threshold Micro - additionalProperties: false + title: Correlation Id + description: The X-Request-Id of the request. Quote it when you write to hello@faxforagents.com. + details: + title: Details + description: Code-specific fields, for example details.scope on scope_missing. + additionalProperties: true type: object - title: BillingSettingsPatch - Budget: + required: + - code + - message + - retryable + title: ErrorBody + ErrorEnvelope: + properties: + error: + $ref: '#/components/schemas/ErrorBody' + additionalProperties: true + type: object + required: + - error + title: ErrorEnvelope + Event: properties: id: type: string title: Id + type: + type: string + title: Type + created_at: + type: string + title: Created At + org_id: + type: string + title: Org Id environment: type: string enum: - live - test title: Environment - scope: - type: string - enum: - - organization - - project - - agent - title: Scope project_id: anyOf: - type: string - type: 'null' title: Project Id - agent_id: + resource_type: + type: string + title: Resource Type + resource_id: + type: string + title: Resource Id + fax_job_id: anyOf: - type: string - type: 'null' - title: Agent Id - period: - type: string - enum: - - daily - - monthly - title: Period - limit_micro: + title: Fax Job Id + schema_version: type: integer - title: Limit Micro - spent_micro: - type: integer - title: Spent Micro - remaining_micro: - type: integer - title: Remaining Micro - status: - type: string - enum: - - active - - disabled - title: Status - resets_at: - type: string - title: Resets At - created_at: - type: string - title: Created At - updated_at: - type: string - title: Updated At + title: Schema Version + correlation_id: + anyOf: + - type: string + - type: 'null' + title: Correlation Id + data: + additionalProperties: true + type: object + title: Data additionalProperties: true type: object required: - id + - type + - created_at + - org_id - environment - - scope - project_id - - agent_id - - period - - limit_micro - - spent_micro - - remaining_micro - - status - - resets_at - - created_at - - updated_at - title: Budget - BudgetCreate: - properties: - scope: - type: string - enum: - - organization - - project - - agent - title: Scope - default: organization - project_id: - anyOf: - - type: string - - type: 'null' - title: Project Id - agent_id: - anyOf: - - type: string - - type: 'null' - title: Agent Id - period: - type: string - enum: - - daily - - monthly - title: Period - limit_micro: - type: integer - minimum: 0.0 - title: Limit Micro - additionalProperties: false - type: object - required: - - period - - limit_micro - title: BudgetCreate - BudgetList: + - resource_type + - resource_id + - fax_job_id + - schema_version + - correlation_id + - data + title: Event + EventPage: properties: items: items: - $ref: '#/components/schemas/Budget' + $ref: '#/components/schemas/Event' type: array title: Items + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor additionalProperties: true type: object required: - items - title: BudgetList - BudgetPatch: + title: EventPage + Extraction: properties: - limit_micro: - anyOf: - - type: integer - minimum: 0.0 - - type: 'null' - title: Limit Micro + id: + type: string + title: Id + kind: + type: string + enum: + - extract + - classify + - summarize + title: Kind status: - anyOf: - - type: string - enum: - - active - - disabled - - type: 'null' + type: string + enum: + - pending + - queued + - running + - completed + - failed title: Status - additionalProperties: false - type: object - title: BudgetPatch - Capabilities: - properties: environment: type: string enum: - live - test title: Environment - provider: - type: string - title: Provider - send: - type: boolean - title: Send - receive: - type: boolean - title: Receive - numbers: - type: boolean - title: Numbers - routes: - items: - type: string - type: array - title: Routes - formats: - items: - type: string - type: array - title: Formats - max_pages: - type: integer - title: Max Pages - max_upload_bytes: - type: integer - title: Max Upload Bytes - price_version: + document_id: type: string - title: Price Version - rates: - additionalProperties: true - type: object - title: Rates - scopes: - items: - type: string - type: array - title: Scopes - approvals: - type: boolean - title: Approvals - extraction: - type: boolean - title: Extraction - extraction_pricing: - additionalProperties: true - type: object - title: Extraction Pricing - description: What POST /v1/extractions charges, in micro-units. page_micro is for every page read. escalated_page_micro - is added for a page the stronger model reads again. max_pages is the most pages one extraction reads. - Sandbox extractions are free. - limits: - additionalProperties: - type: integer - type: object - title: Limits - one_time: - additionalProperties: true - type: object - title: One Time - additionalProperties: true - type: object - required: - - environment - - provider - - send - - receive - - numbers - - routes - - formats - - max_pages - - max_upload_bytes - - price_version - - rates - - scopes - - approvals - - limits - title: Capabilities - ClassificationCreate: - properties: + title: Document Id inbox_item_id: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' title: Inbox Item Id - document_id: + schema_id: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Document Id - max_pages: + title: Schema Id + schema: anyOf: - - type: integer - maximum: 200.0 - minimum: 1.0 + - additionalProperties: true + type: object - type: 'null' - title: Max Pages - strict: - type: boolean - title: Strict - description: Refuse with page_limit_exceeded when the document has more pages than would be read, instead - of reading the first ones and warning. - default: false - document_types: - items: - type: string - type: array - maxItems: 30 - minItems: 1 - title: Document Types - abstain_below: - type: number - maximum: 1.0 - minimum: 0.0 - title: Abstain Below - default: 0.6 - strong_model_if_below: - type: number - maximum: 1.0 - minimum: 0.0 - title: Strong Model If Below - default: 0.75 - additionalProperties: false - type: object - required: - - document_types - title: ClassificationCreate - Client: - properties: - id: - type: string - title: Id - client_id: - type: string - title: Client Id - kind: + title: Schema + options: + additionalProperties: true + type: object + title: Options + pages_requested: + type: integer + title: Pages Requested + pages_processed: + type: integer + title: Pages Processed + pages_escalated: + type: integer + title: Pages Escalated + document_pages: + type: integer + title: Document Pages + description: The document's page count. Above pages_processed on a completed row means the cap left pages + unread; output.truncated and a warning say so. + confidence: + anyOf: + - type: number + - type: 'null' + title: Confidence + pages: + items: + $ref: '#/components/schemas/ExtractionPage' + type: array + title: Pages + output: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Output + models: + additionalProperties: true + type: object + title: Models + price_micro: + type: integer + title: Price Micro + provider_cost_micro: + type: integer + title: Provider Cost Micro + currency: type: string - enum: - - static - - dynamic - - cimd - title: Kind - client_name: + title: Currency + error_code: anyOf: - type: string - type: 'null' - title: Client Name - client_host: + title: Error Code + created_by: type: string - title: Client Host + title: Created By created_at: type: string title: Created At - last_used_at: + started_at: anyOf: - type: string - type: 'null' - title: Last Used At - disabled_at: + title: Started At + completed_at: anyOf: - type: string - type: 'null' - title: Disabled At - disabled_reason: + title: Completed At + corrections: anyOf: - - type: string + - items: + additionalProperties: true + type: object + type: array - type: 'null' - title: Disabled Reason + title: Corrections additionalProperties: true type: object required: - id - - client_id - kind - - client_name - - client_host + - status + - environment + - document_id + - inbox_item_id + - schema_id + - options + - pages_requested + - pages_processed + - pages_escalated + - document_pages + - confidence + - pages + - output + - models + - price_micro + - provider_cost_micro + - currency + - error_code + - created_by - created_at - - last_used_at - - disabled_at - - disabled_reason - title: Client - ClientList: + - started_at + - completed_at + title: Extraction + ExtractionCreate: properties: - items: - items: - $ref: '#/components/schemas/Client' - type: array - title: Items - next_cursor: + inbox_item_id: anyOf: - type: string + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Next Cursor - total: - type: integer - minimum: 0.0 - title: Total - additionalProperties: true - type: object - required: - - items - - total - title: ClientList - Correction: - properties: - id: - type: string - title: Id - extraction_id: - type: string - title: Extraction Id - field: - type: string - title: Field - value: - title: Value - note: + title: Inbox Item Id + document_id: anyOf: - type: string + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Note - created_by: - type: string - title: Created By - created_at: - type: string - title: Created At - additionalProperties: true - type: object - required: - - id - - extraction_id - - field - - value - - note - - created_by - - created_at - title: Correction - CorrectionCreate: - properties: - field: + title: Document Id + max_pages: anyOf: - - type: string - maxLength: 120 + - type: integer + maximum: 200.0 + minimum: 1.0 - type: 'null' - title: Field - value: - title: Value - note: + title: Max Pages + strict: + type: boolean + title: Strict + description: Refuse with page_limit_exceeded when the document has more pages than would be read, instead + of reading the first ones and warning. + default: false + schema: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Schema + description: A JSON Schema object of string, number, boolean or date fields with descriptions. + schema_id: anyOf: - type: string - maxLength: 1000 + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Note + title: Schema Id + strong_model_if_below: + type: number + maximum: 1.0 + minimum: 0.0 + title: Strong Model If Below + default: 0.75 additionalProperties: false type: object - title: CorrectionCreate - Coverage: + title: ExtractionCreate + ExtractionPage: properties: - coverage_version: - anyOf: - - type: string - - type: 'null' - title: Coverage Version - generated_at: + page: + type: integer + title: Page + text: + type: string + title: Text + confidence: + type: number + title: Confidence + language: anyOf: - type: string - type: 'null' - title: Generated At - orderable_now: + title: Language + status: + type: string + title: Status + model: + type: string + title: Model + escalated: + type: boolean + title: Escalated + default: false + warnings: items: type: string type: array - title: Orderable Now - outbound: - additionalProperties: true - type: object - title: Outbound - inbound: - additionalProperties: true - type: object - title: Inbound - excluded: - additionalProperties: true - type: object - title: Excluded - note: - anyOf: - - type: string - - type: 'null' - title: Note + title: Warnings + default: [] + fast_read: + type: boolean + description: Returned by GET /v1/extractions/{extraction_id}. Declared here until the public schema includes + it. + x-sdk-route: GET /v1/extractions/{extraction_id} + strong_read: + type: boolean + description: Returned by GET /v1/extractions/{extraction_id}. Declared here until the public schema includes + it. + x-sdk-route: GET /v1/extractions/{extraction_id} + cost_micro: + type: integer + description: Returned by GET /v1/extractions/{extraction_id}. Declared here until the public schema includes + it. + x-sdk-route: GET /v1/extractions/{extraction_id} + words_count: + type: integer + description: Returned by GET /v1/extractions/{extraction_id}. Declared here until the public schema includes + it. + x-sdk-route: GET /v1/extractions/{extraction_id} additionalProperties: true type: object required: - - coverage_version - - generated_at - - orderable_now - - outbound - - inbound - - excluded - - note - title: Coverage - Deleted: + - page + - text + - confidence + - status + - model + title: ExtractionPage + ExtractionPageList: properties: - id: - type: string - title: Id - deleted: - type: boolean - title: Deleted - default: true + items: + items: + $ref: '#/components/schemas/Extraction' + type: array + title: Items + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor additionalProperties: true type: object required: - - id - title: Deleted - Delivery: + - items + title: ExtractionPageList + ExtractionSchema: properties: id: type: string title: Id - webhook_id: - type: string - title: Webhook Id - event_id: - type: string - title: Event Id - event_type: + name: type: string - title: Event Type - attempt: + title: Name + version: type: integer - title: Attempt - status: - type: string - title: Status - response_status: - anyOf: - - type: integer - - type: 'null' - title: Response Status - error: - anyOf: - - type: string - - type: 'null' - title: Error - duration_ms: - anyOf: - - type: integer - - type: 'null' - title: Duration Ms - replay_of: - anyOf: - - type: string - - type: 'null' - title: Replay Of - schedule_s: - items: - type: integer - type: array - title: Schedule S - next_attempt_at: + title: Version + description: anyOf: - type: string - type: 'null' - title: Next Attempt At + title: Description + schema: + additionalProperties: true + type: object + title: Schema + status: + type: string + title: Status + created_by: + type: string + title: Created By created_at: type: string title: Created At - delivered_at: - anyOf: - - type: string - - type: 'null' - title: Delivered At additionalProperties: true type: object required: - id - - webhook_id - - event_id - - event_type - - attempt + - name + - version + - description + - schema - status - - response_status - - error - - duration_ms - - replay_of - - schedule_s - - next_attempt_at + - created_by - created_at - - delivered_at - title: Delivery - DeliveryPage: + title: ExtractionSchema + ExtractionSchemaList: properties: items: items: - $ref: '#/components/schemas/Delivery' + $ref: '#/components/schemas/ExtractionSchema' type: array title: Items - next_cursor: + additionalProperties: true + type: object + required: + - items + title: ExtractionSchemaList + FaxCreate: + properties: + quote_id: + type: string + title: Quote Id + client_reference: anyOf: - type: string + maxLength: 200 - type: 'null' - title: Next Cursor - additionalProperties: true + title: Client Reference + approval_id: + anyOf: + - type: string + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ + - type: 'null' + title: Approval Id + description: An approved approval request bound to this quote. Consumed by this one send. + additionalProperties: false type: object required: - - items - title: DeliveryPage - Document: + - quote_id + title: FaxCreate + description: |- + M9: an approved request authorizes the send; without one a quote that needs authorization is + evaluated against the caller's delegated policies. + FaxJob: properties: id: type: string @@ -11691,121 +9630,177 @@ components: - live - test title: Environment - status: - type: string - title: Status - source: - type: string - title: Source - filename: - type: string - title: Filename - content_type: - type: string - title: Content Type - size_bytes: - type: integer - title: Size Bytes - sha256: + direction: type: string - title: Sha256 - page_count: - type: integer - title: Page Count - render_status: + title: Direction + state: type: string - title: Render Status - render_reason: + enum: + - queued + - active + - partial + - failed + - unknown + - delivered + title: State + failure_code: anyOf: - type: string - type: 'null' - title: Render Reason - validation: - additionalProperties: true - type: object - title: Validation - upload_id: + title: Failure Code + to: + type: string + title: To + from: anyOf: - type: string - type: 'null' - title: Upload Id - created_at: + title: From + route: type: string - title: Created At - expires_at: + title: Route + document_id: + type: string + title: Document Id + document_sha256: + type: string + title: Document Sha256 + transmitted_sha256: anyOf: - type: string - type: 'null' - title: Expires At - deleted_at: + title: Transmitted Sha256 + quote_id: anyOf: - type: string - type: 'null' - title: Deleted At - additionalProperties: true - type: object - required: - - id - - environment - - status - - source - - filename - - content_type - - size_bytes - - sha256 - - page_count - - render_status - - render_reason - - validation - - upload_id - - created_at - - expires_at - - deleted_at - title: Document - DocumentCreate: - properties: - upload_id: + title: Quote Id + billable_pages: + type: integer + title: Billable Pages + cover_pages: + type: integer + title: Cover Pages + quality: + type: string + title: Quality + default: fine + sender_name: anyOf: - type: string - type: 'null' - title: Upload Id - text: + title: Sender Name + delete_after_send: + type: boolean + title: Delete After Send + default: false + pages_sent: + type: integer + title: Pages Sent + amount_micro: + type: integer + title: Amount Micro + captured_micro: + type: integer + title: Captured Micro + currency: + type: string + title: Currency + provider: + type: string + title: Provider + provider_ref: anyOf: - type: string - type: 'null' - title: Text - description: Plain text rendered to a letter PDF. - examples: - - Hello from Fax for Agents - markdown: + title: Provider Ref + client_reference: anyOf: - type: string - type: 'null' - title: Markdown - description: Markdown (headings, lists, emphasis, code) rendered to PDF. - html: + title: Client Reference + attempt_count: + type: integer + title: Attempt Count + created_at: + type: string + title: Created At + updated_at: + type: string + title: Updated At + completed_at: anyOf: - type: string - type: 'null' - title: Html - description: 'HTML rendered to PDF by a headless browser with scripts off and no network: inline CSS and - data: images print, external resources are counted as blocked. US letter unless @page says otherwise. - At most 2 MiB.' - filename: + title: Completed At + cancel_requested_at: anyOf: - type: string - maxLength: 255 - type: 'null' - title: Filename - additionalProperties: false + title: Cancel Requested At + evidence: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Evidence + description: The carrier's evidence once delivered or partial; null before. + one_time_order_id: + anyOf: + - type: string + - type: 'null' + title: One Time Order Id + description: The one-time order this fax was paid by; null for a wallet fax. + one_time: + anyOf: + - $ref: '#/components/schemas/OneTimeJob' + - type: 'null' + approval_id: + type: + - string + - 'null' + description: Returned by GET /v1/faxes/{fax_id}. Declared here until the public schema includes it. + x-sdk-route: GET /v1/faxes/{fax_id} + policy_version_id: + type: + - string + - 'null' + description: Returned by GET /v1/faxes/{fax_id}. Declared here until the public schema includes it. + x-sdk-route: GET /v1/faxes/{fax_id} + additionalProperties: true type: object - title: DocumentCreate - description: Send exactly one of text, markdown, html or upload_id. - DocumentPage: + required: + - id + - environment + - direction + - state + - failure_code + - to + - route + - document_id + - document_sha256 + - transmitted_sha256 + - quote_id + - billable_pages + - cover_pages + - pages_sent + - amount_micro + - captured_micro + - currency + - provider + - provider_ref + - client_reference + - attempt_count + - created_at + - updated_at + - completed_at + - cancel_requested_at + title: FaxJob + FaxJobPage: properties: items: items: - $ref: '#/components/schemas/Document' + $ref: '#/components/schemas/FaxJob' type: array title: Items next_cursor: @@ -11817,764 +9812,691 @@ components: type: object required: - items - title: DocumentPage - DocumentPages: + title: FaxJobPage + Grant: properties: - document_id: + id: type: string - title: Document Id - page_count: - type: integer - title: Page Count - render_status: + title: Id + org_id: type: string - title: Render Status - render_reason: + title: Org Id + organization: + type: string + title: Organization + user_id: + type: string + title: User Id + client_id: + type: string + title: Client Id + client_host: + type: string + title: Client Host + client_name: anyOf: - type: string - type: 'null' - title: Render Reason + title: Client Name + environment: + type: string + enum: + - test + - live + title: Environment + scopes: + items: + type: string + type: array + title: Scopes + created_at: + type: string + title: Created At + last_used_at: + anyOf: + - type: string + - type: 'null' + title: Last Used At + revoked_at: + anyOf: + - type: string + - type: 'null' + title: Revoked At + additionalProperties: true + type: object + required: + - id + - org_id + - organization + - user_id + - client_id + - client_host + - client_name + - environment + - scopes + - created_at + - last_used_at + - revoked_at + title: Grant + GrantList: + properties: items: items: - $ref: '#/components/schemas/PagePreview' + $ref: '#/components/schemas/Grant' type: array title: Items + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor additionalProperties: true type: object required: - - document_id - - page_count - - render_status - - render_reason - items - title: DocumentPages - DocumentValidation: + title: GrantList + InboxItem: properties: id: type: string title: Id - status: - type: string - title: Status - page_count: - type: integer - title: Page Count - render_status: - type: string - title: Render Status - render_reason: + from: anyOf: - type: string - type: 'null' - title: Render Reason - warnings: - items: - additionalProperties: true - type: object - type: array - title: Warnings - additionalProperties: true - type: object - required: - - id - - status - - page_count - - render_status - - render_reason - - warnings - title: DocumentValidation - EffectivePolicies: - properties: - actor: - type: string - title: Actor - environment: - type: string - enum: - - live - - test - title: Environment - under_policy: - type: boolean - title: Under Policy - approval_required_without_policy: - type: boolean - title: Approval Required Without Policy - requires_human_approval: - type: boolean - title: Requires Human Approval - description: 'Server-set for hosted integration clients and their keys: every send needs a person''s approval, - whatever the policies say.' - default: false - policies: - items: - $ref: '#/components/schemas/Policy' - type: array - title: Policies - rules_order: - items: - type: string - type: array - title: Rules Order - additionalProperties: true - type: object - required: - - actor - - environment - - under_policy - - approval_required_without_policy - - policies - - rules_order - title: EffectivePolicies - ErrorEnvelope: - title: ErrorEnvelope - type: object - required: - - error - properties: - error: - type: object - required: - - code - - message - - retryable - - correlation_id - properties: - code: - type: string - description: A stable code such as invalid_token, scope_missing, not_found, quote_expired, insufficient_balance, - approval_required, rate_limited, live_provider_unavailable, one_time_unavailable. - message: - type: string - description: One sentence a person can act on. - retryable: - type: boolean - correlation_id: - type: string - description: The X-Request-Id of the request. Quote it when you write to hello@faxforagents.com. - details: - type: object - additionalProperties: true - description: Code-specific fields, for example details.scope on scope_missing. - Event: - properties: - id: - type: string - title: Id - type: + title: From + to: type: string - title: Type - created_at: + title: To + pages: + type: integer + title: Pages + status: type: string - title: Created At - org_id: + title: Status + document_id: + anyOf: + - type: string + - type: 'null' + title: Document Id + received_at: type: string - title: Org Id + title: Received At + amount_micro: + type: integer + title: Amount Micro + default: 0 + note: + anyOf: + - type: string + - type: 'null' + title: Note environment: type: string enum: - live - test title: Environment + default: live + number_id: + anyOf: + - type: string + - type: 'null' + title: Number Id project_id: anyOf: - type: string - type: 'null' title: Project Id - resource_type: - type: string - title: Resource Type - resource_id: + partial_content: + type: boolean + title: Partial Content + default: false + media_status: type: string - title: Resource Id - fax_job_id: + title: Media Status + default: stored + duration_secs: anyOf: - - type: string + - type: integer - type: 'null' - title: Fax Job Id - schema_version: - type: integer - title: Schema Version - correlation_id: + title: Duration Secs + provider: + type: string + title: Provider + default: '' + read_at: anyOf: - type: string - type: 'null' - title: Correlation Id - data: - additionalProperties: true - type: object - title: Data - additionalProperties: true - type: object - required: - - id - - type - - created_at - - org_id - - environment - - project_id - - resource_type - - resource_id - - fax_job_id - - schema_version - - correlation_id - - data - title: Event - EventPage: - properties: - items: - items: - $ref: '#/components/schemas/Event' - type: array - title: Items - next_cursor: + title: Read At + expires_at: anyOf: - type: string - type: 'null' - title: Next Cursor + title: Expires At additionalProperties: true type: object required: - - items - title: EventPage - Extraction: + - id + - to + - pages + - status + - document_id + - received_at + title: InboxItem + InboxItemDetail: properties: id: type: string title: Id - kind: + from: + anyOf: + - type: string + - type: 'null' + title: From + to: type: string - enum: - - extract - - classify - - summarize - title: Kind + title: To + pages: + type: integer + title: Pages status: type: string - enum: - - pending - - queued - - running - - completed - - failed title: Status + document_id: + anyOf: + - type: string + - type: 'null' + title: Document Id + received_at: + type: string + title: Received At + amount_micro: + type: integer + title: Amount Micro + default: 0 + note: + anyOf: + - type: string + - type: 'null' + title: Note environment: type: string enum: - live - test title: Environment - document_id: - type: string - title: Document Id - inbox_item_id: + default: live + number_id: anyOf: - type: string - type: 'null' - title: Inbox Item Id - schema_id: + title: Number Id + project_id: anyOf: - type: string - type: 'null' - title: Schema Id - schema: + title: Project Id + partial_content: + type: boolean + title: Partial Content + default: false + media_status: + type: string + title: Media Status + default: stored + duration_secs: anyOf: - - additionalProperties: true - type: object + - type: integer - type: 'null' - title: Schema - options: - additionalProperties: true - type: object - title: Options - pages_requested: - type: integer - title: Pages Requested - pages_processed: - type: integer - title: Pages Processed - pages_escalated: - type: integer - title: Pages Escalated - document_pages: - type: integer - title: Document Pages - description: The document's page count. Above pages_processed on a completed row means the cap left pages - unread; output.truncated and a warning say so. - confidence: - anyOf: - - type: number - - type: 'null' - title: Confidence - pages: - items: - $ref: '#/components/schemas/ExtractionPage' - type: array - title: Pages - output: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Output - models: - additionalProperties: true - type: object - title: Models - price_micro: - type: integer - title: Price Micro - provider_cost_micro: - type: integer - title: Provider Cost Micro - currency: + title: Duration Secs + provider: type: string - title: Currency - error_code: + title: Provider + default: '' + read_at: anyOf: - type: string - type: 'null' - title: Error Code - created_by: - type: string - title: Created By - created_at: - type: string - title: Created At - started_at: + title: Read At + expires_at: anyOf: - type: string - type: 'null' - title: Started At - completed_at: + title: Expires At + document: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Document + text: anyOf: - type: string - type: 'null' - title: Completed At - corrections: + title: Text + extraction_id: anyOf: - - items: - additionalProperties: true - type: object - type: array + - type: string - type: 'null' - title: Corrections + title: Extraction Id additionalProperties: true type: object required: - id - - kind + - to + - pages - status - - environment - document_id - - inbox_item_id - - schema_id - - options - - pages_requested - - pages_processed - - pages_escalated - - document_pages - - confidence - - pages - - output - - models - - price_micro - - provider_cost_micro - - currency - - error_code - - created_by - - created_at - - started_at - - completed_at - title: Extraction - ExtractionCreate: + - received_at + title: InboxItemDetail + InboxItemSummary: properties: - inbox_item_id: + id: + type: string + title: Id + from: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Inbox Item Id + title: From + to: + type: string + title: To + pages: + type: integer + title: Pages + status: + type: string + title: Status document_id: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' title: Document Id - max_pages: + received_at: + type: string + title: Received At + amount_micro: + type: integer + title: Amount Micro + default: 0 + note: anyOf: - - type: integer - maximum: 200.0 - minimum: 1.0 + - type: string - type: 'null' - title: Max Pages - strict: + title: Note + environment: + type: string + enum: + - live + - test + title: Environment + description: Returned by POST /v1/sandbox/inbound-faxes. + x-sdk-route: POST /v1/sandbox/inbound-faxes + number_id: + anyOf: + - type: string + - type: 'null' + title: Number Id + description: Returned by POST /v1/sandbox/inbound-faxes. + x-sdk-route: POST /v1/sandbox/inbound-faxes + project_id: + anyOf: + - type: string + - type: 'null' + title: Project Id + description: Returned by POST /v1/sandbox/inbound-faxes. + x-sdk-route: POST /v1/sandbox/inbound-faxes + partial_content: type: boolean - title: Strict - description: Refuse with page_limit_exceeded when the document has more pages than would be read, instead - of reading the first ones and warning. - default: false - schema: + title: Partial Content + description: Returned by POST /v1/sandbox/inbound-faxes. + x-sdk-route: POST /v1/sandbox/inbound-faxes + media_status: + type: string + title: Media Status + description: Returned by POST /v1/sandbox/inbound-faxes. + x-sdk-route: POST /v1/sandbox/inbound-faxes + duration_secs: anyOf: - - additionalProperties: true - type: object + - type: integer - type: 'null' - title: Schema - description: A JSON Schema object of string, number, boolean or date fields with descriptions. - schema_id: + title: Duration Secs + description: Returned by POST /v1/sandbox/inbound-faxes. + x-sdk-route: POST /v1/sandbox/inbound-faxes + provider: + type: string + title: Provider + description: Returned by POST /v1/sandbox/inbound-faxes. + x-sdk-route: POST /v1/sandbox/inbound-faxes + read_at: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Schema Id - strong_model_if_below: - type: number - maximum: 1.0 - minimum: 0.0 - title: Strong Model If Below - default: 0.75 - additionalProperties: false + title: Read At + description: Returned by POST /v1/sandbox/inbound-faxes. + x-sdk-route: POST /v1/sandbox/inbound-faxes + expires_at: + anyOf: + - type: string + - type: 'null' + title: Expires At + description: Returned by POST /v1/sandbox/inbound-faxes. + x-sdk-route: POST /v1/sandbox/inbound-faxes + additionalProperties: true type: object - title: ExtractionCreate - ExtractionPage: + required: + - id + - to + - pages + - status + - document_id + - received_at + title: InboxItem + InboxPage: properties: - page: - type: integer - title: Page - text: - type: string - title: Text - confidence: - type: number - title: Confidence - language: + items: + items: + $ref: '#/components/schemas/InboxItem' + type: array + title: Items + next_cursor: anyOf: - type: string - type: 'null' - title: Language + title: Next Cursor + additionalProperties: true + type: object + required: + - items + title: InboxPage + InboxUpdate: + properties: status: + anyOf: + - type: string + enum: + - received + - read + - archived + - type: 'null' + title: Status + additionalProperties: false + type: object + title: InboxUpdate + Inventory: + properties: + country: type: string - title: Status - model: - type: string - title: Model - escalated: - type: boolean - title: Escalated - default: false - warnings: + title: Country + number_type: + type: string + title: Number Type + locality: + anyOf: + - type: string + - type: 'null' + title: Locality + items: items: - type: string + $ref: '#/components/schemas/InventoryNumber' type: array - title: Warnings - default: [] - fast_read: - type: boolean - description: Returned by GET /v1/extractions/{extraction_id}. Declared here until the public schema includes - it. - x-sdk-route: GET /v1/extractions/{extraction_id} - strong_read: - type: boolean - description: Returned by GET /v1/extractions/{extraction_id}. Declared here until the public schema includes - it. - x-sdk-route: GET /v1/extractions/{extraction_id} - cost_micro: - type: integer - description: Returned by GET /v1/extractions/{extraction_id}. Declared here until the public schema includes - it. - x-sdk-route: GET /v1/extractions/{extraction_id} - words_count: - type: integer - description: Returned by GET /v1/extractions/{extraction_id}. Declared here until the public schema includes - it. - x-sdk-route: GET /v1/extractions/{extraction_id} + title: Items + recurring_period: + type: string + title: Recurring Period + note: + type: string + title: Note additionalProperties: true type: object required: - - page - - text - - confidence - - status - - model - title: ExtractionPage - ExtractionPageList: + - country + - number_type + - locality + - items + - recurring_period + - note + title: Inventory + InventoryNumber: properties: - items: - items: - $ref: '#/components/schemas/Extraction' - type: array - title: Items - next_cursor: + e164: + type: string + title: E164 + country: + type: string + title: Country + number_type: + type: string + title: Number Type + locality: anyOf: - type: string - type: 'null' - title: Next Cursor + title: Locality + monthly_micro: + type: integer + title: Monthly Micro + currency: + type: string + title: Currency + setup_micro: + type: integer + title: Setup Micro additionalProperties: true type: object required: - - items - title: ExtractionPageList - ExtractionSchema: + - e164 + - country + - number_type + - locality + - monthly_micro + - currency + - setup_micro + title: InventoryNumber + Invitation: properties: id: type: string title: Id - name: + email: type: string - title: Name - version: - type: integer - title: Version - description: - anyOf: - - type: string - - type: 'null' - title: Description - schema: - additionalProperties: true - type: object - title: Schema - status: + title: Email + role: type: string - title: Status - created_by: + enum: + - owner + - admin + - member + - viewer + title: Role + invited_by: type: string - title: Created By + title: Invited By created_at: type: string title: Created At + expires_at: + type: string + title: Expires At + accepted_at: + anyOf: + - type: string + - type: 'null' + title: Accepted At additionalProperties: true type: object required: - id - - name - - version - - description - - schema - - status - - created_by + - email + - role + - invited_by - created_at - title: ExtractionSchema - ExtractionSchemaList: + - expires_at + - accepted_at + title: Invitation + InvitationCreate: + properties: + email: + type: string + format: email + title: Email + role: + type: string + enum: + - owner + - admin + - member + - viewer + title: Role + default: member + additionalProperties: false + type: object + required: + - email + title: InvitationCreate + InvitationList: properties: items: items: - $ref: '#/components/schemas/ExtractionSchema' + $ref: '#/components/schemas/Invitation' type: array title: Items additionalProperties: true type: object required: - items - title: ExtractionSchemaList - FaxCreate: + title: InvitationList + Invoice: properties: - quote_id: + id: type: string - title: Quote Id - client_reference: + title: Id + number: anyOf: - type: string - maxLength: 200 - type: 'null' - title: Client Reference - approval_id: + title: Number + status: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Approval Id - description: An approved approval request bound to this quote. Consumed by this one send. - additionalProperties: false - type: object - required: - - quote_id - title: FaxCreate - description: |- - M9: an approved request authorizes the send; without one a quote that needs authorization is - evaluated against the caller's delegated policies. - FaxJob: - properties: - id: - type: string - title: Id - environment: - type: string - enum: - - live - - test - title: Environment - direction: - type: string - title: Direction - state: + title: Status + currency: type: string - enum: - - queued - - active - - partial - - failed - - unknown - - delivered - title: State - failure_code: + title: Currency + amount_due_micro: + type: integer + title: Amount Due Micro + amount_paid_micro: + type: integer + title: Amount Paid Micro + subscription_id: anyOf: - type: string - type: 'null' - title: Failure Code - to: - type: string - title: To - from: - anyOf: + title: Subscription Id + hosted_invoice_url: + anyOf: - type: string - type: 'null' - title: From - route: - type: string - title: Route - document_id: - type: string - title: Document Id - document_sha256: - type: string - title: Document Sha256 - transmitted_sha256: + title: Hosted Invoice Url + invoice_pdf: anyOf: - type: string - type: 'null' - title: Transmitted Sha256 - quote_id: + title: Invoice Pdf + created_at: anyOf: - type: string - type: 'null' - title: Quote Id - billable_pages: - type: integer - title: Billable Pages - cover_pages: - type: integer - title: Cover Pages - quality: - type: string - title: Quality - default: fine - sender_name: + title: Created At + additionalProperties: true + type: object + required: + - id + - number + - status + - currency + - amount_due_micro + - amount_paid_micro + - subscription_id + - hosted_invoice_url + - invoice_pdf + - created_at + title: Invoice + InvoicePage: + properties: + items: + items: + $ref: '#/components/schemas/Invoice' + type: array + title: Items + next_cursor: anyOf: - type: string - type: 'null' - title: Sender Name - delete_after_send: - type: boolean - title: Delete After Send - default: false - pages_sent: - type: integer - title: Pages Sent - amount_micro: - type: integer - title: Amount Micro - captured_micro: - type: integer - title: Captured Micro - currency: + title: Next Cursor + additionalProperties: true + type: object + required: + - items + title: InvoicePage + LedgerEntry: + properties: + id: type: string - title: Currency - provider: + title: Id + txn_id: type: string - title: Provider - provider_ref: - anyOf: - - type: string - - type: 'null' - title: Provider Ref - client_reference: - anyOf: - - type: string - - type: 'null' - title: Client Reference - attempt_count: - type: integer - title: Attempt Count - created_at: + title: Txn Id + account: type: string - title: Created At - updated_at: + title: Account + amount_micro: + type: integer + title: Amount Micro + kind: type: string - title: Updated At - completed_at: + title: Kind + ref_type: anyOf: - type: string - type: 'null' - title: Completed At - cancel_requested_at: + title: Ref Type + ref_id: anyOf: - type: string - type: 'null' - title: Cancel Requested At - evidence: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Evidence - description: The carrier's evidence once delivered or partial; null before. - one_time_order_id: + title: Ref Id + memo: anyOf: - type: string - type: 'null' - title: One Time Order Id - description: The one-time order this fax was paid by; null for a wallet fax. - one_time: - anyOf: - - $ref: '#/components/schemas/OneTimeJob' - - type: 'null' - approval_id: - type: - - string - - 'null' - description: Returned by GET /v1/faxes/{fax_id}. Declared here until the public schema includes it. - x-sdk-route: GET /v1/faxes/{fax_id} - policy_version_id: - type: - - string - - 'null' - description: Returned by GET /v1/faxes/{fax_id}. Declared here until the public schema includes it. - x-sdk-route: GET /v1/faxes/{fax_id} + title: Memo + created_at: + type: string + title: Created At additionalProperties: true type: object required: - id - - environment - - direction - - state - - failure_code - - to - - route - - document_id - - document_sha256 - - transmitted_sha256 - - quote_id - - billable_pages - - cover_pages - - pages_sent + - txn_id + - account - amount_micro - - captured_micro - - currency - - provider - - provider_ref - - client_reference - - attempt_count + - kind + - ref_type + - ref_id + - memo - created_at - - updated_at - - completed_at - - cancel_requested_at - title: FaxJob - FaxJobPage: + title: LedgerEntry + LedgerPage: properties: items: items: - $ref: '#/components/schemas/FaxJob' + $ref: '#/components/schemas/LedgerEntry' type: array title: Items next_cursor: @@ -12586,4710 +10508,5113 @@ components: type: object required: - items - title: FaxJobPage - Grant: + title: LedgerPage + Me: properties: - id: - type: string - title: Id org_id: type: string title: Org Id - organization: - type: string - title: Organization - user_id: + project_id: type: string - title: User Id - client_id: + title: Project Id + key_id: type: string - title: Client Id - client_host: + title: Key Id + key_prefix: type: string - title: Client Host - client_name: - anyOf: - - type: string - - type: 'null' - title: Client Name + title: Key Prefix environment: type: string enum: - - test - live + - test title: Environment scopes: items: type: string type: array title: Scopes - created_at: + actor: type: string - title: Created At - last_used_at: - anyOf: - - type: string - - type: 'null' - title: Last Used At - revoked_at: - anyOf: - - type: string - - type: 'null' - title: Revoked At + title: Actor additionalProperties: true type: object required: - - id - org_id - - organization - - user_id - - client_id - - client_host - - client_name + - project_id + - key_id + - key_prefix - environment - scopes - - created_at - - last_used_at - - revoked_at - title: Grant - GrantList: + - actor + title: Me + Member: properties: - items: - items: - $ref: '#/components/schemas/Grant' - type: array - title: Items - next_cursor: + id: + type: string + title: Id + email: + type: string + title: Email + name: anyOf: - type: string - type: 'null' - title: Next Cursor + title: Name + role: + type: string + enum: + - owner + - admin + - member + - viewer + title: Role + user_id: + anyOf: + - type: string + - type: 'null' + title: User Id + created_at: + type: string + title: Created At additionalProperties: true type: object required: - - items - title: GrantList - HTTPValidationError: + - id + - email + - name + - role + - user_id + - created_at + title: Member + MemberList: properties: - detail: + items: items: - $ref: '#/components/schemas/ValidationError' + $ref: '#/components/schemas/Member' type: array - title: Detail + title: Items + additionalProperties: true type: object - title: HTTPValidationError - InboxItem: + required: + - items + title: MemberList + MemberPatch: + properties: + role: + anyOf: + - type: string + enum: + - owner + - admin + - member + - viewer + - type: 'null' + title: Role + description: Required. Optional in the schema so a foreign id is a 404 first. + additionalProperties: false + type: object + title: MemberPatch + Number: properties: id: type: string title: Id - from: + environment: + type: string + enum: + - live + - test + title: Environment + e164: + type: string + title: E164 + country: + type: string + title: Country + number_type: + type: string + title: Number Type + locality: anyOf: - type: string - type: 'null' - title: From - to: - type: string - title: To - pages: - type: integer - title: Pages + title: Locality status: type: string title: Status - document_id: + label: anyOf: - type: string - type: 'null' - title: Document Id - received_at: - type: string - title: Received At - amount_micro: - type: integer - title: Amount Micro - default: 0 - note: + title: Label + project_id: anyOf: - type: string - type: 'null' - title: Note - environment: - type: string - enum: - - live - - test - title: Environment - default: live - number_id: + title: Project Id + inbound_webhook_id: anyOf: - type: string - type: 'null' - title: Number Id - project_id: + title: Inbound Webhook Id + inbound_status: + type: string + title: Inbound Status + provider: + type: string + title: Provider + monthly_micro: + type: integer + title: Monthly Micro + currency: + type: string + title: Currency + order_id: anyOf: - type: string - type: 'null' - title: Project Id - partial_content: - type: boolean - title: Partial Content - default: false - media_status: + title: Order Id + created_at: type: string - title: Media Status - default: stored - duration_secs: + title: Created At + activated_at: anyOf: - - type: integer + - type: string - type: 'null' - title: Duration Secs - provider: - type: string - title: Provider - default: '' - read_at: + title: Activated At + renews_at: anyOf: - type: string - type: 'null' - title: Read At - expires_at: + title: Renews At + released_at: anyOf: - type: string - type: 'null' - title: Expires At + title: Released At additionalProperties: true type: object required: - id - - to - - pages + - environment + - e164 + - country + - number_type + - locality - status - - document_id - - received_at - title: InboxItem - InboxItemDetail: + - label + - project_id + - inbound_webhook_id + - inbound_status + - provider + - monthly_micro + - currency + - order_id + - created_at + - activated_at + - renews_at + - released_at + title: Number + NumberList: + properties: + items: + items: + $ref: '#/components/schemas/Number' + type: array + title: Items + additionalProperties: true + type: object + required: + - items + title: NumberList + NumberOrder: properties: id: type: string title: Id - from: - anyOf: - - type: string - - type: 'null' - title: From - to: + environment: type: string - title: To - pages: - type: integer - title: Pages + enum: + - live + - test + title: Environment status: type: string title: Status - document_id: + e164: anyOf: - type: string - type: 'null' - title: Document Id - received_at: - type: string - title: Received At - amount_micro: - type: integer - title: Amount Micro - default: 0 - note: + title: E164 + country: anyOf: - type: string - type: 'null' - title: Note - environment: - type: string - enum: - - live - - test - title: Environment - default: live - number_id: + title: Country + number_type: anyOf: - type: string - type: 'null' - title: Number Id - project_id: + title: Number Type + number_id: anyOf: - type: string - type: 'null' - title: Project Id - partial_content: - type: boolean - title: Partial Content - default: false - media_status: - type: string - title: Media Status - default: stored - duration_secs: + title: Number Id + number: anyOf: - - type: integer + - $ref: '#/components/schemas/Number' - type: 'null' - title: Duration Secs provider: type: string title: Provider - default: '' - read_at: - anyOf: - - type: string - - type: 'null' - title: Read At - expires_at: - anyOf: - - type: string - - type: 'null' - title: Expires At - document: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Document - text: + recurring_charge_micro: + type: integer + title: Recurring Charge Micro + description: Charged every month on the activation day. + recurring_period: + type: string + title: Recurring Period + first_month_hold_micro: + type: integer + title: First Month Hold Micro + description: Held now, captured when the number activates. + currency: + type: string + title: Currency + error: anyOf: - type: string - type: 'null' - title: Text - extraction_id: + title: Error + created_at: + type: string + title: Created At + completed_at: anyOf: - type: string - type: 'null' - title: Extraction Id + title: Completed At additionalProperties: true type: object required: - id - - to - - pages + - environment - status - - document_id - - received_at - title: InboxItemDetail - InboxItemSummary: + - e164 + - country + - number_type + - number_id + - number + - provider + - recurring_charge_micro + - recurring_period + - first_month_hold_micro + - currency + - error + - created_at + - completed_at + title: NumberOrder + NumberOrderCreate: properties: - id: + e164: type: string - title: Id - from: + title: E164 + description: A number from GET /v1/number-inventory, E.164. + label: anyOf: - type: string + maxLength: 120 - type: 'null' - title: From - to: - type: string - title: To - pages: - type: integer - title: Pages - status: - type: string - title: Status - document_id: + title: Label + project_id: anyOf: - type: string - type: 'null' - title: Document Id - received_at: - type: string - title: Received At - amount_micro: - type: integer - title: Amount Micro - default: 0 - note: + title: Project Id + description: Inbound faxes are filed under this project. + inbound_webhook_id: anyOf: - type: string - type: 'null' - title: Note - environment: - type: string - enum: - - live - - test - title: Environment - description: Returned by POST /v1/sandbox/inbound-faxes. - x-sdk-route: POST /v1/sandbox/inbound-faxes - number_id: + title: Inbound Webhook Id + description: 'The webhook that receives fax.received for this number (default: all).' + additionalProperties: false + type: object + required: + - e164 + title: NumberOrderCreate + NumberOrderList: + properties: + items: + items: + $ref: '#/components/schemas/NumberOrder' + type: array + title: Items + additionalProperties: true + type: object + required: + - items + title: NumberOrderList + NumberUpdate: + properties: + label: anyOf: - type: string + maxLength: 120 - type: 'null' - title: Number Id - description: Returned by POST /v1/sandbox/inbound-faxes. - x-sdk-route: POST /v1/sandbox/inbound-faxes + title: Label project_id: anyOf: - type: string - type: 'null' title: Project Id - description: Returned by POST /v1/sandbox/inbound-faxes. - x-sdk-route: POST /v1/sandbox/inbound-faxes - partial_content: - type: boolean - title: Partial Content - description: Returned by POST /v1/sandbox/inbound-faxes. - x-sdk-route: POST /v1/sandbox/inbound-faxes - media_status: - type: string - title: Media Status - description: Returned by POST /v1/sandbox/inbound-faxes. - x-sdk-route: POST /v1/sandbox/inbound-faxes - duration_secs: + inbound_webhook_id: anyOf: - - type: integer + - type: string - type: 'null' - title: Duration Secs - description: Returned by POST /v1/sandbox/inbound-faxes. - x-sdk-route: POST /v1/sandbox/inbound-faxes - provider: - type: string - title: Provider - description: Returned by POST /v1/sandbox/inbound-faxes. - x-sdk-route: POST /v1/sandbox/inbound-faxes - read_at: + title: Inbound Webhook Id + additionalProperties: false + type: object + title: NumberUpdate + OneTimeCard: + properties: + last4: anyOf: - type: string - type: 'null' - title: Read At - description: Returned by POST /v1/sandbox/inbound-faxes. - x-sdk-route: POST /v1/sandbox/inbound-faxes - expires_at: + title: Last4 + brand: anyOf: - type: string - type: 'null' - title: Expires At - description: Returned by POST /v1/sandbox/inbound-faxes. - x-sdk-route: POST /v1/sandbox/inbound-faxes + title: Brand additionalProperties: true type: object required: - - id - - to - - pages - - status - - document_id - - received_at - title: InboxItem - InboxPage: + - last4 + - brand + title: OneTimeCard + OneTimeCheckout: properties: - items: - items: - $ref: '#/components/schemas/InboxItem' - type: array - title: Items - next_cursor: - anyOf: - - type: string - - type: 'null' - title: Next Cursor + order_id: + type: string + title: Order Id + checkout_url: + type: string + title: Checkout Url + expires_at: + type: string + title: Expires At + amount_micro: + type: integer + title: Amount Micro + currency: + type: string + title: Currency additionalProperties: true type: object required: - - items - title: InboxPage - InboxUpdate: + - order_id + - checkout_url + - expires_at + - amount_micro + - currency + title: OneTimeCheckout + OneTimeConfig: properties: - status: + enabled: + type: boolean + title: Enabled + reason: anyOf: - type: string - enum: - - received - - read - - archived - type: 'null' - title: Status - additionalProperties: false - type: object - title: InboxUpdate - InsufficientBalance: - title: InsufficientBalance - description: The error envelope of 402 insufficient_balance, with its details written out. - type: object - required: - - error - properties: - error: + title: Reason + price_version: + type: string + title: Price Version + effective_from: + type: string + title: Effective From + currency: + type: string + title: Currency + routes: + additionalProperties: + $ref: '#/components/schemas/OneTimeRoute' type: object - required: - - code - - message - - retryable - - correlation_id - - details - properties: - code: - type: string - const: insufficient_balance - message: - type: string - retryable: - type: boolean - correlation_id: - type: string - details: - type: object - additionalProperties: true - required: - - available_micro - - needed_micro - properties: - available_micro: - type: integer - description: What the wallet holds that is not on hold. - needed_micro: - type: integer - description: What this fax holds. - top_up_url: - type: string - description: The dashboard page where a person adds funds to the wallet. A key cannot top up. - one_time_offer: - type: object - description: 'The card path for this exact send, present when it qualifies: the one-time product - is open, the key is live, the route is sold one fax at a time and the document is within the - page cap. Pass the quote to POST /v1/one-time-sends/from-quote. A pointer, never a promise: - the create runs every check again.' - required: - - amount_micro - - currency - - document_pages - - included_pages - - extra_page_micro - - max_document_pages - properties: - amount_micro: - type: integer - description: The one-time price of this document to this number. - currency: - type: string - document_pages: - type: integer - included_pages: - type: integer - extra_page_micro: - type: integer - max_document_pages: - type: integer - approval_id: - type: - - string - - 'null' - description: The approval that authorized this send. It authorizes the order of the same quote - too. - Inventory: - properties: - country: - type: string - title: Country - number_type: - type: string - title: Number Type - locality: - anyOf: - - type: string - - type: 'null' - title: Locality - items: + title: Routes + max_document_pages: + type: integer + title: Max Document Pages + max_upload_bytes: + type: integer + title: Max Upload Bytes + max_text_chars: + type: integer + title: Max Text Chars + formats: items: - $ref: '#/components/schemas/InventoryNumber' + type: string type: array - title: Items - recurring_period: - type: string - title: Recurring Period - note: - type: string - title: Note - additionalProperties: true - type: object - required: - - country - - number_type - - locality - - items - - recurring_period - - note - title: Inventory - InventoryNumber: - properties: - e164: + title: Formats + aup_version: type: string - title: E164 - country: + title: Aup Version + aup_url: type: string - title: Country - number_type: + title: Aup Url + terms_url: type: string - title: Number Type - locality: + title: Terms Url + queue: anyOf: - - type: string + - $ref: '#/components/schemas/OneTimeQueue' - type: 'null' - title: Locality - monthly_micro: - type: integer - title: Monthly Micro - currency: - type: string - title: Currency - setup_micro: - type: integer - title: Setup Micro + description: The wait a fax ordered now would face for a carrier line. Null when one-time sends are closed + here or the carrier has no line limit. additionalProperties: true type: object required: - - e164 - - country - - number_type - - locality - - monthly_micro + - enabled + - price_version + - effective_from - currency - - setup_micro - title: InventoryNumber - Invitation: + - routes + - max_document_pages + - max_upload_bytes + - max_text_chars + - formats + - aup_version + - aup_url + - terms_url + title: OneTimeConfig + description: |- + What the public send page and an agent read before an order: whether the product is open here, the + card the order will be priced from (present only while open), the document limits and the policy the + sender accepts. Prices are integer micro-USD; the dollar figure is the client's to format. + OneTimeConfirm: properties: - id: + token: type: string - title: Id - email: + maxLength: 128 + minLength: 1 + title: Token + description: The token of the link in the confirmation mail. + additionalProperties: false + type: object + required: + - token + title: OneTimeConfirm + OneTimeConfirmSummary: + properties: + order_id: type: string - title: Email - role: + title: Order Id + state: type: string enum: - - owner - - admin - - member - - viewer - title: Role - invited_by: + - ok + - link_used + - link_expired + title: State + status: type: string - title: Invited By - created_at: + enum: + - draft + - checkout_open + - authorized + - awaiting_confirmation + - released + - capturing + - canceling + - captured + - released_hold + - expired + - refused + - settle_failed + title: Status + to: type: string - title: Created At - expires_at: + title: To + sender_name: type: string - title: Expires At - accepted_at: + title: Sender Name + email: + type: string + title: Email + document_pages: + type: integer + title: Document Pages + amount_micro: + type: integer + title: Amount Micro + currency: + type: string + title: Currency + confirm_deadline_at: anyOf: - type: string - type: 'null' - title: Accepted At + title: Confirm Deadline At additionalProperties: true type: object required: - - id + - order_id + - state + - status + - to + - sender_name - email - - role - - invited_by - - created_at - - expires_at - - accepted_at - title: Invitation - InvitationCreate: + - document_pages + - amount_micro + - currency + - confirm_deadline_at + title: OneTimeConfirmSummary + description: |- + What the confirm page shows before the click. ``state`` is ``ok`` while the link can still be used, + else ``link_used`` or ``link_expired``. Reading it consumes nothing. + OneTimeConfirmed: properties: - email: - type: string - format: email - title: Email - role: - type: string - enum: - - owner - - admin - - member - - viewer - title: Role - default: member - additionalProperties: false - type: object - required: - - email - title: InvitationCreate - InvitationList: - properties: - items: - items: - $ref: '#/components/schemas/Invitation' - type: array - title: Items + order: + $ref: '#/components/schemas/OneTimeOrder' + signed_in: + type: boolean + title: Signed In + me: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Me additionalProperties: true type: object required: - - items - title: InvitationList - Invoice: + - order + - signed_in + title: OneTimeConfirmed + description: |- + ``signed_in`` says whether this browser now holds a session for the payer; ``me`` is then the same + object ``GET /v1/auth/me`` answers (the CSRF token included). + OneTimeFromQuote: properties: - id: + quote_id: type: string - title: Id - number: - anyOf: - - type: string - - type: 'null' - title: Number - status: - anyOf: - - type: string - - type: 'null' - title: Status - currency: + title: Quote Id + sender_name: type: string - title: Currency - amount_due_micro: - type: integer - title: Amount Due Micro - amount_paid_micro: - type: integer - title: Amount Paid Micro - subscription_id: + maxLength: 200 + title: Sender Name + description: Printed on the cover sheet. 2 to 120 characters. + accept_aup: + type: boolean + title: Accept Aup + description: 'A session sends true: the signed-in person accepts the acceptable use policy and the terms. + A key''s value is not recorded: the person who pays accepts on the order''s page.' + default: false + email: anyOf: - type: string + maxLength: 254 - type: 'null' - title: Subscription Id - hosted_invoice_url: + title: Email + approval_id: anyOf: - type: string + maxLength: 64 - type: 'null' - title: Hosted Invoice Url - invoice_pdf: + title: Approval Id + description: An approved, unused approval request for this quote (POST /v1/approval-requests). A key needs + it unless a delegated policy allows the send. A session needs none. + source_ref: anyOf: - type: string + maxLength: 32 - type: 'null' - title: Invoice Pdf - created_at: + title: Source Ref + delete_after_send: anyOf: - - type: string + - type: boolean - type: 'null' - title: Created At - additionalProperties: true + title: Delete After Send + description: Delete the document and the transmitted copy the moment the fax ends in delivered, partial + or failed. The order, the receipt and the carrier evidence stay; they hold no document content. A fax + that ends unknown keeps the document until the carrier reports, or until the retention period ends. + Left out, the quote's own delete_after_send applies. + additionalProperties: false type: object required: - - id - - number - - status - - currency - - amount_due_micro - - amount_paid_micro - - subscription_id - - hosted_invoice_url - - invoice_pdf - - created_at - title: Invoice - InvoicePage: + - quote_id + - sender_name + title: OneTimeFromQuote + OneTimeJob: properties: - items: - items: - $ref: '#/components/schemas/Invoice' - type: array - title: Items - next_cursor: + order_id: + type: string + title: Order Id + status: anyOf: - type: string + enum: + - draft + - checkout_open + - authorized + - awaiting_confirmation + - released + - capturing + - canceling + - captured + - released_hold + - expired + - refused + - settle_failed - type: 'null' - title: Next Cursor - additionalProperties: true - type: object - required: - - items - title: InvoicePage - LedgerEntry: - properties: - id: - type: string - title: Id - txn_id: - type: string - title: Txn Id - account: - type: string - title: Account + title: Status amount_micro: - type: integer + anyOf: + - type: integer + - type: 'null' title: Amount Micro - kind: - type: string - title: Kind - ref_type: + captured_micro: anyOf: - - type: string + - type: integer - type: 'null' - title: Ref Type - ref_id: + title: Captured Micro + refunded_micro: anyOf: - - type: string + - type: integer - type: 'null' - title: Ref Id - memo: + title: Refunded Micro + description: What was refunded to the card after the charge, in micro-units. + document_pages: anyOf: - - type: string + - type: integer - type: 'null' - title: Memo - created_at: - type: string - title: Created At - additionalProperties: true - type: object - required: - - id - - txn_id - - account - - amount_micro - - kind - - ref_type - - ref_id - - memo - - created_at - title: LedgerEntry - LedgerPage: - properties: - items: - items: - $ref: '#/components/schemas/LedgerEntry' - type: array - title: Items - next_cursor: + title: Document Pages + description: The pages of the order's document. The cover sheet is not counted. + card: anyOf: - - type: string + - $ref: '#/components/schemas/OneTimeCard' - type: 'null' - title: Next Cursor additionalProperties: true type: object required: - - items - title: LedgerPage - MagicLinkRequest: + - order_id + title: OneTimeJob + description: 'The order behind a fax job that a one-time send made: what was authorized, what was charged.' + OneTimeOrder: properties: - email: + id: type: string - format: email - title: Email + title: Id + status: + type: string + enum: + - draft + - checkout_open + - authorized + - awaiting_confirmation + - released + - capturing + - canceling + - captured + - released_hold + - expired + - refused + - settle_failed + title: Status next: - anyOf: - - type: string - maxLength: 400 - - type: 'null' + type: string + enum: + - checkout + - confirm + - wait + - done title: Next - description: An in-app path to open after sign-in. - additionalProperties: false - type: object - required: - - email - title: MagicLinkRequest - Me: - properties: - org_id: - type: string - title: Org Id - project_id: - type: string - title: Project Id - key_id: - type: string - title: Key Id - key_prefix: - type: string - title: Key Prefix - environment: + environment: type: string enum: - live - test title: Environment - scopes: - items: - type: string - type: array - title: Scopes - actor: - type: string - title: Actor - additionalProperties: true - type: object - required: - - org_id - - project_id - - key_id - - key_prefix - - environment - - scopes - - actor - title: Me - Member: - properties: - id: + source: type: string - title: Id + enum: + - web + - api + - mcp + title: Source email: type: string title: Email - name: + email_verified: + type: boolean + title: Email Verified + sender_name: + type: string + title: Sender Name + to: + type: string + title: To + route: + type: string + title: Route + cover: anyOf: - - type: string + - additionalProperties: true + type: object - type: 'null' - title: Name - role: + title: Cover + document_pages: + type: integer + title: Document Pages + document_sha256: type: string - enum: - - owner - - admin - - member - - viewer - title: Role - user_id: + title: Document Sha256 + document_id: anyOf: - type: string - type: 'null' - title: User Id - created_at: - type: string - title: Created At - additionalProperties: true - type: object - required: - - id - - email - - name - - role - - user_id - - created_at - title: Member - MemberList: - properties: - items: - items: - $ref: '#/components/schemas/Member' - type: array - title: Items - additionalProperties: true - type: object - required: - - items - title: MemberList - MemberPatch: - properties: - role: + title: Document Id + delete_after_send: + type: boolean + title: Delete After Send + description: The sender asked for the document and the transmitted copy to be deleted the moment the fax + ends in delivered, partial or failed. + default: false + document_deleted: + type: boolean + title: Document Deleted + description: 'True once no copy of the document is held: it was deleted after the send, by the retention + period or by its owner, or the order ended before it was released and the uploaded file was removed. + The order, the fax and the carrier evidence stay; they hold no document content.' + default: false + document_expires_at: anyOf: - type: string - enum: - - owner - - admin - - member - - viewer - type: 'null' - title: Role - description: Required. Optional in the schema so a foreign id is a 404 first. - additionalProperties: false - type: object - title: MemberPatch - Number: - properties: - id: - type: string - title: Id - environment: - type: string - enum: - - live - - test - title: Environment - e164: - type: string - title: E164 - country: - type: string - title: Country - number_type: - type: string - title: Number Type - locality: + title: Document Expires At + description: When the retention period deletes the stored document. Null before the release and once the + document is deleted. + price: + $ref: '#/components/schemas/OneTimePrice' + amount_micro: + type: integer + title: Amount Micro + captured_micro: + type: integer + title: Captured Micro + refunded_micro: + type: integer + title: Refunded Micro + description: What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero + when nothing was refunded. captured_micro stays what was charged. + default: 0 + card: + anyOf: + - $ref: '#/components/schemas/OneTimeCard' + - type: 'null' + checkout_url: anyOf: - type: string - type: 'null' - title: Locality - status: - type: string - title: Status - label: + title: Checkout Url + checkout_expires_at: anyOf: - type: string - type: 'null' - title: Label - project_id: + title: Checkout Expires At + authorized_at: anyOf: - type: string - type: 'null' - title: Project Id - inbound_webhook_id: + title: Authorized At + confirm_deadline_at: anyOf: - type: string - type: 'null' - title: Inbound Webhook Id - inbound_status: - type: string - title: Inbound Status - provider: - type: string - title: Provider - monthly_micro: - type: integer - title: Monthly Micro - currency: - type: string - title: Currency - order_id: + title: Confirm Deadline At + capture_deadline_at: anyOf: - type: string - type: 'null' - title: Order Id - created_at: - type: string - title: Created At - activated_at: + title: Capture Deadline At + confirm_mail_sent_at: anyOf: - type: string - type: 'null' - title: Activated At - renews_at: + title: Confirm Mail Sent At + resend_allowed_at: anyOf: - type: string - type: 'null' - title: Renews At + title: Resend Allowed At + description: When the confirmation mail may be asked for again; null when it may not. + queue: + anyOf: + - $ref: '#/components/schemas/OneTimeQueue' + - type: 'null' + description: The wait for a carrier line while the order has not ended and its fax is not on a line yet. + Null for an ended order, a fax that is sending, and a test order. released_at: anyOf: - type: string - type: 'null' title: Released At - additionalProperties: true - type: object - required: - - id - - environment - - e164 - - country - - number_type - - locality - - status - - label - - project_id - - inbound_webhook_id - - inbound_status - - provider - - monthly_micro - - currency - - order_id - - created_at - - activated_at - - renews_at - - released_at - title: Number - NumberList: - properties: - items: - items: - $ref: '#/components/schemas/Number' - type: array - title: Items - additionalProperties: true - type: object - required: - - items - title: NumberList - NumberOrder: - properties: - id: - type: string - title: Id - environment: - type: string - enum: - - live - - test - title: Environment - status: - type: string - title: Status - e164: + settled_at: anyOf: - type: string - type: 'null' - title: E164 - country: + title: Settled At + quote_id: anyOf: - type: string - type: 'null' - title: Country - number_type: + title: Quote Id + fax_job_id: anyOf: - type: string - type: 'null' - title: Number Type - number_id: + title: Fax Job Id + failure_code: anyOf: - type: string - type: 'null' - title: Number Id - number: - anyOf: - - $ref: '#/components/schemas/Number' - - type: 'null' - provider: - type: string - title: Provider - recurring_charge_micro: - type: integer - title: Recurring Charge Micro - description: Charged every month on the activation day. - recurring_period: - type: string - title: Recurring Period - first_month_hold_micro: - type: integer - title: First Month Hold Micro - description: Held now, captured when the number activates. - currency: + title: Failure Code + aup_version: type: string - title: Currency - error: + title: Aup Version + aup_accepted: + type: boolean + title: Aup Accepted + description: Whether a person accepted the acceptable use policy and the terms for this order. False for + an order a key created until the payer accepts on the order's page; the checkout needs it. + default: true + status_url: anyOf: - type: string - type: 'null' - title: Error + title: Status Url + description: The order's page for the person who pays or confirms, with a fresh status token. Present + on a read by a key or session of the order's organization while the order is not done. + warnings: + items: + additionalProperties: true + type: object + type: array + title: Warnings + fax: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Fax + description: The fax job (the FaxJob shape) once the order was released; null before. created_at: type: string title: Created At - completed_at: - anyOf: - - type: string - - type: 'null' - title: Completed At + updated_at: + type: string + title: Updated At additionalProperties: true type: object required: - id - - environment - status - - e164 - - country - - number_type - - number_id - - number - - provider - - recurring_charge_micro - - recurring_period - - first_month_hold_micro - - currency - - error + - next + - environment + - source + - email + - email_verified + - sender_name + - to + - route + - cover + - document_pages + - document_sha256 + - document_id + - price + - amount_micro + - captured_micro + - card + - checkout_url + - checkout_expires_at + - authorized_at + - confirm_deadline_at + - capture_deadline_at + - confirm_mail_sent_at + - released_at + - settled_at + - quote_id + - fax_job_id + - failure_code + - aup_version - created_at - - completed_at - title: NumberOrder - NumberOrderCreate: + - updated_at + title: OneTimeOrder + description: |- + One order of the one-time send. ``next`` is what the caller does now: ``checkout`` (open the + payment), ``confirm`` (the payer clicks the link in the mail), ``wait`` (nothing to do; read again) or + ``done``. Money is integer micro-USD. ``captured_micro`` is what the card was charged, written only + once the payment provider confirmed it. ``fax`` is the fax job once the order was released, with the + carrier's evidence once it has any. + OneTimeOrderCreated: properties: - e164: + id: type: string - title: E164 - description: A number from GET /v1/number-inventory, E.164. - label: + title: Id + status: + type: string + enum: + - draft + - checkout_open + - authorized + - awaiting_confirmation + - released + - capturing + - canceling + - captured + - released_hold + - expired + - refused + - settle_failed + title: Status + next: + type: string + enum: + - checkout + - confirm + - wait + - done + title: Next + environment: + type: string + enum: + - live + - test + title: Environment + source: + type: string + enum: + - web + - api + - mcp + title: Source + email: + type: string + title: Email + email_verified: + type: boolean + title: Email Verified + sender_name: + type: string + title: Sender Name + to: + type: string + title: To + route: + type: string + title: Route + cover: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Cover + document_pages: + type: integer + title: Document Pages + document_sha256: + type: string + title: Document Sha256 + document_id: anyOf: - type: string - maxLength: 120 - type: 'null' - title: Label - project_id: + title: Document Id + delete_after_send: + type: boolean + title: Delete After Send + description: The sender asked for the document and the transmitted copy to be deleted the moment the fax + ends in delivered, partial or failed. + default: false + document_deleted: + type: boolean + title: Document Deleted + description: 'True once no copy of the document is held: it was deleted after the send, by the retention + period or by its owner, or the order ended before it was released and the uploaded file was removed. + The order, the fax and the carrier evidence stay; they hold no document content.' + default: false + document_expires_at: anyOf: - type: string - type: 'null' - title: Project Id - description: Inbound faxes are filed under this project. - inbound_webhook_id: + title: Document Expires At + description: When the retention period deletes the stored document. Null before the release and once the + document is deleted. + price: + $ref: '#/components/schemas/OneTimePrice' + amount_micro: + type: integer + title: Amount Micro + captured_micro: + type: integer + title: Captured Micro + refunded_micro: + type: integer + title: Refunded Micro + description: What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero + when nothing was refunded. captured_micro stays what was charged. + default: 0 + card: + anyOf: + - $ref: '#/components/schemas/OneTimeCard' + - type: 'null' + checkout_url: anyOf: - type: string - type: 'null' - title: Inbound Webhook Id - description: 'The webhook that receives fax.received for this number (default: all).' - additionalProperties: false - type: object - required: - - e164 - title: NumberOrderCreate - NumberOrderList: - properties: - items: - items: - $ref: '#/components/schemas/NumberOrder' - type: array - title: Items - additionalProperties: true - type: object - required: - - items - title: NumberOrderList - NumberUpdate: - properties: - label: + title: Checkout Url + checkout_expires_at: anyOf: - type: string - maxLength: 120 - type: 'null' - title: Label - project_id: + title: Checkout Expires At + authorized_at: anyOf: - type: string - type: 'null' - title: Project Id - inbound_webhook_id: + title: Authorized At + confirm_deadline_at: anyOf: - type: string - type: 'null' - title: Inbound Webhook Id - additionalProperties: false - type: object - title: NumberUpdate - OAuthConsent: - properties: - id: + title: Confirm Deadline At + capture_deadline_at: + anyOf: + - type: string + - type: 'null' + title: Capture Deadline At + confirm_mail_sent_at: + anyOf: + - type: string + - type: 'null' + title: Confirm Mail Sent At + resend_allowed_at: + anyOf: + - type: string + - type: 'null' + title: Resend Allowed At + description: When the confirmation mail may be asked for again; null when it may not. + queue: + anyOf: + - $ref: '#/components/schemas/OneTimeQueue' + - type: 'null' + description: The wait for a carrier line while the order has not ended and its fax is not on a line yet. + Null for an ended order, a fax that is sending, and a test order. + released_at: + anyOf: + - type: string + - type: 'null' + title: Released At + settled_at: + anyOf: + - type: string + - type: 'null' + title: Settled At + quote_id: + anyOf: + - type: string + - type: 'null' + title: Quote Id + fax_job_id: + anyOf: + - type: string + - type: 'null' + title: Fax Job Id + failure_code: + anyOf: + - type: string + - type: 'null' + title: Failure Code + aup_version: type: string - title: Id - client: - $ref: '#/components/schemas/OAuthConsentClient' - redirect_host: + title: Aup Version + aup_accepted: + type: boolean + title: Aup Accepted + description: Whether a person accepted the acceptable use policy and the terms for this order. False for + an order a key created until the payer accepts on the order's page; the checkout needs it. + default: true + status_url: type: string - title: Redirect Host - scopes_requested: - items: - type: string - type: array - title: Scopes Requested - organizations: + title: Status Url + warnings: items: - $ref: '#/components/schemas/OAuthConsentOrganization' + additionalProperties: true + type: object type: array - title: Organizations - default_environment: + title: Warnings + fax: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Fax + description: The fax job (the FaxJob shape) once the order was released; null before. + created_at: type: string - enum: - - live - - test - title: Default Environment - expires_at: + title: Created At + updated_at: type: string - title: Expires At + title: Updated At + status_token: + type: string + title: Status Token additionalProperties: true type: object required: - id - - client - - redirect_host - - scopes_requested - - organizations - - default_environment - - expires_at - title: OAuthConsent - OAuthConsentClient: + - status + - next + - environment + - source + - email + - email_verified + - sender_name + - to + - route + - cover + - document_pages + - document_sha256 + - document_id + - price + - amount_micro + - captured_micro + - card + - checkout_url + - checkout_expires_at + - authorized_at + - confirm_deadline_at + - capture_deadline_at + - confirm_mail_sent_at + - released_at + - settled_at + - quote_id + - fax_job_id + - failure_code + - aup_version + - status_url + - created_at + - updated_at + - status_token + title: OneTimeOrderCreated + description: |- + The create answer: the order plus the status token. The token reads this one order, opens its + checkout and asks for the confirmation mail again, with no key and no session, for seven days. Send it + as ``X-FFA-Order-Token`` (or ``?t=``). ``status_url`` is the order's page in the app with the token. + OneTimeOrderPage: properties: - name: + items: + items: + $ref: '#/components/schemas/OneTimeOrder' + type: array + title: Items + next_cursor: anyOf: - type: string - type: 'null' - title: Name - description: The client's own name, shown as text beside the host. - host: - type: string - title: Host - description: 'The host the person is sending a credential to: the trust anchor.' - loopback: - type: boolean - title: Loopback - description: The redirect goes to the person's own computer (an app they started). - first_seen: - type: boolean - title: First Seen - description: This client was registered during this request. + title: Next Cursor additionalProperties: true type: object required: - - name - - host - - loopback - - first_seen - title: OAuthConsentClient - OAuthConsentDecision: - properties: - org_id: - type: string - maxLength: 64 - minLength: 1 - title: Org Id - environment: - type: string - enum: - - live - - test - title: Environment - default: test - additionalProperties: false - type: object - required: - - org_id - title: OAuthConsentDecision - OAuthConsentOrganization: + - items + title: OneTimeOrderPage + OneTimePrice: properties: - id: - type: string - title: Id - name: + price_version: type: string - title: Name - role: + title: Price Version + currency: type: string - title: Role - scopes: - items: - type: string - type: array - title: Scopes - description: What the grant would carry for this organization and role. + title: Currency + flat_micro: + type: integer + title: Flat Micro + included_pages: + type: integer + title: Included Pages + extra_page_micro: + type: integer + title: Extra Page Micro + cover_included: + type: boolean + title: Cover Included additionalProperties: true type: object required: - - id - - name - - role - - scopes - title: OAuthConsentOrganization - OAuthRedirect: + - price_version + - currency + - flat_micro + - included_pages + - extra_page_micro + - cover_included + title: OneTimePrice + OneTimeQueue: properties: - redirect_to: + queued: + type: boolean + title: Queued + jobs_ahead: + type: integer + title: Jobs Ahead + estimated_wait_minutes: + type: integer + title: Estimated Wait Minutes + additionalProperties: true + type: object + required: + - queued + - jobs_ahead + - estimated_wait_minutes + title: OneTimeQueue + description: |- + The wait for a carrier line. ``queued`` is true when a fax sent now, or this order's waiting fax, + is estimated to wait more than ten minutes for a line: the order is kept and sent in turn, never + dropped. The minutes are an estimate from the number of faxes ahead and the carrier's line count. + OneTimeRoute: + properties: + label: type: string - title: Redirect To - description: 'Where the browser goes next: the client''s registered redirect URI.' + title: Label + flat_micro: + type: integer + title: Flat Micro + included_pages: + type: integer + title: Included Pages + extra_page_micro: + type: integer + title: Extra Page Micro + cover_included: + type: boolean + title: Cover Included additionalProperties: true type: object required: - - redirect_to - title: OAuthRedirect - OneTimeCard: + - label + - flat_micro + - included_pages + - extra_page_micro + - cover_included + title: OneTimeRoute + Organization: properties: - last4: - anyOf: - - type: string - - type: 'null' - title: Last4 - brand: + id: + type: string + title: Id + name: + type: string + title: Name + role: anyOf: - type: string + enum: + - owner + - admin + - member + - viewer - type: 'null' - title: Brand + title: Role + created_at: + type: string + title: Created At + members: + type: integer + title: Members additionalProperties: true type: object required: - - last4 - - brand - title: OneTimeCard - OneTimeCheckout: + - id + - name + - role + - created_at + - members + title: Organization + OrganizationList: properties: - order_id: + items: + items: + $ref: '#/components/schemas/OrganizationSummary' + type: array + title: Items + additionalProperties: true + type: object + required: + - items + title: OrganizationList + OrganizationPatch: + properties: + name: type: string - title: Order Id - checkout_url: + maxLength: 200 + minLength: 1 + title: Name + additionalProperties: false + type: object + required: + - name + title: OrganizationPatch + OrganizationSummary: + properties: + id: type: string - title: Checkout Url - expires_at: + title: Id + name: type: string - title: Expires At - amount_micro: + title: Name + role: + type: string + enum: + - owner + - admin + - member + - viewer + title: Role + additionalProperties: true + type: object + required: + - id + - name + - role + title: OrganizationSummary + PagePreview: + properties: + page_number: type: integer - title: Amount Micro - currency: + title: Page Number + width_px: + anyOf: + - type: integer + - type: 'null' + title: Width Px + height_px: + anyOf: + - type: integer + - type: 'null' + title: Height Px + url: type: string - title: Currency + title: Url additionalProperties: true type: object required: - - order_id - - checkout_url - - expires_at - - amount_micro - - currency - title: OneTimeCheckout - OneTimeConfig: + - page_number + - width_px + - height_px + - url + title: PagePreview + Policy: properties: + id: + type: string + title: Id + name: + type: string + title: Name + purpose: + anyOf: + - type: string + - type: 'null' + title: Purpose enabled: type: boolean title: Enabled - reason: + version: + type: integer + title: Version + current_version_id: anyOf: - type: string - type: 'null' - title: Reason - price_version: - type: string - title: Price Version - effective_from: - type: string - title: Effective From - currency: - type: string - title: Currency - routes: - additionalProperties: - $ref: '#/components/schemas/OneTimeRoute' + title: Current Version Id + rules: + additionalProperties: true type: object - title: Routes - max_document_pages: - type: integer - title: Max Document Pages - max_upload_bytes: - type: integer - title: Max Upload Bytes - max_text_chars: - type: integer - title: Max Text Chars - formats: - items: - type: string - type: array - title: Formats - aup_version: + title: Rules + managed: + anyOf: + - type: string + - type: 'null' + title: Managed + description: connected_apps when a Settings switch (the auto-send setting) manages this policy. Such a + policy is read here and changed only through PUT /v1/organizations/current/auto-send. + created_by: type: string - title: Aup Version - aup_url: + title: Created By + created_at: type: string - title: Aup Url - terms_url: + title: Created At + updated_at: type: string - title: Terms Url - queue: - anyOf: - - $ref: '#/components/schemas/OneTimeQueue' - - type: 'null' - description: The wait a fax ordered now would face for a carrier line. Null when one-time sends are closed - here or the carrier has no line limit. + title: Updated At additionalProperties: true type: object required: - - enabled - - price_version - - effective_from - - currency - - routes - - max_document_pages - - max_upload_bytes - - max_text_chars - - formats - - aup_version - - aup_url - - terms_url - title: OneTimeConfig - description: |- - What the public send page and an agent read before an order: whether the product is open here, the - card the order will be priced from (present only while open), the document limits and the policy the - sender accepts. Prices are integer micro-USD; the dollar figure is the client's to format. - OneTimeConfirm: + - id + - name + - purpose + - enabled + - version + - current_version_id + - rules + - created_by + - created_at + - updated_at + title: Policy + PolicyCreate: properties: - token: + name: type: string - maxLength: 128 + maxLength: 120 minLength: 1 - title: Token - description: The token of the link in the confirmation mail. + title: Name + purpose: + anyOf: + - type: string + maxLength: 500 + - type: 'null' + title: Purpose + description: Why this policy exists. Shown, never evaluated. + rules: + additionalProperties: true + type: object + title: Rules + description: See the PolicyRules schema in docs/APPROVALS.md. + enabled: + type: boolean + title: Enabled + default: true additionalProperties: false type: object required: - - token - title: OneTimeConfirm - OneTimeConfirmSummary: + - name + - rules + title: PolicyCreate + PolicyEvaluation: properties: - order_id: - type: string - title: Order Id - state: - type: string - enum: - - ok - - link_used - - link_expired - title: State - status: - type: string - enum: - - draft - - checkout_open - - authorized - - awaiting_confirmation - - released - - capturing - - canceling - - captured - - released_hold - - expired - - refused - - settle_failed - title: Status - to: - type: string - title: To - sender_name: - type: string - title: Sender Name - email: + decision: type: string - title: Email - document_pages: - type: integer - title: Document Pages - amount_micro: - type: integer - title: Amount Micro - currency: + title: Decision + rule: + anyOf: + - type: string + - type: 'null' + title: Rule + reason: type: string - title: Currency - confirm_deadline_at: + title: Reason + policy_id: anyOf: - type: string - type: 'null' - title: Confirm Deadline At - additionalProperties: true - type: object - required: - - order_id - - state - - status - - to - - sender_name - - email - - document_pages - - amount_micro - - currency - - confirm_deadline_at - title: OneTimeConfirmSummary - description: |- - What the confirm page shows before the click. ``state`` is ``ok`` while the link can still be used, - else ``link_used`` or ``link_expired``. Reading it consumes nothing. - OneTimeConfirmed: - properties: - order: - $ref: '#/components/schemas/OneTimeOrder' - signed_in: - type: boolean - title: Signed In - me: + title: Policy Id + policy_version_id: anyOf: - - additionalProperties: true - type: object + - type: string - type: 'null' - title: Me + title: Policy Version Id + policy_name: + anyOf: + - type: string + - type: 'null' + title: Policy Name + version: + anyOf: + - type: integer + - type: 'null' + title: Version + denials: + items: + additionalProperties: true + type: object + type: array + title: Denials + plan: + additionalProperties: true + type: object + title: Plan + executed: + type: boolean + title: Executed + default: false + usage: + type: + - object + - 'null' + additionalProperties: + type: integer + description: Returned by POST /v1/policy-evaluations when a bound policy has usage. + x-sdk-route: POST /v1/policy-evaluations additionalProperties: true type: object required: - - order - - signed_in - title: OneTimeConfirmed - description: |- - ``signed_in`` says whether this browser now holds a session for the payer; ``me`` is then the same - object ``GET /v1/auth/me`` answers (the CSRF token included). - OneTimeFromQuote: + - decision + - rule + - reason + - policy_id + - policy_version_id + - policy_name + - version + - denials + - plan + title: PolicyEvaluation + PolicyEvaluationCreate: properties: quote_id: - type: string - title: Quote Id - sender_name: - type: string - maxLength: 200 - title: Sender Name - description: Printed on the cover sheet. 2 to 120 characters. - accept_aup: - type: boolean - title: Accept Aup - description: 'A session sends true: the signed-in person accepts the acceptable use policy and the terms. - A key''s value is not recorded: the person who pays accepts on the order''s page.' - default: false - email: anyOf: - type: string - maxLength: 254 + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Email - approval_id: + title: Quote Id + description: Evaluate an existing quote. + document_id: anyOf: - type: string - maxLength: 64 + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Approval Id - description: An approved, unused approval request for this quote (POST /v1/approval-requests). A key needs - it unless a delegated policy allows the send. A session needs none. - source_ref: + title: Document Id + description: 'Or plan: this document ...' + to: anyOf: - type: string maxLength: 32 - type: 'null' - title: Source Ref - delete_after_send: + title: To + description: '... to this E.164 destination.' + from: anyOf: - - type: boolean + - type: string + maxLength: 32 - type: 'null' - title: Delete After Send - description: Delete the document and the transmitted copy the moment the fax ends in delivered, partial - or failed. The order, the receipt and the carrier evidence stay; they hold no document content. A fax - that ends unknown keeps the document until the carrier reports, or until the retention period ends. - Left out, the quote's own delete_after_send applies. + title: From additionalProperties: false type: object + title: PolicyEvaluationCreate + PolicyList: + properties: + items: + items: + $ref: '#/components/schemas/Policy' + type: array + title: Items + additionalProperties: true + type: object required: - - quote_id - - sender_name - title: OneTimeFromQuote - OneTimeJob: + - items + title: PolicyList + PolicyUpdate: properties: - order_id: - type: string - title: Order Id - status: + name: anyOf: - type: string - enum: - - draft - - checkout_open - - authorized - - awaiting_confirmation - - released - - capturing - - canceling - - captured - - released_hold - - expired - - refused - - settle_failed - - type: 'null' - title: Status - amount_micro: - anyOf: - - type: integer + maxLength: 120 + minLength: 1 - type: 'null' - title: Amount Micro - captured_micro: + title: Name + purpose: anyOf: - - type: integer + - type: string + maxLength: 500 - type: 'null' - title: Captured Micro - refunded_micro: + title: Purpose + rules: anyOf: - - type: integer + - additionalProperties: true + type: object - type: 'null' - title: Refunded Micro - description: What was refunded to the card after the charge, in micro-units. - document_pages: + title: Rules + enabled: anyOf: - - type: integer + - type: boolean - type: 'null' - title: Document Pages - description: The pages of the order's document. The cover sheet is not counted. - card: + title: Enabled + additionalProperties: false + type: object + title: PolicyUpdate + PolicyVersion: + properties: + id: + type: string + title: Id + policy_id: + type: string + title: Policy Id + version: + type: integer + title: Version + name: + type: string + title: Name + purpose: anyOf: - - $ref: '#/components/schemas/OneTimeCard' + - type: string - type: 'null' + title: Purpose + enabled: + type: boolean + title: Enabled + rules: + additionalProperties: true + type: object + title: Rules + created_by: + type: string + title: Created By + created_at: + type: string + title: Created At additionalProperties: true type: object required: - - order_id - title: OneTimeJob - description: 'The order behind a fax job that a one-time send made: what was authorized, what was charged.' - OneTimeOrder: + - id + - policy_id + - version + - name + - purpose + - enabled + - rules + - created_by + - created_at + title: PolicyVersion + PolicyVersionList: + properties: + items: + items: + $ref: '#/components/schemas/PolicyVersion' + type: array + title: Items + additionalProperties: true + type: object + required: + - items + title: PolicyVersionList + PortOrder: properties: id: type: string title: Id - status: - type: string - enum: - - draft - - checkout_open - - authorized - - awaiting_confirmation - - released - - capturing - - canceling - - captured - - released_hold - - expired - - refused - - settle_failed - title: Status - next: - type: string - enum: - - checkout - - confirm - - wait - - done - title: Next environment: type: string enum: - live - test title: Environment - source: - type: string - enum: - - web - - api - - mcp - title: Source - email: + direction: type: string - title: Email - email_verified: - type: boolean - title: Email Verified - sender_name: + title: Direction + status: type: string - title: Sender Name - to: + title: Status + numbers: + items: + type: string + type: array + title: Numbers + request: + additionalProperties: true + type: object + title: Request + milestones: + items: + additionalProperties: true + type: object + type: array + title: Milestones + provider: type: string - title: To - route: + title: Provider + created_at: type: string - title: Route - cover: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Cover - document_pages: - type: integer - title: Document Pages - document_sha256: + title: Created At + updated_at: type: string - title: Document Sha256 - document_id: + title: Updated At + additionalProperties: true + type: object + required: + - id + - environment + - direction + - status + - numbers + - request + - milestones + - provider + - created_at + - updated_at + title: PortOrder + PortOrderCreate: + properties: + numbers: + items: + type: string + type: array + maxItems: 50 + minItems: 1 + title: Numbers + note: anyOf: - type: string + maxLength: 500 - type: 'null' - title: Document Id - delete_after_send: - type: boolean - title: Delete After Send - description: The sender asked for the document and the transmitted copy to be deleted the moment the fax - ends in delivered, partial or failed. - default: false - document_deleted: - type: boolean - title: Document Deleted - description: 'True once no copy of the document is held: it was deleted after the send, by the retention - period or by its owner, or the order ended before it was released and the uploaded file was removed. - The order, the fax and the carrier evidence stay; they hold no document content.' - default: false - document_expires_at: + title: Note + additionalProperties: false + type: object + required: + - numbers + title: PortOrderCreate + PortOrderList: + properties: + items: + items: + $ref: '#/components/schemas/PortOrder' + type: array + title: Items + additionalProperties: true + type: object + required: + - items + title: PortOrderList + PortOutRequestCreate: + properties: + number_id: + type: string + title: Number Id + note: anyOf: - type: string + maxLength: 500 - type: 'null' - title: Document Expires At - description: When the retention period deletes the stored document. Null before the release and once the - document is deleted. - price: - $ref: '#/components/schemas/OneTimePrice' + title: Note + additionalProperties: false + type: object + required: + - number_id + title: PortOutRequestCreate + PortabilityCheck: + properties: + items: + items: + additionalProperties: true + type: object + type: array + title: Items + checked_at: + type: string + title: Checked At + additionalProperties: true + type: object + required: + - items + - checked_at + title: PortabilityCheck + PortabilityCheckCreate: + properties: + numbers: + items: + type: string + type: array + maxItems: 50 + minItems: 1 + title: Numbers + additionalProperties: false + type: object + required: + - numbers + title: PortabilityCheckCreate + PortalSession: + properties: + url: + type: string + title: Url + expires_at: + type: string + title: Expires At + additionalProperties: true + type: object + required: + - url + - expires_at + title: PortalSession + Quote: + properties: + id: + type: string + title: Id + environment: + type: string + enum: + - live + - test + title: Environment + document_id: + type: string + title: Document Id + document_sha256: + type: string + title: Document Sha256 + to: + type: string + title: To + from: + anyOf: + - type: string + - type: 'null' + title: From + route: + type: string + title: Route + document_pages: + type: integer + title: Document Pages + cover_pages: + type: integer + title: Cover Pages + billable_pages: + type: integer + title: Billable Pages amount_micro: type: integer title: Amount Micro - captured_micro: - type: integer - title: Captured Micro - refunded_micro: + currency: + type: string + title: Currency + price_version: + type: string + title: Price Version + per_page_micro: type: integer - title: Refunded Micro - description: What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero - when nothing was refunded. captured_micro stays what was charged. + title: Per Page Micro default: 0 - card: - anyOf: - - $ref: '#/components/schemas/OneTimeCard' - - type: 'null' - checkout_url: - anyOf: - - type: string - - type: 'null' - title: Checkout Url - checkout_expires_at: - anyOf: - - type: string - - type: 'null' - title: Checkout Expires At - authorized_at: - anyOf: - - type: string - - type: 'null' - title: Authorized At - confirm_deadline_at: - anyOf: - - type: string - - type: 'null' - title: Confirm Deadline At - capture_deadline_at: - anyOf: - - type: string - - type: 'null' - title: Capture Deadline At - confirm_mail_sent_at: - anyOf: - - type: string - - type: 'null' - title: Confirm Mail Sent At - resend_allowed_at: - anyOf: - - type: string - - type: 'null' - title: Resend Allowed At - description: When the confirmation mail may be asked for again; null when it may not. - queue: - anyOf: - - $ref: '#/components/schemas/OneTimeQueue' - - type: 'null' - description: The wait for a carrier line while the order has not ended and its fax is not on a line yet. - Null for an ended order, a fax that is sending, and a test order. - released_at: - anyOf: - - type: string - - type: 'null' - title: Released At - settled_at: - anyOf: - - type: string - - type: 'null' - title: Settled At - quote_id: - anyOf: - - type: string - - type: 'null' - title: Quote Id - fax_job_id: - anyOf: - - type: string - - type: 'null' - title: Fax Job Id - failure_code: + route_label: + type: string + title: Route Label + default: '' + cover: anyOf: - - type: string + - additionalProperties: true + type: object - type: 'null' - title: Failure Code - aup_version: + title: Cover + quality: type: string - title: Aup Version - aup_accepted: - type: boolean - title: Aup Accepted - description: Whether a person accepted the acceptable use policy and the terms for this order. False for - an order a key created until the payer accepts on the order's page; the checkout needs it. - default: true - status_url: + title: Quality + default: fine + sender_name: anyOf: - type: string - type: 'null' - title: Status Url - description: The order's page for the person who pays or confirms, with a fresh status token. Present - on a read by a key or session of the order's organization while the order is not done. + title: Sender Name + delete_after_send: + type: boolean + title: Delete After Send + default: false + authorization_required: + type: boolean + title: Authorization Required warnings: items: additionalProperties: true type: object type: array title: Warnings - fax: + expires_at: + type: string + title: Expires At + expired: + type: boolean + title: Expired + consumed_by_job_id: anyOf: - - additionalProperties: true - type: object + - type: string - type: 'null' - title: Fax - description: The fax job (the FaxJob shape) once the order was released; null before. + title: Consumed By Job Id created_at: type: string title: Created At - updated_at: + pricing: type: string - title: Updated At + description: Returned by POST /v1/fax-quotes. Declared here until the public schema includes it. + x-sdk-route: POST /v1/fax-quotes + policy_evaluation: + type: + - object + - 'null' + description: Returned by GET /v1/fax-quotes/{quote_id}. Declared here until the public schema includes + it. + x-sdk-route: GET /v1/fax-quotes/{quote_id} + additionalProperties: true additionalProperties: true type: object required: - id - - status - - next - environment - - source - - email - - email_verified - - sender_name + - document_id + - document_sha256 - to - route - - cover - document_pages - - document_sha256 - - document_id - - price + - cover_pages + - billable_pages - amount_micro - - captured_micro - - card - - checkout_url - - checkout_expires_at - - authorized_at - - confirm_deadline_at - - capture_deadline_at - - confirm_mail_sent_at - - released_at - - settled_at - - quote_id - - fax_job_id - - failure_code - - aup_version + - currency + - price_version + - cover + - authorization_required + - warnings + - expires_at + - expired + - consumed_by_job_id - created_at - - updated_at - title: OneTimeOrder - description: |- - One order of the one-time send. ``next`` is what the caller does now: ``checkout`` (open the - payment), ``confirm`` (the payer clicks the link in the mail), ``wait`` (nothing to do; read again) or - ``done``. Money is integer micro-USD. ``captured_micro`` is what the card was charged, written only - once the payment provider confirmed it. ``fax`` is the fax job once the order was released, with the - carrier's evidence once it has any. - OneTimeOrderCreated: + title: Quote + QuoteCreate: properties: - id: - type: string - title: Id - status: - type: string - enum: - - draft - - checkout_open - - authorized - - awaiting_confirmation - - released - - capturing - - canceling - - captured - - released_hold - - expired - - refused - - settle_failed - title: Status - next: - type: string - enum: - - checkout - - confirm - - wait - - done - title: Next - environment: - type: string - enum: - - live - - test - title: Environment - source: - type: string - enum: - - web - - api - - mcp - title: Source - email: - type: string - title: Email - email_verified: - type: boolean - title: Email Verified - sender_name: + document_id: type: string - title: Sender Name + title: Document Id to: type: string title: To - route: - type: string - title: Route + description: Destination in E.164, for example +12025550123. + from: + anyOf: + - type: string + - type: 'null' + title: From + description: A number you own; omit for the shared pool. cover: anyOf: - additionalProperties: true type: object - type: 'null' title: Cover - document_pages: - type: integer - title: Document Pages - document_sha256: + description: 'Cover sheet fields: to_name, from_name, subject, message. Counts as a page.' + quality: type: string - title: Document Sha256 - document_id: + enum: + - standard + - fine + - superfine + - ultra + title: Quality + description: 'Fax resolution. standard is the fax standard''s 204 by 98 dpi, fine (the default) 204 by + 196, superfine 204 by 392. ultra asks the carrier for its darkest text processing at the same superfine + resolution and takes longer to process: measured 2026-11-09, a page sent at ultra and one at superfine + both arrived as 1728 by 4112 pixels, 204 by 391 dpi. The price does not change. The job echoes the level.' + default: fine + sender_name: anyOf: - type: string + maxLength: 128 - type: 'null' - title: Document Id + title: Sender Name + description: The name that identifies the sender. The carrier gets it as the caller name for its header + line. A fax without a cover sheet prints it in one line at the top of page one. The line also gives + the sending number and the time in UTC. Letters, digits, spaces and - _ ~ ! . + only, at most 128 characters. + Omit to use the organization's name. delete_after_send: type: boolean title: Delete After Send - description: The sender asked for the document and the transmitted copy to be deleted the moment the fax - ends in delivered, partial or failed. - default: false - document_deleted: - type: boolean - title: Document Deleted - description: 'True once no copy of the document is held: it was deleted after the send, by the retention - period or by its owner, or the order ended before it was released and the uploaded file was removed. - The order, the fax and the carrier evidence stay; they hold no document content.' + description: 'Delete the document and the transmitted copy the moment the fax ends in delivered, partial + or failed. The job, its receipt and the carrier evidence stay; they hold no document content. A fax + that ends unknown keeps the document until a reconcile settles it. Default: keep the document for the + retention period.' default: false - document_expires_at: + additionalProperties: false + type: object + required: + - document_id + - to + title: QuoteCreate + Receipt: + properties: + fax_job_id: + type: string + title: Fax Job Id + state: + type: string + title: State + failure_code: anyOf: - type: string - type: 'null' - title: Document Expires At - description: When the retention period deletes the stored document. Null before the release and once the - document is deleted. - price: - $ref: '#/components/schemas/OneTimePrice' - amount_micro: - type: integer - title: Amount Micro - captured_micro: - type: integer - title: Captured Micro - refunded_micro: - type: integer - title: Refunded Micro - description: What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero - when nothing was refunded. captured_micro stays what was charged. - default: 0 - card: - anyOf: - - $ref: '#/components/schemas/OneTimeCard' - - type: 'null' - checkout_url: + title: Failure Code + to: + type: string + title: To + from: anyOf: - type: string - type: 'null' - title: Checkout Url - checkout_expires_at: + title: From + document_sha256: + type: string + title: Document Sha256 + transmitted_sha256: anyOf: - type: string - type: 'null' - title: Checkout Expires At - authorized_at: + title: Transmitted Sha256 + billable_pages: + type: integer + title: Billable Pages + cover_pages: + type: integer + title: Cover Pages + description: 'How many of the billable pages are the cover sheet: 0 or 1.' + default: 0 + pages_sent: + type: integer + title: Pages Sent + amount_micro: + type: integer + title: Amount Micro + captured_micro: + type: integer + title: Captured Micro + currency: + type: string + title: Currency + provider: + type: string + title: Provider + created_at: + type: string + title: Created At + completed_at: anyOf: - type: string - type: 'null' - title: Authorized At - confirm_deadline_at: + title: Completed At + evidence: anyOf: - - type: string + - additionalProperties: true + type: object - type: 'null' - title: Confirm Deadline At - capture_deadline_at: + title: Evidence + attempts: + items: + $ref: '#/components/schemas/Attempt' + type: array + title: Attempts + note: + type: string + title: Note + generated_at: + type: string + title: Generated At + one_time: anyOf: - - type: string + - $ref: '#/components/schemas/OneTimeJob' - type: 'null' - title: Capture Deadline At - confirm_mail_sent_at: + description: Set on the receipt of a fax that a one-time order paid for. It names the order, its status, + the card and the amount the card was authorized for. captured_micro in it is the amount charged, written + once the payment provider confirmed the capture. For a card order read the money here. Null for a fax + paid from the wallet. + additionalProperties: true + type: object + required: + - fax_job_id + - state + - failure_code + - to + - document_sha256 + - transmitted_sha256 + - billable_pages + - pages_sent + - amount_micro + - captured_micro + - currency + - provider + - created_at + - completed_at + - evidence + - attempts + - note + - generated_at + title: Receipt + ReleaseRequest: + properties: + confirm: anyOf: - type: string - type: 'null' - title: Confirm Mail Sent At - resend_allowed_at: - anyOf: - - type: string - - type: 'null' - title: Resend Allowed At - description: When the confirmation mail may be asked for again; null when it may not. - queue: - anyOf: - - $ref: '#/components/schemas/OneTimeQueue' - - type: 'null' - description: The wait for a carrier line while the order has not ended and its fax is not on a line yet. - Null for an ended order, a fax that is sending, and a test order. - released_at: - anyOf: - - type: string - - type: 'null' - title: Released At - settled_at: - anyOf: - - type: string - - type: 'null' - title: Settled At - quote_id: - anyOf: - - type: string - - type: 'null' - title: Quote Id - fax_job_id: - anyOf: - - type: string - - type: 'null' - title: Fax Job Id - failure_code: - anyOf: - - type: string - - type: 'null' - title: Failure Code - aup_version: - type: string - title: Aup Version - aup_accepted: + title: Confirm + description: The number itself, typed out, to confirm. + additionalProperties: false + type: object + title: ReleaseRequest + Requested: + properties: + requested: type: boolean - title: Aup Accepted - description: Whether a person accepted the acceptable use policy and the terms for this order. False for - an order a key created until the payer accepts on the order's page; the checkout needs it. - default: true - status_url: + title: Requested + kind: type: string - title: Status Url - warnings: - items: - additionalProperties: true - type: object - type: array - title: Warnings - fax: + enum: + - export + - deletion + title: Kind + message: + type: string + title: Message + additionalProperties: true + type: object + required: + - requested + - kind + - message + title: Requested + SandboxFixture: + properties: + id: + type: string + title: Id + scenario: + type: string + title: Scenario + destination: anyOf: - - additionalProperties: true - type: object + - type: string - type: 'null' - title: Fax - description: The fax job (the FaxJob shape) once the order was released; null before. + title: Destination created_at: type: string title: Created At - updated_at: - type: string - title: Updated At - status_token: + expires_at: type: string - title: Status Token + title: Expires At additionalProperties: true type: object required: - id - - status - - next - - environment - - source - - email - - email_verified - - sender_name - - to - - route - - cover - - document_pages - - document_sha256 - - document_id - - price - - amount_micro - - captured_micro - - card - - checkout_url - - checkout_expires_at - - authorized_at - - confirm_deadline_at - - capture_deadline_at - - confirm_mail_sent_at - - released_at - - settled_at - - quote_id - - fax_job_id - - failure_code - - aup_version - - status_url + - scenario + - destination - created_at - - updated_at - - status_token - title: OneTimeOrderCreated - description: |- - The create answer: the order plus the status token. The token reads this one order, opens its - checkout and asks for the confirmation mail again, with no key and no session, for seven days. Send it - as ``X-FFA-Order-Token`` (or ``?t=``). ``status_url`` is the order's page in the app with the token. - OneTimeOrderPage: + - expires_at + title: SandboxFixture + SandboxInboundCreate: properties: - items: - items: - $ref: '#/components/schemas/OneTimeOrder' - type: array - title: Items - next_cursor: + to: + type: string + title: To + from: anyOf: - type: string - type: 'null' - title: Next Cursor - additionalProperties: true - type: object - required: - - items - title: OneTimeOrderPage - OneTimePrice: - properties: - price_version: - type: string - title: Price Version - currency: - type: string - title: Currency - flat_micro: - type: integer - title: Flat Micro - included_pages: - type: integer - title: Included Pages - extra_page_micro: + title: From + pages: type: integer - title: Extra Page Micro - cover_included: + maximum: 200.0 + minimum: 1.0 + title: Pages + default: 1 + partial_content: type: boolean - title: Cover Included - additionalProperties: true + title: Partial Content + description: Rehearse a cut-off transmission. + default: false + additionalProperties: false type: object required: - - price_version - - currency - - flat_micro - - included_pages - - extra_page_micro - - cover_included - title: OneTimePrice - OneTimeQueue: + - to + title: SandboxInboundCreate + SandboxReset: properties: - queued: + reset: type: boolean - title: Queued - jobs_ahead: - type: integer - title: Jobs Ahead - estimated_wait_minutes: + title: Reset + deleted: + additionalProperties: + type: integer + type: object + title: Deleted + wallet_available_micro: type: integer - title: Estimated Wait Minutes + title: Wallet Available Micro additionalProperties: true type: object required: - - queued - - jobs_ahead - - estimated_wait_minutes - title: OneTimeQueue - description: |- - The wait for a carrier line. ``queued`` is true when a fax sent now, or this order's waiting fax, - is estimated to wait more than ten minutes for a line: the order is kept and sent in turn, never - dropped. The minutes are an estimate from the number of faxes ahead and the carrier's line count. - OneTimeRoute: + - reset + - deleted + - wallet_available_micro + title: SandboxReset + SandboxScenarioCreate: properties: - label: + scenario: type: string - title: Label - flat_micro: - type: integer - title: Flat Micro - included_pages: - type: integer - title: Included Pages - extra_page_micro: - type: integer - title: Extra Page Micro - cover_included: - type: boolean - title: Cover Included - additionalProperties: true + title: Scenario + destination: + anyOf: + - type: string + - type: 'null' + title: Destination + description: Apply to one destination; omit for every send. + additionalProperties: false type: object required: - - label - - flat_micro - - included_pages - - extra_page_micro - - cover_included - title: OneTimeRoute - Organization: - properties: - id: - type: string - title: Id - name: - type: string - title: Name - role: - anyOf: - - type: string - enum: - - owner - - admin - - member - - viewer - - type: 'null' - title: Role - created_at: - type: string - title: Created At - members: - type: integer - title: Members - additionalProperties: true - type: object - required: - - id - - name - - role - - created_at - - members - title: Organization - OrganizationList: + - scenario + title: SandboxScenarioCreate + SandboxScenarios: properties: - items: + scenarios: items: - $ref: '#/components/schemas/OrganizationSummary' + additionalProperties: + type: string + type: object type: array - title: Items + title: Scenarios + destinations: + items: + additionalProperties: + type: string + type: object + type: array + title: Destinations + fixtures: + items: + $ref: '#/components/schemas/SandboxFixture' + type: array + title: Fixtures additionalProperties: true type: object required: - - items - title: OrganizationList - OrganizationPatch: + - scenarios + - destinations + - fixtures + title: SandboxScenarios + SchemaCreate: properties: name: type: string - maxLength: 200 + maxLength: 120 minLength: 1 title: Name + description: + anyOf: + - type: string + maxLength: 500 + - type: 'null' + title: Description + schema: + additionalProperties: true + type: object + title: Schema additionalProperties: false type: object required: - name - title: OrganizationPatch - OrganizationSummary: + - schema + title: SchemaCreate + SenderVerification: properties: id: type: string title: Id - name: - type: string - title: Name - role: + environment: type: string enum: - - owner - - admin - - member - - viewer - title: Role + - live + - test + title: Environment + from: + type: string + title: From + status: + type: string + title: Status + method: + type: string + title: Method + number_id: + anyOf: + - type: string + - type: 'null' + title: Number Id + created_at: + type: string + title: Created At + verified_at: + anyOf: + - type: string + - type: 'null' + title: Verified At additionalProperties: true type: object required: - id - - name - - role - title: OrganizationSummary - OutboxDiscarded: + - environment + - from + - status + - method + - number_id + - created_at + - verified_at + title: SenderVerification + SenderVerificationCreate: properties: - id: + from: type: string - title: Id - discarded: - type: boolean - title: Discarded - additionalProperties: true + title: From + description: A number your organization owns, E.164. + additionalProperties: false type: object required: - - id - - discarded - title: OutboxDiscarded - OutboxPage: + - from + title: SenderVerificationCreate + ServiceStatus: properties: - items: - items: - $ref: '#/components/schemas/OutboxRow' - type: array - title: Items - next_cursor: + status: + type: string + enum: + - ok + - degraded + title: Status + version: + type: string + title: Version + environment: + type: string + enum: + - live + - test + title: Environment + provider: + type: string + title: Provider + database: + type: boolean + title: Database + worker_beat_age_s: + anyOf: + - type: integer + - type: 'null' + title: Worker Beat Age S + status_page: anyOf: - type: string - type: 'null' - title: Next Cursor + title: Status Page additionalProperties: true type: object required: - - items - title: OutboxPage - OutboxRow: + - status + - version + - environment + - provider + - database + title: ServiceStatus + SignedUrl: + properties: + url: + type: string + title: Url + expires_at: + type: string + title: Expires At + content_type: + type: string + title: Content Type + additionalProperties: true + type: object + required: + - url + - expires_at + - content_type + title: SignedUrl + Subscription: properties: id: type: string title: Id - kind: + product: type: string - title: Kind + title: Product status: type: string - enum: - - queued - - running - - done - - failed - - dead title: Status - title: - anyOf: - - type: string - - type: 'null' - title: Title - error: + stripe_subscription_id: + type: string + title: Stripe Subscription Id + stripe_price_id: anyOf: - type: string - type: 'null' - title: Error - attempts: - type: integer - title: Attempts - max_attempts: - type: integer - title: Max Attempts - org_id: + title: Stripe Price Id + cancel_at_period_end: + type: boolean + title: Cancel At Period End + current_period_end: anyOf: - type: string - type: 'null' - title: Org Id + title: Current Period End + entitled: + type: boolean + title: Entitled created_at: type: string title: Created At - finished_at: - anyOf: - - type: string + updated_at: + type: string + title: Updated At + canceled_at: + anyOf: + - type: string - type: 'null' - title: Finished At - age_s: - type: integer - title: Age S + title: Canceled At additionalProperties: true type: object required: - id - - kind + - product - status - - attempts - - max_attempts + - stripe_subscription_id + - stripe_price_id + - cancel_at_period_end + - current_period_end + - entitled - created_at - - age_s - title: OutboxRow - PagePreview: + - updated_at + - canceled_at + title: Subscription + SubscriptionCheckout: properties: - page_number: - type: integer - title: Page Number - width_px: - anyOf: - - type: integer - - type: 'null' - title: Width Px - height_px: - anyOf: - - type: integer - - type: 'null' - title: Height Px url: type: string title: Url + stripe_session_id: + type: string + title: Stripe Session Id + product: + type: string + title: Product additionalProperties: true type: object required: - - page_number - - width_px - - height_px - url - title: PagePreview - Passkey: + - stripe_session_id + - product + title: SubscriptionCheckout + SubscriptionList: + properties: + items: + items: + $ref: '#/components/schemas/Subscription' + type: array + title: Items + workspace: + type: boolean + title: Workspace + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor + additionalProperties: true + type: object + required: + - items + - workspace + title: SubscriptionList + SummaryCreate: + properties: + inbox_item_id: + anyOf: + - type: string + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ + - type: 'null' + title: Inbox Item Id + document_id: + anyOf: + - type: string + pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ + - type: 'null' + title: Document Id + max_pages: + anyOf: + - type: integer + maximum: 200.0 + minimum: 1.0 + - type: 'null' + title: Max Pages + strict: + type: boolean + title: Strict + description: Refuse with page_limit_exceeded when the document has more pages than would be read, instead + of reading the first ones and warning. + default: false + strong_model_if_below: + type: number + maximum: 1.0 + minimum: 0.0 + title: Strong Model If Below + default: 0.75 + additionalProperties: false + type: object + title: SummaryCreate + TopupCreate: + properties: + amount_usd: + type: integer + maximum: 1000.0 + minimum: 10.0 + title: Amount Usd + description: Whole US dollars, 10 to 1000 per session. + additionalProperties: false + type: object + required: + - amount_usd + title: TopupCreate + TopupSession: properties: id: type: string title: Id - label: + environment: + type: string + enum: + - live + - test + title: Environment + kind: + type: string + enum: + - manual + - auto + - setup + title: Kind + amount_micro: + type: integer + title: Amount Micro + currency: + type: string + title: Currency + status: + type: string + enum: + - open + - completed + - expired + - canceled + - failed + title: Status + url: anyOf: - type: string - type: 'null' - title: Label - aaguid: + title: Url + description: The hosted Checkout page while the session is open. + stripe_session_id: anyOf: - type: string - type: 'null' - title: Aaguid - transports: + title: Stripe Session Id + stripe_payment_intent_id: anyOf: - - items: - type: string - type: array + - type: string - type: 'null' - title: Transports - backup_eligible: - type: boolean - title: Backup Eligible + title: Stripe Payment Intent Id + auto_topup_id: + anyOf: + - type: string + - type: 'null' + title: Auto Topup Id + error: + anyOf: + - type: string + - type: 'null' + title: Error created_at: type: string title: Created At - last_used_at: + expires_at: anyOf: - type: string - type: 'null' - title: Last Used At + title: Expires At + completed_at: + anyOf: + - type: string + - type: 'null' + title: Completed At additionalProperties: true type: object required: - id - - label - - aaguid - - transports - - backup_eligible + - environment + - kind + - amount_micro + - currency + - status + - stripe_session_id + - stripe_payment_intent_id + - auto_topup_id + - error - created_at - - last_used_at - title: Passkey - PasskeyList: + - expires_at + - completed_at + title: TopupSession + TopupSessionPage: properties: items: items: - $ref: '#/components/schemas/Passkey' + $ref: '#/components/schemas/TopupSession' type: array title: Items + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor additionalProperties: true type: object required: - items - title: PasskeyList - PasskeyLoginVerify: - properties: - credential: - additionalProperties: true - type: object - title: Credential - additionalProperties: false - type: object - required: - - credential - title: PasskeyLoginVerify - PasskeyRegisterVerify: + title: TopupSessionPage + UploadComplete: properties: - credential: - additionalProperties: true - type: object - title: Credential - label: + sha256: anyOf: - type: string - maxLength: 80 + maxLength: 64 + minLength: 64 - type: 'null' - title: Label + title: Sha256 + description: 'Optional: fail if the bytes differ.' additionalProperties: false type: object - required: - - credential - title: PasskeyRegisterVerify - Policy: + title: UploadComplete + UploadCreate: properties: - id: + filename: type: string - title: Id - name: + maxLength: 255 + minLength: 1 + title: Filename + content_type: type: string - title: Name - purpose: + maxLength: 100 + title: Content Type + description: application/pdf, image/png, image/jpeg or image/tiff. An image becomes 8-bit gray letter + pages, since fax is monochrome. A frame wider than it is tall is rotated. A frame above 300 dpi letter + is downsampled. Every TIFF frame is a page. PNG and JPEG take the first frame. The bytes must be the + declared type. + default: application/pdf + size_bytes: + type: integer + minimum: 1.0 + title: Size Bytes + additionalProperties: false + type: object + required: + - filename + - size_bytes + title: UploadCreate + UploadSession: + properties: + id: + type: string + title: Id + status: + type: string + title: Status + filename: + type: string + title: Filename + content_type: + type: string + title: Content Type + declared_size: + type: integer + title: Declared Size + received_size: + type: integer + title: Received Size + sha256: anyOf: - type: string - type: 'null' - title: Purpose - enabled: - type: boolean - title: Enabled - version: - type: integer - title: Version - current_version_id: + title: Sha256 + created_at: + type: string + title: Created At + expires_at: + type: string + title: Expires At + completed_at: anyOf: - type: string - type: 'null' - title: Current Version Id - rules: + title: Completed At + upload_url: + anyOf: + - type: string + - type: 'null' + title: Upload Url + upload_method: + anyOf: + - type: string + - type: 'null' + title: Upload Method + upload_url_expires_at: + anyOf: + - type: string + - type: 'null' + title: Upload Url Expires At + additionalProperties: true + type: object + required: + - id + - status + - filename + - content_type + - declared_size + - received_size + - sha256 + - created_at + - expires_at + - completed_at + title: UploadSession + UsageExport: + properties: + id: + type: string + title: Id + environment: + type: string + enum: + - live + - test + title: Environment + status: + type: string + enum: + - ready + - expired + title: Status + params: additionalProperties: true type: object - title: Rules - managed: + title: Params + row_count: + type: integer + title: Row Count + content_type: + type: string + title: Content Type + url: anyOf: - type: string - type: 'null' - title: Managed - description: connected_apps when a Settings switch (the auto-send setting) manages this policy. Such a - policy is read here and changed only through PUT /v1/organizations/current/auto-send. - created_by: - type: string - title: Created By + title: Url created_at: type: string title: Created At - updated_at: + expires_at: type: string - title: Updated At + title: Expires At additionalProperties: true type: object required: - id - - name - - purpose - - enabled - - version - - current_version_id - - rules - - created_by + - environment + - status + - params + - row_count + - content_type + - url - created_at - - updated_at - title: Policy - PolicyCreate: + - expires_at + title: UsageExport + UsageExportCreate: properties: - name: - type: string - maxLength: 120 - minLength: 1 - title: Name - purpose: + from: anyOf: - type: string - maxLength: 500 - type: 'null' - title: Purpose - description: Why this policy exists. Shown, never evaluated. - rules: - additionalProperties: true - type: object - title: Rules - description: See the PolicyRules schema in docs/APPROVALS.md. - enabled: - type: boolean - title: Enabled - default: true + title: From + description: ISO date; default 30 days ago. + to: + anyOf: + - type: string + - type: 'null' + title: To + description: ISO date; default today. additionalProperties: false type: object - required: - - name - - rules - title: PolicyCreate - PolicyEvaluation: + title: UsageExportCreate + UsageItem: properties: - decision: - type: string - title: Decision - rule: + day: anyOf: - type: string - type: 'null' - title: Rule - reason: - type: string - title: Reason - policy_id: + title: Day + direction: anyOf: - type: string - type: 'null' - title: Policy Id - policy_version_id: + title: Direction + route: anyOf: - type: string - type: 'null' - title: Policy Version Id - policy_name: + title: Route + destination: anyOf: - type: string - type: 'null' - title: Policy Name - version: + title: Destination + project_id: anyOf: - - type: integer + - type: string - type: 'null' - title: Version - denials: - items: - additionalProperties: true - type: object - type: array - title: Denials - plan: - additionalProperties: true - type: object - title: Plan - executed: - type: boolean - title: Executed - default: false - usage: - type: - - object - - 'null' - additionalProperties: - type: integer - description: Returned by POST /v1/policy-evaluations when a bound policy has usage. - x-sdk-route: POST /v1/policy-evaluations + title: Project Id + pages: + type: integer + title: Pages + jobs: + type: integer + title: Jobs + amount_micro: + type: integer + title: Amount Micro additionalProperties: true type: object required: - - decision - - rule - - reason - - policy_id - - policy_version_id - - policy_name - - version - - denials - - plan - title: PolicyEvaluation - PolicyEvaluationCreate: - properties: - quote_id: + - pages + - jobs + - amount_micro + title: UsageItem + UsageReport: + properties: + environment: + type: string + enum: + - live + - test + title: Environment + from: + type: string + title: From + to: + type: string + title: To + group_by: + items: + type: string + type: array + title: Group By + currency: + type: string + title: Currency + items: + items: + $ref: '#/components/schemas/UsageItem' + type: array + title: Items + totals: + additionalProperties: + type: integer + type: object + title: Totals + additionalProperties: true + type: object + required: + - environment + - from + - to + - group_by + - currency + - items + - totals + title: UsageReport + Webhook: + properties: + id: + type: string + title: Id + url: + type: string + title: Url + description: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Quote Id - description: Evaluate an existing quote. - document_id: + title: Description + event_types: + items: + type: string + type: array + title: Event Types + status: + type: string + title: Status + previous_secret_expires_at: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Document Id - description: 'Or plan: this document ...' - to: + title: Previous Secret Expires At + created_at: + type: string + title: Created At + updated_at: + type: string + title: Updated At + additionalProperties: true + type: object + required: + - id + - url + - description + - event_types + - status + - previous_secret_expires_at + - created_at + - updated_at + title: Webhook + WebhookCreate: + properties: + url: + type: string + maxLength: 2000 + title: Url + description: anyOf: - type: string - maxLength: 32 + maxLength: 200 - type: 'null' - title: To - description: '... to this E.164 destination.' - from: + title: Description + event_types: anyOf: - - type: string - maxLength: 32 + - items: + type: string + type: array - type: 'null' - title: From + title: Event Types + description: 'Empty or omitted: every event type.' additionalProperties: false type: object - title: PolicyEvaluationCreate - PolicyList: + required: + - url + title: WebhookCreate + WebhookList: properties: items: items: - $ref: '#/components/schemas/Policy' + $ref: '#/components/schemas/Webhook' type: array title: Items additionalProperties: true type: object required: - items - title: PolicyList - PolicyUpdate: + title: WebhookList + WebhookUpdate: properties: - name: + url: anyOf: - type: string - maxLength: 120 - minLength: 1 + maxLength: 2000 - type: 'null' - title: Name - purpose: + title: Url + description: anyOf: - type: string - maxLength: 500 + maxLength: 200 - type: 'null' - title: Purpose - rules: + title: Description + event_types: anyOf: - - additionalProperties: true - type: object + - items: + type: string + type: array - type: 'null' - title: Rules - enabled: + title: Event Types + status: anyOf: - - type: boolean + - type: string + enum: + - active + - paused - type: 'null' - title: Enabled + title: Status additionalProperties: false type: object - title: PolicyUpdate - PolicyVersion: + title: WebhookUpdate + WebhookWithSecret: properties: id: type: string title: Id - policy_id: - type: string - title: Policy Id - version: - type: integer - title: Version - name: + url: type: string - title: Name - purpose: + title: Url + description: anyOf: - type: string - type: 'null' - title: Purpose - enabled: - type: boolean - title: Enabled - rules: - additionalProperties: true - type: object - title: Rules - created_by: - type: string - title: Created By - created_at: - type: string - title: Created At - additionalProperties: true - type: object - required: - - id - - policy_id - - version - - name - - purpose - - enabled - - rules - - created_by - - created_at - title: PolicyVersion - PolicyVersionList: - properties: - items: + title: Description + event_types: items: - $ref: '#/components/schemas/PolicyVersion' + type: string type: array - title: Items - additionalProperties: true - type: object - required: - - items - title: PolicyVersionList - PortOrder: - properties: - id: - type: string - title: Id - environment: - type: string - enum: - - live - - test - title: Environment - direction: - type: string - title: Direction + title: Event Types status: type: string title: Status - numbers: - items: - type: string - type: array - title: Numbers - request: - additionalProperties: true - type: object - title: Request - milestones: - items: - additionalProperties: true - type: object - type: array - title: Milestones - provider: - type: string - title: Provider + previous_secret_expires_at: + anyOf: + - type: string + - type: 'null' + title: Previous Secret Expires At created_at: type: string title: Created At updated_at: type: string title: Updated At + secret: + type: string + title: Secret + description: whsec_... Shown once. Verify webhook-signature with it. additionalProperties: true type: object required: - id - - environment - - direction + - url + - description + - event_types - status - - numbers - - request - - milestones - - provider + - previous_secret_expires_at - created_at - updated_at - title: PortOrder - PortOrderCreate: + - secret + title: WebhookWithSecret + InsufficientBalance: + title: InsufficientBalance + description: The error envelope of 402 insufficient_balance, with its details written out. + type: object + required: + - error properties: - numbers: - items: - type: string - type: array - maxItems: 50 - minItems: 1 - title: Numbers - note: + error: + type: object + required: + - code + - message + - retryable + - correlation_id + - details + properties: + code: + type: string + const: insufficient_balance + message: + type: string + retryable: + type: boolean + correlation_id: + type: string + details: + type: object + additionalProperties: true + required: + - available_micro + - needed_micro + properties: + available_micro: + type: integer + description: What the wallet holds that is not on hold. + needed_micro: + type: integer + description: What this fax holds. + top_up_url: + type: string + description: The dashboard page where a person adds funds to the wallet. A key cannot top up. + one_time_offer: + type: object + description: 'The card path for this exact send, present when it qualifies: the one-time product + is open, the key is live, the route is sold one fax at a time and the document is within the + page cap. Pass the quote to POST /v1/one-time-sends/from-quote. A pointer, never a promise: + the create runs every check again.' + required: + - amount_micro + - currency + - document_pages + - included_pages + - extra_page_micro + - max_document_pages + properties: + amount_micro: + type: integer + description: The one-time price of this document to this number. + currency: + type: string + document_pages: + type: integer + included_pages: + type: integer + extra_page_micro: + type: integer + max_document_pages: + type: integer + approval_id: + type: + - string + - 'null' + description: The approval that authorized this send. It authorizes the order of the same quote + too. + AbuseReview: + properties: + id: + type: string + title: Id + org_id: + type: string + title: Org Id + key_id: anyOf: - type: string - maxLength: 500 - type: 'null' - title: Note - additionalProperties: false - type: object - required: - - numbers - title: PortOrderCreate - PortOrderList: - properties: - items: - items: - $ref: '#/components/schemas/PortOrder' - type: array - title: Items + title: Key Id + status: + type: string + enum: + - open + - resolved + title: Status + action: + type: string + enum: + - none + - suspended + title: Action + opened_by: + type: string + title: Opened By additionalProperties: true type: object required: - - items - title: PortOrderList - PortOutRequestCreate: + - id + - org_id + - status + - action + - opened_by + title: AbuseReview + AbuseReviewCreate: properties: - number_id: + org_id: type: string - title: Number Id - note: + maxLength: 64 + minLength: 3 + title: Org Id + key_id: anyOf: - type: string - maxLength: 500 + maxLength: 64 - type: 'null' - title: Note + title: Key Id + reason: + type: string + maxLength: 500 + minLength: 3 + title: Reason + description: 'Why: recorded on the audit row' + suspend: + type: boolean + title: Suspend + description: Suspend sends for the organization or key at once + default: false additionalProperties: false type: object required: - - number_id - title: PortOutRequestCreate - PortabilityCheck: + - org_id + - reason + title: AbuseReviewCreate + AbuseReviewPage: properties: items: items: - additionalProperties: true - type: object + $ref: '#/components/schemas/AbuseReview' type: array title: Items - checked_at: - type: string - title: Checked At + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor additionalProperties: true type: object required: - items - - checked_at - title: PortabilityCheck - PortabilityCheckCreate: + title: AbuseReviewPage + AbuseReviewPatch: properties: - numbers: - items: - type: string - type: array - maxItems: 50 - minItems: 1 - title: Numbers + action: + type: string + enum: + - suspend + - unsuspend + - resolve + title: Action + reason: + type: string + maxLength: 500 + minLength: 3 + title: Reason + description: 'Why: recorded on the audit row' additionalProperties: false type: object required: - - numbers - title: PortabilityCheckCreate - PortalSession: + - action + - reason + title: AbuseReviewPatch + Accepted: properties: - url: - type: string - title: Url - expires_at: - type: string - title: Expires At + organization: + $ref: '#/components/schemas/OrganizationSummary' additionalProperties: true type: object required: - - url - - expires_at - title: PortalSession - ProviderHealth: + - organization + title: Accepted + Adjustment: properties: - name: + id: type: string - title: Name - configured: - type: boolean - title: Configured - serves: - items: - type: string - type: array - title: Serves - default: [] - circuit: + title: Id + org_id: type: string - title: Circuit - routes_paused: - items: - type: string - type: array - title: Routes Paused - breakers: - items: - additionalProperties: true - type: object - type: array - title: Breakers - default: [] - last_success_at: + title: Org Id + environment: + type: string + title: Environment + direction: + type: string + title: Direction + amount_micro: + type: integer + title: Amount Micro + status: + type: string + title: Status + proposed_by: + type: string + title: Proposed By + applied_by: anyOf: - type: string - type: 'null' - title: Last Success At - last_failure_at: + title: Applied By + txn_id: anyOf: - type: string - type: 'null' - title: Last Failure At - concurrency_in_use: - type: integer - title: Concurrency In Use - additionalProperties: true - type: object - required: - - name - - configured - - circuit - - routes_paused - - concurrency_in_use - title: ProviderHealth - ProviderList: - properties: - items: - items: - $ref: '#/components/schemas/ProviderHealth' - type: array - title: Items + title: Txn Id additionalProperties: true type: object required: - - items - title: ProviderList - Providers: + - id + - org_id + - environment + - direction + - amount_micro + - status + - proposed_by + title: Adjustment + AdjustmentApply: properties: - magic_link: - type: boolean - title: Magic Link - default: true - passkeys: - type: boolean - title: Passkeys - default: true - github: - type: boolean - title: Github - google: + reason: + type: string + maxLength: 500 + minLength: 3 + title: Reason + description: 'Why: recorded on the audit row' + confirm: type: boolean - title: Google - additionalProperties: true + title: Confirm + description: Required when the proposer applies their own adjustment + default: false + additionalProperties: false type: object required: - - github - - google - title: Providers - Quote: + - reason + title: AdjustmentApply + AdjustmentCreate: properties: - id: + org_id: type: string - title: Id + maxLength: 64 + minLength: 3 + title: Org Id environment: type: string enum: - live - test title: Environment - document_id: - type: string - title: Document Id - document_sha256: - type: string - title: Document Sha256 - to: - type: string - title: To - from: - anyOf: - - type: string - - type: 'null' - title: From - route: + default: live + direction: type: string - title: Route - document_pages: - type: integer - title: Document Pages - cover_pages: - type: integer - title: Cover Pages - billable_pages: - type: integer - title: Billable Pages + enum: + - credit + - debit + title: Direction amount_micro: type: integer + maximum: 10000000000.0 + exclusiveMinimum: 0.0 title: Amount Micro - currency: + description: Integer micro-USD; at most 10,000.00 + reason: type: string - title: Currency - price_version: + maxLength: 500 + minLength: 3 + title: Reason + description: 'Why: recorded on the audit row' + additionalProperties: false + type: object + required: + - org_id + - direction + - amount_micro + - reason + title: AdjustmentCreate + AdjustmentPage: + properties: + items: + items: + $ref: '#/components/schemas/Adjustment' + type: array + title: Items + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor + additionalProperties: true + type: object + required: + - items + title: AdjustmentPage + AdminAction: + properties: + reason: type: string - title: Price Version - per_page_micro: + maxLength: 500 + minLength: 3 + title: Reason + description: 'Why: recorded on the audit row' + additionalProperties: false + type: object + required: + - reason + title: AdminAction + AdminBrief: + properties: + utc_day: + anyOf: + - type: string + - type: 'null' + title: Utc Day + text: + anyOf: + - type: string + - type: 'null' + title: Text + posted_at: + anyOf: + - type: string + - type: 'null' + title: Posted At + channel: + anyOf: + - type: string + - type: 'null' + title: Channel + status: + anyOf: + - type: string + enum: + - posted + - failed + - gave_up + - type: 'null' + title: Status + attempts: type: integer - title: Per Page Micro + title: Attempts default: 0 - route_label: - type: string - title: Route Label - default: '' - cover: + local_day: anyOf: - - additionalProperties: true - type: object + - type: string - type: 'null' - title: Cover - quality: - type: string - title: Quality - default: fine - sender_name: + title: Local Day + attempted_at: anyOf: - type: string - type: 'null' - title: Sender Name - delete_after_send: - type: boolean - title: Delete After Send - default: false - authorization_required: - type: boolean - title: Authorization Required - warnings: - items: - additionalProperties: true - type: object - type: array - title: Warnings - expires_at: - type: string - title: Expires At - expired: - type: boolean - title: Expired - consumed_by_job_id: + title: Attempted At + attempt_utc_day: anyOf: - type: string - type: 'null' - title: Consumed By Job Id - created_at: - type: string - title: Created At - pricing: - type: string - description: Returned by POST /v1/fax-quotes. Declared here until the public schema includes it. - x-sdk-route: POST /v1/fax-quotes - policy_evaluation: - type: - - object - - 'null' - description: Returned by GET /v1/fax-quotes/{quote_id}. Declared here until the public schema includes - it. - x-sdk-route: GET /v1/fax-quotes/{quote_id} - additionalProperties: true + title: Attempt Utc Day + retry_after_s: + type: integer + title: Retry After S + default: 600 + waiting_day: + anyOf: + - type: string + - type: 'null' + title: Waiting Day additionalProperties: true type: object - required: - - id - - environment - - document_id - - document_sha256 - - to - - route - - document_pages - - cover_pages - - billable_pages - - amount_micro - - currency - - price_version - - cover - - authorization_required - - warnings - - expires_at - - expired - - consumed_by_job_id - - created_at - title: Quote - QuoteCreate: + title: AdminBrief + AdminDaily: properties: - document_id: - type: string - title: Document Id - to: + metric: type: string - title: To - description: Destination in E.164, for example +12025550123. - from: - anyOf: - - type: string - - type: 'null' - title: From - description: A number you own; omit for the shared pool. - cover: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Cover - description: 'Cover sheet fields: to_name, from_name, subject, message. Counts as a page.' - quality: + title: Metric + description: type: string - enum: - - standard - - fine - - superfine - - ultra - title: Quality - description: 'Fax resolution. standard is the fax standard''s 204 by 98 dpi, fine (the default) 204 by - 196, superfine 204 by 392. ultra asks the carrier for its darkest text processing at the same superfine - resolution and takes longer to process: measured 2026-11-09, a page sent at ultra and one at superfine - both arrived as 1728 by 4112 pixels, 204 by 391 dpi. The price does not change. The job echoes the level.' - default: fine - sender_name: - anyOf: - - type: string - maxLength: 128 - - type: 'null' - title: Sender Name - description: The station name the carrier prints in the fax header, next to the sending number. Letters, - digits, spaces and - _ ~ ! . + only, at most 128 characters. Omit to show the number alone. - delete_after_send: - type: boolean - title: Delete After Send - description: 'Delete the document and the transmitted copy the moment the fax ends in delivered, partial - or failed. The job, its receipt and the carrier evidence stay; they hold no document content. A fax - that ends unknown keeps the document until a reconcile settles it. Default: keep the document for the - retention period.' - default: false - additionalProperties: false + title: Description + days: + type: integer + title: Days + items: + items: + $ref: '#/components/schemas/AdminDailyPoint' + type: array + title: Items + additionalProperties: true type: object required: - - document_id - - to - title: QuoteCreate - Reauth: + - metric + - description + - days + - items + title: AdminDaily + AdminDailyPoint: properties: - method: + day: type: string - enum: - - passkey - - magic_link - title: Method - credential: + title: Day + environment: + type: string + title: Environment + dims: + additionalProperties: true + type: object + title: Dims + value_num: anyOf: - - additionalProperties: true - type: object + - type: integer - type: 'null' - title: Credential - additionalProperties: false + title: Value Num + value_json: + title: Value Json + computed_at: + type: string + title: Computed At + additionalProperties: true type: object required: - - method - title: Reauth - Receipt: + - day + - environment + - dims + - computed_at + title: AdminDailyPoint + AdminJob: properties: - fax_job_id: + id: type: string - title: Fax Job Id + title: Id + org_id: + type: string + title: Org Id state: type: string title: State - failure_code: - anyOf: - - type: string - - type: 'null' - title: Failure Code - to: + route: type: string - title: To - from: - anyOf: - - type: string - - type: 'null' - title: From - document_sha256: + title: Route + environment: type: string - title: Document Sha256 - transmitted_sha256: - anyOf: - - type: string - - type: 'null' - title: Transmitted Sha256 - billable_pages: - type: integer - title: Billable Pages - cover_pages: - type: integer - title: Cover Pages - description: 'How many of the billable pages are the cover sheet: 0 or 1.' - default: 0 - pages_sent: - type: integer - title: Pages Sent - amount_micro: - type: integer - title: Amount Micro - captured_micro: + enum: + - live + - test + title: Environment + age_s: type: integer - title: Captured Micro - currency: - type: string - title: Currency - provider: - type: string - title: Provider - created_at: - type: string - title: Created At - completed_at: - anyOf: - - type: string - - type: 'null' - title: Completed At - evidence: - anyOf: - - additionalProperties: true - type: object - - type: 'null' - title: Evidence - attempts: + title: Age S + additionalProperties: true + type: object + required: + - id + - org_id + - state + - route + - environment + - age_s + title: AdminJob + AdminJobPage: + properties: + items: items: - $ref: '#/components/schemas/Attempt' + $ref: '#/components/schemas/AdminJob' type: array - title: Attempts - note: - type: string - title: Note - generated_at: - type: string - title: Generated At - one_time: + title: Items + next_cursor: anyOf: - - $ref: '#/components/schemas/OneTimeJob' + - type: string - type: 'null' - description: Set on the receipt of a fax that a one-time order paid for. It names the order, its status, - the card and the amount the card was authorized for. captured_micro in it is the amount charged, written - once the payment provider confirmed the capture. For a card order read the money here. Null for a fax - paid from the wallet. + title: Next Cursor additionalProperties: true type: object required: - - fax_job_id - - state - - failure_code - - to - - document_sha256 - - transmitted_sha256 - - billable_pages - - pages_sent - - amount_micro - - captured_micro - - currency - - provider - - created_at - - completed_at - - evidence - - attempts - - note - - generated_at - title: Receipt - ReconcileResult: + - items + title: AdminJobPage + AdminOrganization: properties: - outcome: + id: + type: string + title: Id + name: + type: string + title: Name + suspended_at: + anyOf: + - type: string + - type: 'null' + title: Suspended At + internal: + type: boolean + title: Internal + default: false + balances_micro: + additionalProperties: true + type: object + title: Balances Micro + counts: + additionalProperties: + type: integer + type: object + title: Counts + additionalProperties: true + type: object + required: + - id + - name + - balances_micro + - counts + title: AdminOrganization + AdminOrganizationDetail: + properties: + organization: + additionalProperties: true + type: object + title: Organization + members: + items: + additionalProperties: true + type: object + type: array + title: Members + keys: + items: + additionalProperties: true + type: object + type: array + title: Keys + recent_jobs: + items: + additionalProperties: true + type: object + type: array + title: Recent Jobs + ledger: + additionalProperties: true + type: object + title: Ledger + open_reviews: + items: + additionalProperties: true + type: object + type: array + title: Open Reviews + additionalProperties: true + type: object + required: + - organization + - members + - keys + - recent_jobs + - ledger + - open_reviews + title: AdminOrganizationDetail + AdminOrganizationPage: + properties: + items: + items: + $ref: '#/components/schemas/AdminOrganization' + type: array + title: Items + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor + additionalProperties: true + type: object + required: + - items + title: AdminOrganizationPage + AdminRevenue: + properties: + computed_at: + type: string + title: Computed At + days: + type: integer + title: Days + captured: + additionalProperties: true + type: object + title: Captured + funded: + additionalProperties: true + type: object + title: Funded + refunded: + additionalProperties: true + type: object + title: Refunded + recurring: + additionalProperties: true + type: object + title: Recurring + balances_micro: + additionalProperties: + additionalProperties: + type: integer + type: object + type: object + title: Balances Micro + by_day: + items: + additionalProperties: true + type: object + type: array + title: By Day + data_age: + additionalProperties: true + type: object + title: Data Age + sources: + items: + additionalProperties: true + type: object + type: array + title: Sources + additionalProperties: true + type: object + required: + - computed_at + - days + - captured + - funded + - refunded + - recurring + - balances_micro + - by_day + - data_age + - sources + title: AdminRevenue + AdminStats: + properties: + computed_at: + type: string + title: Computed At + jobs_by_state: + additionalProperties: + type: integer + type: object + title: Jobs By State + by_environment: + additionalProperties: true + type: object + title: By Environment + live_sends: + additionalProperties: true + type: object + title: Live Sends + needs_you: + additionalProperties: true + type: object + title: Needs You + window: + additionalProperties: true + type: object + title: Window + totals: + additionalProperties: true + type: object + title: Totals + money_live_micro: + additionalProperties: + type: integer + type: object + title: Money Live Micro + additionalProperties: true + type: object + required: + - computed_at + - jobs_by_state + - by_environment + - live_sends + - needs_you + - window + - totals + - money_live_micro + title: AdminStats + AdminWhoami: + properties: + kind: type: string enum: - - no_provider_ref - - skipped - - poll_failed - - finalized - - retry_scheduled - - unknown - - pending - title: Outcome - job: - $ref: '#/components/schemas/AdminJob' + - user + - service + - dev + title: Kind + identity: + type: string + title: Identity + actor: + type: string + title: Actor + read_only: + type: boolean + title: Read Only additionalProperties: true type: object required: - - outcome - - job - title: ReconcileResult - ReconciliationReport: + - kind + - identity + - actor + - read_only + title: AdminWhoami + AnalyticsJourneys: + properties: + computed_at: + type: string + title: Computed At + days: + type: integer + title: Days + window: + additionalProperties: + type: string + type: object + title: Window + cohort: + type: integer + title: Cohort + funnel: + items: + additionalProperties: true + type: object + type: array + title: Funnel + leakiest: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Leakiest + doors: + items: + additionalProperties: true + type: object + type: array + title: Doors + topups: + additionalProperties: true + type: object + title: Topups + site: + additionalProperties: true + type: object + title: Site + organizations: + items: + additionalProperties: true + type: object + type: array + title: Organizations + listed: + type: integer + title: Listed + additionalProperties: true + type: object + required: + - computed_at + - days + - window + - cohort + - funnel + - doors + - topups + - site + - organizations + - listed + title: AnalyticsJourneys + AnalyticsOrganization: + properties: + computed_at: + type: string + title: Computed At + days: + type: integer + title: Days + window: + additionalProperties: + type: string + type: object + title: Window + organization: + additionalProperties: true + type: object + title: Organization + steps: + items: + additionalProperties: true + type: object + type: array + title: Steps + members: + items: + additionalProperties: true + type: object + type: array + title: Members + doors: + items: + additionalProperties: true + type: object + type: array + title: Doors + keys: + additionalProperties: true + type: object + title: Keys + jobs: + additionalProperties: true + type: object + title: Jobs + topups: + items: + additionalProperties: true + type: object + type: array + title: Topups + inbound: + additionalProperties: true + type: object + title: Inbound + numbers: + additionalProperties: true + type: object + title: Numbers + actions: + items: + additionalProperties: true + type: object + type: array + title: Actions + recent: + items: + additionalProperties: true + type: object + type: array + title: Recent + usage: + items: + additionalProperties: true + type: object + type: array + title: Usage + tools: + items: + additionalProperties: true + type: object + type: array + title: Tools + additionalProperties: true + type: object + required: + - computed_at + - days + - window + - organization + - steps + - members + - doors + - keys + - jobs + - topups + - inbound + - numbers + - actions + - recent + - usage + - tools + title: AnalyticsOrganization + AnalyticsSource: properties: - report: + source: + type: string + title: Source + label: + type: string + title: Label + status: + type: string + title: Status + missing: + items: + type: string + type: array + title: Missing + step: + type: integer + title: Step + error: anyOf: - - additionalProperties: true - type: object + - type: string - type: 'null' - title: Report - last_day: + title: Error + last_pulled_at: anyOf: - type: string - type: 'null' - title: Last Day - additionalProperties: true - type: object - required: - - report - - last_day - title: ReconciliationReport - ReleaseRequest: - properties: - confirm: + title: Last Pulled At + latest_day: anyOf: - type: string - type: 'null' - title: Confirm - description: The number itself, typed out, to confirm. - additionalProperties: false + title: Latest Day + additionalProperties: true type: object - title: ReleaseRequest - ReleaseResult: + required: + - source + - label + - status + - missing + - step + title: AnalyticsSource + AnalyticsSources: properties: - settlement: + items: + items: + $ref: '#/components/schemas/AnalyticsSource' + type: array + title: Items + pull: additionalProperties: true type: object - title: Settlement - job: - $ref: '#/components/schemas/AdminJob' + title: Pull additionalProperties: true type: object required: - - settlement - - job - title: ReleaseResult - Requested: + - items + - pull + title: AnalyticsSources + AnalyticsUsage: properties: - requested: - type: boolean - title: Requested - kind: - type: string - enum: - - export - - deletion - title: Kind - message: + computed_at: type: string - title: Message + title: Computed At + days: + type: integer + title: Days + window: + additionalProperties: + type: string + type: object + title: Window + org_id: + anyOf: + - type: string + - type: 'null' + title: Org Id + totals: + additionalProperties: true + type: object + title: Totals + by_day: + items: + additionalProperties: true + type: object + type: array + title: By Day + by_surface: + items: + additionalProperties: true + type: object + type: array + title: By Surface + by_family: + items: + additionalProperties: true + type: object + type: array + title: By Family + top_organizations: + items: + additionalProperties: true + type: object + type: array + title: Top Organizations + top_keys: + items: + additionalProperties: true + type: object + type: array + title: Top Keys + tools: + additionalProperties: true + type: object + title: Tools + data_age: + additionalProperties: true + type: object + title: Data Age additionalProperties: true type: object required: - - requested - - kind - - message - title: Requested - ReviewAccessAction: - properties: - reason: - type: string - maxLength: 500 - minLength: 3 - title: Reason - description: 'Why: recorded on the audit row' - additionalProperties: false - type: object - required: - - reason - title: ReviewAccessAction - ReviewAccessCreate: + - computed_at + - days + - window + - totals + - by_day + - by_surface + - by_family + - top_organizations + - top_keys + - tools + - data_age + title: AnalyticsUsage + AnalyticsWebsite: properties: - reason: - type: string - maxLength: 500 - minLength: 3 - title: Reason - description: 'Why: recorded on the audit row' - email: - type: string - format: email - title: Email - label: + computed_at: type: string - maxLength: 120 - minLength: 1 - title: Label - default: Directory review - ttl_days: + title: Computed At + days: type: integer - maximum: 90.0 - minimum: 1.0 - title: Ttl Days - default: 30 - additionalProperties: false + title: Days + window: + additionalProperties: + type: string + type: object + title: Window + sources: + items: + $ref: '#/components/schemas/AnalyticsSource' + type: array + title: Sources + search: + additionalProperties: true + type: object + title: Search + traffic: + additionalProperties: true + type: object + title: Traffic + site: + additionalProperties: true + type: object + title: Site + ux: + additionalProperties: true + type: object + title: Ux + bing: + additionalProperties: true + type: object + title: Bing + authority: + additionalProperties: true + type: object + title: Authority + data_age: + additionalProperties: true + type: object + title: Data Age + additionalProperties: true type: object required: - - reason - - email - title: ReviewAccessCreate - ReviewAccessIssued: + - computed_at + - days + - window + - sources + - search + - traffic + - site + - ux + - bing + - authority + - data_age + title: AnalyticsWebsite + AuditEvent: properties: id: type: string title: Id - email: + org_id: + anyOf: + - type: string + - type: 'null' + title: Org Id + actor: type: string - title: Email - label: + title: Actor + action: type: string - title: Label - code: + title: Action + resource_type: type: string - title: Code - expires_at: + title: Resource Type + resource_id: + anyOf: + - type: string + - type: 'null' + title: Resource Id + created_at: type: string - title: Expires At + title: Created At additionalProperties: true type: object required: - id - - email - - label - - code - - expires_at - title: ReviewAccessIssued - ReviewSignIn: - properties: - email: - type: string - format: email - title: Email - code: - type: string - maxLength: 256 - minLength: 1 - format: password - title: Code - writeOnly: true - additionalProperties: false - type: object - required: - - email - - code - title: ReviewSignIn - Revoked: - properties: - revoked: - type: integer - title: Revoked - additionalProperties: true - type: object - required: - - revoked - title: Revoked - RouteList: + - actor + - action + - resource_type + - created_at + title: AuditEvent + AuditEventPage: properties: items: items: - $ref: '#/components/schemas/RouteState' + $ref: '#/components/schemas/AuditEvent' type: array title: Items + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor additionalProperties: true type: object required: - items - title: RouteList - RouteState: + title: AuditEventPage + Client: properties: - route: + id: type: string - title: Route - status: + title: Id + client_id: + type: string + title: Client Id + kind: type: string enum: - - paused - - open - - breaker_open - title: Status - reason: + - static + - dynamic + - cimd + title: Kind + client_name: anyOf: - type: string - type: 'null' - title: Reason - actor: + title: Client Name + client_host: type: string - title: Actor - updated_at: + title: Client Host + created_at: type: string - title: Updated At - paused_at: + title: Created At + last_used_at: anyOf: - type: string - type: 'null' - title: Paused At - open_until: + title: Last Used At + disabled_at: anyOf: - type: string - type: 'null' - title: Open Until - additionalProperties: true - type: object - required: - - route - - status - - actor - - updated_at - title: RouteState - SandboxFixture: - properties: - id: - type: string - title: Id - scenario: - type: string - title: Scenario - destination: + title: Disabled At + disabled_reason: anyOf: - type: string - type: 'null' - title: Destination - created_at: - type: string - title: Created At - expires_at: - type: string - title: Expires At + title: Disabled Reason additionalProperties: true type: object required: - id - - scenario - - destination + - client_id + - kind + - client_name + - client_host - created_at - - expires_at - title: SandboxFixture - SandboxInboundCreate: + - last_used_at + - disabled_at + - disabled_reason + title: Client + ClientList: properties: - to: - type: string - title: To - from: + items: + items: + $ref: '#/components/schemas/Client' + type: array + title: Items + next_cursor: anyOf: - type: string - type: 'null' - title: From - pages: - type: integer - maximum: 200.0 - minimum: 1.0 - title: Pages - default: 1 - partial_content: - type: boolean - title: Partial Content - description: Rehearse a cut-off transmission. - default: false - additionalProperties: false - type: object - required: - - to - title: SandboxInboundCreate - SandboxReset: - properties: - reset: - type: boolean - title: Reset - deleted: - additionalProperties: - type: integer - type: object - title: Deleted - wallet_available_micro: + title: Next Cursor + total: type: integer - title: Wallet Available Micro - additionalProperties: true - type: object - required: - - reset - - deleted - - wallet_available_micro - title: SandboxReset - SandboxScenarioCreate: - properties: - scenario: - type: string - title: Scenario - destination: - anyOf: - - type: string - - type: 'null' - title: Destination - description: Apply to one destination; omit for every send. - additionalProperties: false - type: object - required: - - scenario - title: SandboxScenarioCreate - SandboxScenarios: - properties: - scenarios: - items: - additionalProperties: - type: string - type: object - type: array - title: Scenarios - destinations: - items: - additionalProperties: - type: string - type: object - type: array - title: Destinations - fixtures: - items: - $ref: '#/components/schemas/SandboxFixture' - type: array - title: Fixtures + minimum: 0.0 + title: Total additionalProperties: true type: object required: - - scenarios - - destinations - - fixtures - title: SandboxScenarios - SchemaCreate: + - items + - total + title: ClientList + MagicLinkRequest: properties: - name: + email: type: string - maxLength: 120 - minLength: 1 - title: Name - description: + format: email + title: Email + next: anyOf: - type: string - maxLength: 500 + maxLength: 400 - type: 'null' - title: Description - schema: - additionalProperties: true - type: object - title: Schema + title: Next + description: An in-app path to open after sign-in. additionalProperties: false type: object required: - - name - - schema - title: SchemaCreate - SenderVerification: + - email + title: MagicLinkRequest + OAuthConsent: properties: id: type: string title: Id - environment: + client: + $ref: '#/components/schemas/OAuthConsentClient' + redirect_host: + type: string + title: Redirect Host + scopes_requested: + items: + type: string + type: array + title: Scopes Requested + organizations: + items: + $ref: '#/components/schemas/OAuthConsentOrganization' + type: array + title: Organizations + default_environment: type: string enum: - live - test - title: Environment - from: - type: string - title: From - status: - type: string - title: Status - method: - type: string - title: Method - number_id: - anyOf: - - type: string - - type: 'null' - title: Number Id - created_at: + title: Default Environment + expires_at: type: string - title: Created At - verified_at: - anyOf: - - type: string - - type: 'null' - title: Verified At + title: Expires At additionalProperties: true type: object required: - id - - environment - - from - - status - - method - - number_id - - created_at - - verified_at - title: SenderVerification - SenderVerificationCreate: + - client + - redirect_host + - scopes_requested + - organizations + - default_environment + - expires_at + title: OAuthConsent + OAuthConsentClient: properties: - from: + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: The client's own name, shown as text beside the host. + host: type: string - title: From - description: A number your organization owns, E.164. - additionalProperties: false - type: object - required: - - from - title: SenderVerificationCreate - Sent: - properties: - sent: + title: Host + description: 'The host the person is sending a credential to: the trust anchor.' + loopback: type: boolean - title: Sent - message: - type: string - title: Message + title: Loopback + description: The redirect goes to the person's own computer (an app they started). + first_seen: + type: boolean + title: First Seen + description: This client was registered during this request. additionalProperties: true type: object required: - - sent - - message - title: Sent - ServiceStatus: + - name + - host + - loopback + - first_seen + title: OAuthConsentClient + OAuthConsentDecision: properties: - status: - type: string - enum: - - ok - - degraded - title: Status - version: + org_id: type: string - title: Version + maxLength: 64 + minLength: 1 + title: Org Id environment: type: string enum: - live - test title: Environment - provider: - type: string - title: Provider - database: - type: boolean - title: Database - worker_beat_age_s: - anyOf: - - type: integer - - type: 'null' - title: Worker Beat Age S - status_page: - anyOf: - - type: string - - type: 'null' - title: Status Page - additionalProperties: true + default: test + additionalProperties: false type: object required: - - status - - version - - environment - - provider - - database - title: ServiceStatus - SessionInfo: + - org_id + title: OAuthConsentDecision + OAuthConsentOrganization: properties: id: type: string title: Id - auth_method: - type: string - title: Auth Method - authenticated_at: - type: string - title: Authenticated At - fresh_until: + name: type: string - title: Fresh Until - fresh: - type: boolean - title: Fresh - expires_at: + title: Name + role: type: string - title: Expires At + title: Role + scopes: + items: + type: string + type: array + title: Scopes + description: What the grant would carry for this organization and role. additionalProperties: true type: object required: - id - - auth_method - - authenticated_at - - fresh_until - - fresh - - expires_at - title: SessionInfo - SessionList: + - name + - role + - scopes + title: OAuthConsentOrganization + OAuthRedirect: properties: - items: - items: - $ref: '#/components/schemas/SessionOut' - type: array - title: Items + redirect_to: + type: string + title: Redirect To + description: 'Where the browser goes next: the client''s registered redirect URI.' additionalProperties: true type: object required: - - items - title: SessionList - SessionOut: + - redirect_to + title: OAuthRedirect + OutboxDiscarded: properties: id: type: string title: Id - current: + discarded: type: boolean - title: Current - auth_method: - type: string - title: Auth Method - ip: - anyOf: - - type: string - - type: 'null' - title: Ip - user_agent: - anyOf: - - type: string - - type: 'null' - title: User Agent - created_at: - type: string - title: Created At - authenticated_at: - type: string - title: Authenticated At - last_seen_at: - type: string - title: Last Seen At - expires_at: - type: string - title: Expires At + title: Discarded additionalProperties: true type: object required: - id - - current - - auth_method - - ip - - user_agent - - created_at - - authenticated_at - - last_seen_at - - expires_at - title: SessionOut - SignedUrl: + - discarded + title: OutboxDiscarded + OutboxPage: properties: - url: - type: string - title: Url - expires_at: - type: string - title: Expires At - content_type: - type: string - title: Content Type + items: + items: + $ref: '#/components/schemas/OutboxRow' + type: array + title: Items + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor additionalProperties: true type: object required: - - url - - expires_at - - content_type - title: SignedUrl - Subscription: + - items + title: OutboxPage + OutboxRow: properties: id: type: string title: Id - product: + kind: type: string - title: Product + title: Kind status: type: string + enum: + - queued + - running + - done + - failed + - dead title: Status - stripe_subscription_id: - type: string - title: Stripe Subscription Id - stripe_price_id: + title: anyOf: - type: string - type: 'null' - title: Stripe Price Id - cancel_at_period_end: - type: boolean - title: Cancel At Period End - current_period_end: + title: Title + error: anyOf: - type: string - type: 'null' - title: Current Period End - entitled: - type: boolean - title: Entitled + title: Error + attempts: + type: integer + title: Attempts + max_attempts: + type: integer + title: Max Attempts + org_id: + anyOf: + - type: string + - type: 'null' + title: Org Id created_at: type: string title: Created At - updated_at: - type: string - title: Updated At - canceled_at: + finished_at: anyOf: - type: string - type: 'null' - title: Canceled At + title: Finished At + age_s: + type: integer + title: Age S additionalProperties: true type: object required: - id - - product + - kind - status - - stripe_subscription_id - - stripe_price_id - - cancel_at_period_end - - current_period_end - - entitled + - attempts + - max_attempts - created_at - - updated_at - - canceled_at - title: Subscription - SubscriptionCheckout: + - age_s + title: OutboxRow + Passkey: properties: - url: - type: string - title: Url - stripe_session_id: + id: type: string - title: Stripe Session Id - product: + title: Id + label: + anyOf: + - type: string + - type: 'null' + title: Label + aaguid: + anyOf: + - type: string + - type: 'null' + title: Aaguid + transports: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Transports + backup_eligible: + type: boolean + title: Backup Eligible + created_at: type: string - title: Product + title: Created At + last_used_at: + anyOf: + - type: string + - type: 'null' + title: Last Used At additionalProperties: true type: object required: - - url - - stripe_session_id - - product - title: SubscriptionCheckout - SubscriptionList: + - id + - label + - aaguid + - transports + - backup_eligible + - created_at + - last_used_at + title: Passkey + PasskeyList: properties: items: items: - $ref: '#/components/schemas/Subscription' + $ref: '#/components/schemas/Passkey' type: array title: Items - workspace: - type: boolean - title: Workspace - next_cursor: - anyOf: - - type: string - - type: 'null' - title: Next Cursor additionalProperties: true type: object required: - items - - workspace - title: SubscriptionList - SummaryCreate: + title: PasskeyList + PasskeyLoginVerify: properties: - inbox_item_id: + credential: + additionalProperties: true + type: object + title: Credential + additionalProperties: false + type: object + required: + - credential + title: PasskeyLoginVerify + PasskeyRegisterVerify: + properties: + credential: + additionalProperties: true + type: object + title: Credential + label: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ + maxLength: 80 - type: 'null' - title: Inbox Item Id - document_id: + title: Label + additionalProperties: false + type: object + required: + - credential + title: PasskeyRegisterVerify + ProviderHealth: + properties: + name: + type: string + title: Name + configured: + type: boolean + title: Configured + serves: + items: + type: string + type: array + title: Serves + default: [] + circuit: + type: string + title: Circuit + routes_paused: + items: + type: string + type: array + title: Routes Paused + breakers: + items: + additionalProperties: true + type: object + type: array + title: Breakers + default: [] + last_success_at: anyOf: - type: string - pattern: ^[a-z]{2,8}_[0-9a-f]{32}$ - type: 'null' - title: Document Id - max_pages: + title: Last Success At + last_failure_at: anyOf: - - type: integer - maximum: 200.0 - minimum: 1.0 + - type: string - type: 'null' - title: Max Pages - strict: + title: Last Failure At + concurrency_in_use: + type: integer + title: Concurrency In Use + additionalProperties: true + type: object + required: + - name + - configured + - circuit + - routes_paused + - concurrency_in_use + title: ProviderHealth + ProviderList: + properties: + items: + items: + $ref: '#/components/schemas/ProviderHealth' + type: array + title: Items + additionalProperties: true + type: object + required: + - items + title: ProviderList + Providers: + properties: + magic_link: + type: boolean + title: Magic Link + default: true + passkeys: type: boolean - title: Strict - description: Refuse with page_limit_exceeded when the document has more pages than would be read, instead - of reading the first ones and warning. - default: false - strong_model_if_below: - type: number - maximum: 1.0 - minimum: 0.0 - title: Strong Model If Below - default: 0.75 - additionalProperties: false + title: Passkeys + default: true + github: + type: boolean + title: Github + google: + type: boolean + title: Google + additionalProperties: true type: object - title: SummaryCreate - SwitchOrganization: + required: + - github + - google + title: Providers + Reauth: properties: - org_id: + method: type: string - title: Org Id + enum: + - passkey + - magic_link + title: Method + credential: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Credential additionalProperties: false type: object required: - - org_id - title: SwitchOrganization - TelnyxAck: + - method + title: Reauth + ReconcileResult: properties: - received: - type: boolean - title: Received outcome: type: string + enum: + - no_provider_ref + - skipped + - poll_failed + - finalized + - retry_scheduled + - unknown + - pending title: Outcome - event_id: - anyOf: - - type: string - - type: 'null' - title: Event Id + job: + $ref: '#/components/schemas/AdminJob' additionalProperties: true type: object required: - - received - outcome - title: TelnyxAck - TopupCreate: - properties: - amount_usd: - type: integer - maximum: 1000.0 - minimum: 10.0 - title: Amount Usd - description: Whole US dollars, 10 to 1000 per session. - additionalProperties: false - type: object - required: - - amount_usd - title: TopupCreate - TopupSession: + - job + title: ReconcileResult + ReconciliationReport: properties: - id: - type: string - title: Id - environment: - type: string - enum: - - live - - test - title: Environment - kind: - type: string - enum: - - manual - - auto - - setup - title: Kind - amount_micro: - type: integer - title: Amount Micro - currency: - type: string - title: Currency - status: - type: string - enum: - - open - - completed - - expired - - canceled - - failed - title: Status - url: - anyOf: - - type: string - - type: 'null' - title: Url - description: The hosted Checkout page while the session is open. - stripe_session_id: - anyOf: - - type: string - - type: 'null' - title: Stripe Session Id - stripe_payment_intent_id: - anyOf: - - type: string - - type: 'null' - title: Stripe Payment Intent Id - auto_topup_id: - anyOf: - - type: string - - type: 'null' - title: Auto Topup Id - error: - anyOf: - - type: string - - type: 'null' - title: Error - created_at: - type: string - title: Created At - expires_at: + report: anyOf: - - type: string + - additionalProperties: true + type: object - type: 'null' - title: Expires At - completed_at: + title: Report + last_day: anyOf: - type: string - type: 'null' - title: Completed At + title: Last Day additionalProperties: true type: object required: - - id - - environment - - kind - - amount_micro - - currency - - status - - stripe_session_id - - stripe_payment_intent_id - - auto_topup_id - - error - - created_at - - expires_at - - completed_at - title: TopupSession - TopupSessionPage: + - report + - last_day + title: ReconciliationReport + ReleaseResult: properties: - items: - items: - $ref: '#/components/schemas/TopupSession' - type: array - title: Items - next_cursor: - anyOf: - - type: string - - type: 'null' - title: Next Cursor + settlement: + additionalProperties: true + type: object + title: Settlement + job: + $ref: '#/components/schemas/AdminJob' additionalProperties: true type: object required: - - items - title: TopupSessionPage - UploadComplete: + - settlement + - job + title: ReleaseResult + ReviewAccessAction: properties: - sha256: - anyOf: - - type: string - maxLength: 64 - minLength: 64 - - type: 'null' - title: Sha256 - description: 'Optional: fail if the bytes differ.' + reason: + type: string + maxLength: 500 + minLength: 3 + title: Reason + description: 'Why: recorded on the audit row' additionalProperties: false type: object - title: UploadComplete - UploadCreate: + required: + - reason + title: ReviewAccessAction + ReviewAccessCreate: properties: - filename: + reason: type: string - maxLength: 255 - minLength: 1 - title: Filename - content_type: + maxLength: 500 + minLength: 3 + title: Reason + description: 'Why: recorded on the audit row' + email: type: string - maxLength: 100 - title: Content Type - description: application/pdf, image/png, image/jpeg or image/tiff. An image becomes 8-bit gray letter - pages, since fax is monochrome. A frame wider than it is tall is rotated. A frame above 300 dpi letter - is downsampled. Every TIFF frame is a page. PNG and JPEG take the first frame. The bytes must be the - declared type. - default: application/pdf - size_bytes: + format: email + title: Email + label: + type: string + maxLength: 120 + minLength: 1 + title: Label + default: Directory review + ttl_days: type: integer + maximum: 90.0 minimum: 1.0 - title: Size Bytes + title: Ttl Days + default: 30 additionalProperties: false type: object - required: - - filename - - size_bytes - title: UploadCreate - UploadSession: + required: + - reason + - email + title: ReviewAccessCreate + ReviewAccessIssued: properties: id: type: string title: Id - status: - type: string - title: Status - filename: + email: type: string - title: Filename - content_type: + title: Email + label: type: string - title: Content Type - declared_size: - type: integer - title: Declared Size - received_size: - type: integer - title: Received Size - sha256: - anyOf: - - type: string - - type: 'null' - title: Sha256 - created_at: + title: Label + code: type: string - title: Created At + title: Code expires_at: type: string title: Expires At - completed_at: - anyOf: - - type: string - - type: 'null' - title: Completed At - upload_url: - anyOf: - - type: string - - type: 'null' - title: Upload Url - upload_method: - anyOf: - - type: string - - type: 'null' - title: Upload Method - upload_url_expires_at: - anyOf: - - type: string - - type: 'null' - title: Upload Url Expires At additionalProperties: true type: object required: - id - - status - - filename - - content_type - - declared_size - - received_size - - sha256 - - created_at + - email + - label + - code - expires_at - - completed_at - title: UploadSession - UsageExport: + title: ReviewAccessIssued + ReviewSignIn: properties: - id: - type: string - title: Id - environment: + email: type: string - enum: - - live - - test - title: Environment - status: + format: email + title: Email + code: type: string - enum: - - ready - - expired - title: Status - params: - additionalProperties: true - type: object - title: Params - row_count: + maxLength: 256 + minLength: 1 + format: password + title: Code + writeOnly: true + additionalProperties: false + type: object + required: + - email + - code + title: ReviewSignIn + Revoked: + properties: + revoked: type: integer - title: Row Count - content_type: - type: string - title: Content Type - url: - anyOf: - - type: string - - type: 'null' - title: Url - created_at: - type: string - title: Created At - expires_at: - type: string - title: Expires At + title: Revoked additionalProperties: true type: object required: - - id - - environment - - status - - params - - row_count - - content_type - - url - - created_at - - expires_at - title: UsageExport - UsageExportCreate: + - revoked + title: Revoked + RouteList: properties: - from: - anyOf: - - type: string - - type: 'null' - title: From - description: ISO date; default 30 days ago. - to: - anyOf: - - type: string - - type: 'null' - title: To - description: ISO date; default today. - additionalProperties: false + items: + items: + $ref: '#/components/schemas/RouteState' + type: array + title: Items + additionalProperties: true type: object - title: UsageExportCreate - UsageItem: + required: + - items + title: RouteList + RouteState: properties: - day: - anyOf: - - type: string - - type: 'null' - title: Day - direction: - anyOf: - - type: string - - type: 'null' - title: Direction route: + type: string + title: Route + status: + type: string + enum: + - paused + - open + - breaker_open + title: Status + reason: anyOf: - type: string - type: 'null' - title: Route - destination: + title: Reason + actor: + type: string + title: Actor + updated_at: + type: string + title: Updated At + paused_at: anyOf: - type: string - type: 'null' - title: Destination - project_id: + title: Paused At + open_until: anyOf: - type: string - type: 'null' - title: Project Id - pages: - type: integer - title: Pages - jobs: - type: integer - title: Jobs - amount_micro: - type: integer - title: Amount Micro + title: Open Until additionalProperties: true type: object required: - - pages - - jobs - - amount_micro - title: UsageItem - UsageReport: + - route + - status + - actor + - updated_at + title: RouteState + Sent: properties: - environment: - type: string - enum: - - live - - test - title: Environment - from: - type: string - title: From - to: - type: string - title: To - group_by: - items: - type: string - type: array - title: Group By - currency: + sent: + type: boolean + title: Sent + message: type: string - title: Currency - items: - items: - $ref: '#/components/schemas/UsageItem' - type: array - title: Items - totals: - additionalProperties: - type: integer - type: object - title: Totals + title: Message additionalProperties: true type: object required: - - environment - - from - - to - - group_by - - currency - - items - - totals - title: UsageReport - UserOut: + - sent + - message + title: Sent + SessionInfo: properties: id: type: string title: Id - email: + auth_method: type: string - title: Email - name: - anyOf: - - type: string - - type: 'null' - title: Name - email_verified: + title: Auth Method + authenticated_at: + type: string + title: Authenticated At + fresh_until: + type: string + title: Fresh Until + fresh: type: boolean - title: Email Verified - created_at: + title: Fresh + expires_at: type: string - title: Created At - last_login_at: - anyOf: - - type: string - - type: 'null' - title: Last Login At + title: Expires At additionalProperties: true type: object required: - id - - email - - name - - email_verified - - created_at - - last_login_at - title: UserOut - ValidationError: + - auth_method + - authenticated_at + - fresh_until + - fresh + - expires_at + title: SessionInfo + SessionList: properties: - loc: + items: items: - anyOf: - - type: string - - type: integer + $ref: '#/components/schemas/SessionOut' type: array - title: Location - msg: - type: string - title: Message - type: - type: string - title: Error Type - input: - title: Input - ctx: - type: object - title: Context + title: Items + additionalProperties: true type: object required: - - loc - - msg - - type - title: ValidationError - Webhook: + - items + title: SessionList + SessionOut: properties: id: type: string title: Id - url: + current: + type: boolean + title: Current + auth_method: type: string - title: Url - description: + title: Auth Method + ip: anyOf: - type: string - type: 'null' - title: Description - event_types: - items: - type: string - type: array - title: Event Types - status: - type: string - title: Status - previous_secret_expires_at: + title: Ip + user_agent: anyOf: - type: string - type: 'null' - title: Previous Secret Expires At + title: User Agent created_at: type: string title: Created At - updated_at: + authenticated_at: type: string - title: Updated At + title: Authenticated At + last_seen_at: + type: string + title: Last Seen At + expires_at: + type: string + title: Expires At additionalProperties: true type: object required: - id - - url - - description - - event_types - - status - - previous_secret_expires_at + - current + - auth_method + - ip + - user_agent - created_at - - updated_at - title: Webhook - WebhookAck: + - authenticated_at + - last_seen_at + - expires_at + title: SessionOut + SwitchOrganization: + properties: + org_id: + type: string + title: Org Id + additionalProperties: false + type: object + required: + - org_id + title: SwitchOrganization + TelnyxAck: properties: received: type: boolean title: Received - default: true outcome: type: string title: Outcome - additionalProperties: true - type: object - required: - - outcome - title: WebhookAck - WebhookCreate: - properties: - url: - type: string - maxLength: 2000 - title: Url - description: + event_id: anyOf: - type: string - maxLength: 200 - - type: 'null' - title: Description - event_types: - anyOf: - - items: - type: string - type: array - type: 'null' - title: Event Types - description: 'Empty or omitted: every event type.' - additionalProperties: false - type: object - required: - - url - title: WebhookCreate - WebhookList: - properties: - items: - items: - $ref: '#/components/schemas/Webhook' - type: array - title: Items + title: Event Id additionalProperties: true type: object required: - - items - title: WebhookList - WebhookUpdate: - properties: - url: - anyOf: - - type: string - maxLength: 2000 - - type: 'null' - title: Url - description: - anyOf: - - type: string - maxLength: 200 - - type: 'null' - title: Description - event_types: - anyOf: - - items: - type: string - type: array - - type: 'null' - title: Event Types - status: - anyOf: - - type: string - enum: - - active - - paused - - type: 'null' - title: Status - additionalProperties: false - type: object - title: WebhookUpdate - WebhookWithSecret: + - received + - outcome + title: TelnyxAck + UserOut: properties: id: type: string title: Id - url: + email: type: string - title: Url - description: + title: Email + name: anyOf: - type: string - type: 'null' - title: Description - event_types: - items: - type: string - type: array - title: Event Types - status: + title: Name + email_verified: + type: boolean + title: Email Verified + created_at: type: string - title: Status - previous_secret_expires_at: + title: Created At + last_login_at: anyOf: - type: string - type: 'null' - title: Previous Secret Expires At - created_at: - type: string - title: Created At - updated_at: - type: string - title: Updated At - secret: - type: string - title: Secret - description: whsec_... Shown once. Verify webhook-signature with it. + title: Last Login At additionalProperties: true type: object required: - id - - url - - description - - event_types - - status - - previous_secret_expires_at + - email + - name + - email_verified - created_at - - updated_at - - secret - title: WebhookWithSecret + - last_login_at + title: UserOut + WebhookAck: + properties: + received: + type: boolean + title: Received + default: true + outcome: + type: string + title: Outcome + additionalProperties: true + type: object + required: + - outcome + title: WebhookAck faxforagents__api__routes__inbox__InboxItem: properties: id: diff --git a/src/faxforagents/__init__.py b/src/faxforagents/__init__.py index b65d253..9e0c911 100644 --- a/src/faxforagents/__init__.py +++ b/src/faxforagents/__init__.py @@ -18,7 +18,7 @@ from __future__ import annotations -__version__ = "0.4.1" +__version__ = "0.5.0" from faxforagents._http import ORDER_TOKEN_HEADER from faxforagents.async_client import AsyncClient diff --git a/src/faxforagents/async_client.py b/src/faxforagents/async_client.py index e7c7243..80fba24 100644 --- a/src/faxforagents/async_client.py +++ b/src/faxforagents/async_client.py @@ -116,7 +116,7 @@ async def create_upload( content_type: str = "application/pdf", idempotency_key: str | None = None, ) -> m.UploadSession: - """Open an upload session with a signed PUT URL (25 MB, one hour). ``content_type`` is + """Open an upload session with a signed PUT URL (25 MiB, one hour). ``content_type`` is application/pdf, image/png, image/jpeg or image/tiff. Scope: document:write.""" body = m.UploadCreate(filename=filename, size_bytes=size_bytes, content_type=content_type) return await self._h.request( diff --git a/src/faxforagents/client.py b/src/faxforagents/client.py index c3236e9..381b40c 100644 --- a/src/faxforagents/client.py +++ b/src/faxforagents/client.py @@ -165,7 +165,7 @@ def create_upload( content_type: str = "application/pdf", idempotency_key: str | None = None, ) -> m.UploadSession: - """Open an upload session with a signed PUT URL (25 MB, one hour). ``content_type`` is + """Open an upload session with a signed PUT URL (25 MiB, one hour). ``content_type`` is application/pdf, image/png, image/jpeg or image/tiff. Scope: document:write.""" body = m.UploadCreate(filename=filename, size_bytes=size_bytes, content_type=content_type) return self._h.request( diff --git a/src/faxforagents/models.py b/src/faxforagents/models.py index 072f24d..3ce7325 100644 --- a/src/faxforagents/models.py +++ b/src/faxforagents/models.py @@ -1,6 +1,6 @@ """Typed models of the Fax for Agents API. -GENERATED by scripts/gen_models.py from spec/openapi.yaml (API version 1.17.0). Do not edit by hand. +GENERATED by scripts/gen_models.py from spec/openapi.yaml (API version 1.18.0). Do not edit by hand. Money fields ending in ``_micro`` are integer USD micro-units (39000 is $0.039). Timestamps are ISO 8601 strings in UTC. Response models accept fields the API adds later. Request models refuse unknown fields. """ @@ -720,8 +720,16 @@ class EffectivePolicies(_Response): rules_order: list[str] +class ErrorBody(_Response): + code: str = Field(..., description="A stable code such as invalid_token, scope_missing, not_found, quote_expired, insufficient_balance, approval_required, rate_limited, live_provider_unavailable, one_time_unavailable.") + message: str = Field(..., description="One sentence a person can act on.") + retryable: bool + correlation_id: str | None = Field(None, description="The X-Request-Id of the request. Quote it when you write to hello@faxforagents.com.") + details: Any | None = Field(None, description="Code-specific fields, for example details.scope on scope_missing.") + + class ErrorEnvelope(_Response): - error: dict[str, Any] + error: ErrorBody class Event(_Response): @@ -911,18 +919,6 @@ class GrantList(_Response): next_cursor: str | None = None -class ValidationError(_Response): - loc: list[str | int] - msg: str - type: str - input: Any | None = None - ctx: dict[str, Any] | None = None - - -class HTTPValidationError(_Response): - detail: list[ValidationError] | None = None - - class InboxItem(_Response): id: str from_: str | None = Field(None, alias="from") @@ -1623,7 +1619,7 @@ class QuoteCreate(_Request): from_: str | None = Field(None, alias="from", description="A number you own; omit for the shared pool.") cover: dict[str, Any] | None = Field(None, description="Cover sheet fields: to_name, from_name, subject, message. Counts as a page.") quality: Literal["standard", "fine", "superfine", "ultra"] = Field("fine", description="Fax resolution. standard is the fax standard's 204 by 98 dpi, fine (the default) 204 by 196, superfine 204 by 392. ultra asks the carrier for its darkest text processing at the same superfine resolution and takes longer to process: measured 2026-11-09, a page sent at ultra and one at superfine both arrived as 1728 by 4112 pixels, 204 by 391 dpi. The price does not change. The job echoes the level.") - sender_name: str | None = Field(None, description="The station name the carrier prints in the fax header, next to the sending number. Letters, digits, spaces and - _ ~ ! . + only, at most 128 characters. Omit to show the number alone.") + sender_name: str | None = Field(None, description="The name that identifies the sender. The carrier gets it as the caller name for its header line. A fax without a cover sheet prints it in one line at the top of page one. The line also gives the sending number and the time in UTC. Letters, digits, spaces and - _ ~ ! . + only, at most 128 characters. Omit to use the organization's name.") delete_after_send: bool = Field(False, description="Delete the document and the transmitted copy the moment the fax ends in delivered, partial or failed. The job, its receipt and the carrier evidence stay; they hold no document content. A fax that ends unknown keeps the document until a reconcile settles it. Default: keep the document for the retention period.") @@ -2141,6 +2137,7 @@ class faxforagents__auth__schemas__Me(_Response): "DocumentValidation", "Policy", "EffectivePolicies", + "ErrorBody", "ErrorEnvelope", "Event", "EventPage", @@ -2157,8 +2154,6 @@ class faxforagents__auth__schemas__Me(_Response): "FaxJobPage", "Grant", "GrantList", - "ValidationError", - "HTTPValidationError", "InboxItem", "InboxItemDetail", "InboxItemSummary", diff --git a/tests/test_client.py b/tests/test_client.py index fec7b9b..9681005 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -14,6 +14,7 @@ AuthenticationError, Client, ConflictError, + InvalidRequestError, NotFoundError, PaymentRequiredError, RateLimitedError, @@ -156,6 +157,58 @@ def test_error_envelope_maps_to_typed_exceptions( assert "req_1" in str(err) +def test_validation_and_upload_queue_are_the_envelope(api: respx.MockRouter) -> None: + """API 1.18.0 declares every error as the envelope. A field that fails validation is no other shape.""" + api.post("/v1/fax-quotes").respond( + 422, + json={ + "error": { + "code": "invalid_request", + "message": "to is not a number", + "retryable": False, + "correlation_id": None, + "details": {"field": "to"}, + } + }, + ) + api.post("/v1/one-time-sends").respond( + 429, + json={ + "error": { + "code": "rate_limited", + "message": "uploads are queued", + "retryable": True, + "correlation_id": "req_2", + "details": {"cap": "upload_queue"}, + } + }, + headers={"Retry-After": "5"}, + ) + with Client(KEY, base_url=BASE, max_retries=0) as c: + with pytest.raises(InvalidRequestError) as invalid: + c.quotes.create(document_id="doc_1", to="x") + assert invalid.value.status == 422 and invalid.value.code == "invalid_request" + assert invalid.value.retryable is False and invalid.value.correlation_id is None + assert invalid.value.details == {"field": "to"} + with pytest.raises(RateLimitedError) as queued: + c.one_time_sends.create( + to="+12025550100", sender_name="Ada", accept_aup=True, email="a@example.com", text="x" + ) + assert queued.value.retryable is True and queued.value.retry_after == 5.0 + assert queued.value.correlation_id == "req_2" and queued.value.details == {"cap": "upload_queue"} + + +def test_error_envelope_model_reads_the_body() -> None: + from faxforagents.models import ErrorBody, ErrorEnvelope + + env = ErrorEnvelope.model_validate({"error": {"code": "not_found", "message": "no", "retryable": False}}) + assert ( + isinstance(env.error, ErrorBody) + and env.error.code == "not_found" + and env.error.correlation_id is None + ) + + def test_non_json_error_body(client: Client, api: respx.MockRouter) -> None: api.get("/v1/faxes/fax_x").respond(404, text="not here") with pytest.raises(NotFoundError) as exc: