{ "openapi": "3.1.0", "info": { "title": "mintfax API", "version": "1.0", "description": "Developer-first fax API. Send faxes with a single API call.\n\n## Authentication\n\nMost endpoints require a Bearer token in the `Authorization` header.\n\n- **Account keys** (`mfx_acct_...`) access account-level endpoints (`/account`, `/account/balance`, `/account/transactions`, `/account/keys`).\n- **Environment keys** (`mfx_test_...` for test, `mfx_live_...` for live) access operational endpoints (`/environment`, `/faxes`, `/webhooks`, `/events`).\n- Registration endpoints (`POST /account/register` and `POST /account/register/verify`) do not require authentication.\n\n## Base URL\n\nAll API requests use `https://api.mintfax.com/v1` as the base URL.", "contact": { "name": "mintfax Support", "email": "support@mintfax.com", "url": "https://mintfax.com/docs" } }, "servers": [ { "url": "https://api.mintfax.com/v1", "description": "Production" } ], "tags": [ { "name": "Account", "description": "Account-level resources: registration, account info, balances, and API keys." }, { "name": "Environment", "description": "Test and live environment configuration shared across all operational requests." }, { "name": "Fax", "description": "Send, list, retrieve, resend, and purge faxes." }, { "name": "Events", "description": "Read the immutable event log for everything that has happened in the environment." }, { "name": "Webhooks", "description": "Manage webhook endpoints and inspect or replay individual delivery attempts." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/account": { "get": { "operationId": "getAccount", "description": "Returns account details. Requires an account-scoped key (`mfx_acct_...`).", "summary": "Get Account", "tags": [ "Account" ], "responses": { "200": { "description": "`AccountResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResource" } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_account": { "value": { "error": "key_not_scoped_for_account", "message": "This API key cannot access account-level endpoints. Use an mfx_acct_ key.", "action": "use_account_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-account" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/account/balance": { "get": { "operationId": "getAccountBalance", "description": "Returns balances for all credit pools (sandbox and live) on the account.\nRequires an account-scoped key (`mfx_acct_...`).", "summary": "Get Account Balances", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceResource" } } }, "required": [ "data" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_account": { "value": { "error": "key_not_scoped_for_account", "message": "This API key cannot access account-level endpoints. Use an mfx_acct_ key.", "action": "use_account_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-account" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/account/transactions": { "get": { "operationId": "getAccountTransactions", "description": "Returns credit transactions across all pools for the account.\nOptionally filter by `type` query param (`live` or `sandbox`).\nRequires an account-scoped key (`mfx_acct_...`).", "summary": "Get Account Transactions", "tags": [ "Account" ], "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `TransactionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionResource" } } }, "required": [ "data" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_account": { "value": { "error": "key_not_scoped_for_account", "message": "This API key cannot access account-level endpoints. Use an mfx_acct_ key.", "action": "use_account_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-account" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/account/keys": { "get": { "operationId": "listAccountKeys", "description": "Returns all API keys on the account.\nRequires an account-scoped key (`mfx_acct_...`).", "summary": "List API Keys", "tags": [ "Account" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyResource" } } }, "required": [ "data" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_account": { "value": { "error": "key_not_scoped_for_account", "message": "This API key cannot access account-level endpoints. Use an mfx_acct_ key.", "action": "use_account_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-account" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } }, "post": { "operationId": "createAccountKey", "description": "Creates a new environment-scoped API key (test or live). Account-scoped keys\ncan only be created via the dashboard. Requires an account-scoped key (`mfx_acct_...`).", "summary": "Create API Key", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "scope_kind": { "type": "string", "enum": [ "test", "live", "account" ] }, "environment_id": { "type": "string" } }, "required": [ "name", "scope_kind" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" }, "key": { "type": "object", "properties": { "id": { "type": "string", "description": "API key identifier (key_-prefixed).", "examples": [ "key_4HGhJ7K2pNm9XqL3VtR8Wz" ] }, "name": { "type": "string", "description": "Human-readable key name.", "examples": [ "Production keys" ] }, "prefix": { "type": "string", "description": "First 16 chars of the key (e.g. mfx_test_abcd1234).", "examples": [ "mfx_test_abcd1234" ] }, "scope": { "type": "object", "properties": { "environments": { "type": "array", "description": "Environment slugs the key is scoped to (empty for account-only keys).", "items": { "type": "string" } }, "abilities": { "type": "array", "description": "Abilities granted (full account-admin set for account-level keys; empty for environment keys).", "items": { "type": "string" } } }, "required": [ "environments", "abilities" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp the key was last used; null if never used." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp the key was created." } }, "required": [ "id", "name", "prefix", "scope", "last_used_at", "created_at" ] } }, "required": [ "api_key", "key" ] } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "403": { "description": "Account-level keys can only be created from the dashboard, not via API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "acct_key_creation_dashboard_only": { "value": { "error": "acct_key_creation_dashboard_only", "message": "Account-level keys can only be created from the dashboard, not via API.", "action": "use_dashboard", "docs": "https://mintfax.com/docs/errors/acct-key-creation-dashboard-only" } }, "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_account": { "value": { "error": "key_not_scoped_for_account", "message": "This API key cannot access account-level endpoints. Use an mfx_acct_ key.", "action": "use_account_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-account" } } } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/account/keys/{id}": { "delete": { "operationId": "deleteAccountKey", "description": "Permanently revokes and deletes an API key. Account-scoped keys can only be\ndeleted via the dashboard. Requires an account-scoped key (`mfx_acct_...`).", "summary": "Delete API Key", "tags": [ "Account" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "403": { "description": "Account-level keys can only be created from the dashboard, not via API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "acct_key_creation_dashboard_only": { "value": { "error": "acct_key_creation_dashboard_only", "message": "Account-level keys can only be created from the dashboard, not via API.", "action": "use_dashboard", "docs": "https://mintfax.com/docs/errors/acct-key-creation-dashboard-only" } }, "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_account": { "value": { "error": "key_not_scoped_for_account", "message": "This API key cannot access account-level endpoints. Use an mfx_acct_ key.", "action": "use_account_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-account" } } } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/environment": { "get": { "operationId": "getEnvironment", "description": "Returns details for the environment the caller's key is scoped to.\nRequires an environment key (`mfx_test_...` or `mfx_live_...`).", "summary": "Get Environment", "tags": [ "Environment" ], "responses": { "200": { "description": "`EnvironmentResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentResource" } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/environment/balance": { "get": { "operationId": "getEnvironmentBalance", "description": "Returns the account credit balance for the pool matching the caller's\nenvironment mode (sandbox or live). The pool is shared across all\nenvironments of the same mode - this endpoint exists so environment\nkeys can read \"what can I spend?\" without needing an account key.\nFor both pools at once, use `GET /account/balance`.\nRequires an environment key (`mfx_test_...` or `mfx_live_...`).", "summary": "Get Environment Balance", "tags": [ "Environment" ], "responses": { "200": { "description": "`BalanceResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceResource" } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/environment/transactions": { "get": { "operationId": "getEnvironmentTransactions", "description": "Returns credit transactions for the environment the caller's key is scoped to.\nRequires an environment key (`mfx_test_...` or `mfx_live_...`).", "summary": "Get Environment Transactions", "tags": [ "Environment" ], "responses": { "200": { "description": "Array of `TransactionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionResource" } } }, "required": [ "data" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/environment/fax-settings": { "get": { "operationId": "getFaxSettings", "description": "Returns the current default fax submission settings for the environment.\nRequires an environment key (`mfx_test_...` or `mfx_live_...`).", "summary": "Get Default Fax Settings", "tags": [ "Environment" ], "responses": { "200": { "description": "`FaxSettingsResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxSettingsResource" } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } }, "put": { "operationId": "updateFaxSettings", "description": "Set default fax submission parameters for the environment. These apply to all\nfaxes unless overridden per submission.\nRequires an environment key (`mfx_test_...` or `mfx_live_...`).", "summary": "Update Default Fax Settings", "tags": [ "Environment" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "max_attempts": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "csid": { "type": [ "string", "null" ], "maxLength": 20 }, "page_size": { "type": [ "string", "null" ], "enum": [ "letter", "legal", "a4", "b4" ] }, "resolution": { "type": [ "string", "null" ], "enum": [ "standard", "fine" ] }, "optimize_for": { "type": [ "string", "null" ], "enum": [ "text", "photo" ] } } } } } }, "responses": { "200": { "description": "`FaxSettingsResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxSettingsResource" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/events": { "get": { "operationId": "listEvents", "description": "Returns events for the authenticated environment, newest first.\nSupports cursor pagination.", "summary": "List Events", "tags": [ "Events" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^evt_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Array of `EventResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventResource" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/events/{event}": { "get": { "operationId": "retrieveEvent", "summary": "Retrieve an Event", "tags": [ "Events" ], "parameters": [ { "name": "event", "in": "path", "required": true, "description": "The event public id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Return the canonical byte form so the response body matches the\nexact bytes the Standard Webhooks delivery signs. Customers can\nre-verify a received webhook against this body byte-for-byte.", "content": { "application/json": { "schema": { "type": "string" } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/faxes": { "post": { "operationId": "sendFax", "description": "Submit a fax for delivery. The file is staged and the fax is queued for processing.\nA credit hold is placed on submission and captured on delivery or released on failure.", "summary": "Send a Fax", "tags": [ "Fax" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Client-generated key for idempotent submission (recommended). Duplicate keys return the original response without re-processing. Keys expire after 24 hours.", "schema": { "type": "string" }, "example": "order-1234-attempt-1" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SubmitFaxRequest" } } } }, "responses": { "201": { "description": "`FaxSubmissionResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxSubmissionResource" } } }, "headers": { "X-Idempotency-Key": { "description": "Echoed back when the request supplied an `Idempotency-Key` header. Absent when the client omitted the request header.", "required": false, "schema": { "type": "string" }, "example": "order-1234-attempt-1" }, "Idempotency-Replayed": { "description": "Set to `true` when this response was served from the idempotency cache rather than re-processing the request. Absent (not `false`) when the response represents a freshly processed submission.", "required": false, "schema": { "type": "string" }, "example": "true" } } }, "402": { "description": "Insufficient balance for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "insufficient_balance": { "value": { "error": "insufficient_balance", "message": "Insufficient balance for this operation.", "action": "top_up_balance", "docs": "https://mintfax.com/docs/errors/insufficient-balance", "context": { "available": 50, "required": 100 } } } } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } }, "get": { "operationId": "listFaxes", "description": "Returns a cursor-paginated list of faxes, most recent first.\nDefaults to the last 7 days; pass explicit `created_after` and\n`created_before` to widen or narrow the window.", "summary": "List Faxes", "tags": [ "Fax" ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/FaxStatus" } }, { "name": "created_after", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "created_before", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "description": "E.164 destination number, exact match.", "schema": { "type": [ "string", "null" ], "pattern": "^\\+[1-9]\\d{1,14}$" }, "example": "+12125551234" }, { "name": "error_code", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 64 } }, { "name": "tag[]", "in": "query", "description": "Filter by tag values. Use `tag[KEY]=VALUE`. Multiple tag filters compose with AND.", "schema": { "type": "array", "items": { "type": "string", "maxLength": 255 } }, "example": "1234" }, { "name": "cursor", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Array of `FaxResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FaxResource" } } }, "required": [ "data" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/faxes/{fax}": { "get": { "operationId": "getFax", "description": "Returns the full fax record including status, error details, and timing.", "summary": "Get a Fax", "tags": [ "Fax" ], "parameters": [ { "name": "fax", "in": "path", "required": true, "description": "The fax public id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`FaxResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxResource" } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } }, "delete": { "operationId": "purgeFax", "description": "Scrubs fax content and PII (document, destination number, idempotency key, webhook URL, error message) and removes the stored image. The fax record itself is retained so billing and audit history stay intact; subsequent `GET /faxes/{id}` calls continue to succeed and return the scrubbed record.\nOnly faxes in a terminal state (delivered or failed) can be purged.", "summary": "Purge a Fax", "tags": [ "Fax" ], "parameters": [ { "name": "fax", "in": "path", "required": true, "description": "The fax public id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "409": { "description": "Fax must be in a terminal state (delivered or failed) to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "fax_not_terminal": { "value": { "error": "fax_not_terminal", "message": "Fax must be in a terminal state (delivered or failed) to perform this action.", "action": "wait_for_completion", "docs": "https://mintfax.com/docs/errors/fax-not-terminal", "context": { "status": "queued" } } } } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/faxes/{fax}/image": { "get": { "operationId": "getFaxImage", "description": "Returns the rendered fax image (TIFF). Only available for faxes that have been\nprocessed and are within the retention period.", "summary": "Get Fax Image", "tags": [ "Fax" ], "parameters": [ { "name": "fax", "in": "path", "required": true, "description": "The fax public id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "string" } } } }, "422": { "description": "Fax data has been purged and cannot be used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "fax_data_purged": { "value": { "error": "fax_data_purged", "message": "Fax data has been purged and cannot be used.", "action": "submit_new_fax", "docs": "https://mintfax.com/docs/errors/fax-data-purged" } } } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/faxes/{fax}/resend": { "post": { "operationId": "resendFax", "description": "Resubmits a previously failed or delivered fax using the original document.\nA new credit hold is placed. Returns the new fax record.", "summary": "Resend a Fax", "tags": [ "Fax" ], "parameters": [ { "name": "fax", "in": "path", "required": true, "description": "The fax public id", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "Client-generated key for idempotent submission (recommended). Duplicate keys return the original response without re-processing. Keys expire after 24 hours.", "schema": { "type": "string" }, "example": "order-1234-attempt-1" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": [ "string", "null" ], "pattern": "^\\+[1-9]\\d{1,14}$" }, "webhook_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "max_attempts": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 } } } } } }, "responses": { "201": { "description": "`FaxSubmissionResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxSubmissionResource" } } }, "headers": { "X-Idempotency-Key": { "description": "Echoed back when the request supplied an `Idempotency-Key` header. Absent when the client omitted the request header.", "required": false, "schema": { "type": "string" }, "example": "order-1234-attempt-1" }, "Idempotency-Replayed": { "description": "Set to `true` when this response was served from the idempotency cache rather than re-processing the request. Absent (not `false`) when the response represents a freshly processed submission.", "required": false, "schema": { "type": "string" }, "example": "true" } } }, "409": { "description": "Fax must be in a terminal state (delivered or failed) to perform this action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "fax_not_terminal": { "value": { "error": "fax_not_terminal", "message": "Fax must be in a terminal state (delivered or failed) to perform this action.", "action": "wait_for_completion", "docs": "https://mintfax.com/docs/errors/fax-not-terminal", "context": { "status": "queued" } } } } } } }, "422": { "description": "Fax data has been purged and cannot be used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "fax_data_purged": { "value": { "error": "fax_data_purged", "message": "Fax data has been purged and cannot be used.", "action": "submit_new_fax", "docs": "https://mintfax.com/docs/errors/fax-data-purged" } }, "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/account/register": { "post": { "operationId": "registerAccount", "description": "Begins the account registration flow. Sends a 6-digit activation code to the\nprovided email address. The code is valid for 15 minutes.\n\nSubmit the code to `POST /account/register/verify` to complete registration\nand receive your API key.\n\nThis endpoint does not require authentication.", "summary": "Start Registration", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterViaApiRequest" } } } }, "responses": { "200": { "description": "`RegistrationInitiatedResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationInitiatedResource" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/account/register/verify": { "post": { "operationId": "verifyRegistration", "description": "Completes registration by verifying the activation code sent to the provided\nemail. On success, creates the account, user, sandbox environment, and API key\nin a single transaction.\n\nThe API key is only shown once - store it securely.\n\nThis endpoint does not require authentication.", "summary": "Verify Registration Code", "tags": [ "Account" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteApiRegistrationRequest" } } } }, "responses": { "201": { "description": "`RegistrationCompleteResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationCompleteResource" } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/webhooks/attempts": { "get": { "operationId": "listWebhookAttempts", "description": "Returns webhook delivery attempts for the authenticated environment, newest\nfirst. Supports cursor pagination and filtering by endpoint, fax, or\nattempt outcome.", "summary": "List Webhook Delivery Attempts", "tags": [ "Webhooks" ], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^wha_[0-9A-HJKMNP-TV-Z]{26}$" } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } }, { "name": "endpoint", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^we_[0-9A-Za-z]{22}$" } }, { "name": "fax", "in": "query", "schema": { "type": [ "string", "null" ], "pattern": "^fax_[0-9A-Za-z]{22}$" } }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "succeeded", "failed" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": [] }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/webhooks/attempts/{attempt}": { "get": { "operationId": "retrieveWebhookAttempt", "summary": "Retrieve a Webhook Attempt", "tags": [ "Webhooks" ], "parameters": [ { "name": "attempt", "in": "path", "required": true, "description": "The attempt public id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookAttemptResource`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAttemptResource" } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/webhooks/attempts/{attempt}/retry": { "post": { "operationId": "retryWebhookAttempt", "description": "Re-dispatches the original Event payload to the webhook endpoint. Allowed\nregardless of the original attempt's outcome. The new attempt row carries\n`parent_attempt_id` pointing to the original.", "summary": "Retry a Webhook Delivery", "tags": [ "Webhooks" ], "parameters": [ { "name": "attempt", "in": "path", "required": true, "description": "The attempt public id", "schema": { "type": "string" } } ], "responses": { "202": { "description": "" }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/webhooks": { "get": { "operationId": "listWebhookEndpoints", "description": "Returns all webhook endpoints configured for the current environment.", "summary": "List Webhook Endpoints", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Array of `WebhookEndpointResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointResource" } } }, "required": [ "data" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } }, "post": { "operationId": "createWebhookEndpoint", "description": "Creates a new webhook endpoint. Returns the endpoint and its signing secret.\nThe signing secret is only shown once - store it securely.", "summary": "Create Webhook Endpoint", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreWebhookEndpointRequest" } } } }, "responses": { "201": { "description": "`WebhookEndpointResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointResource" }, "signing_secret": { "type": "string" } }, "required": [ "data", "signing_secret" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/webhooks/{webhook}": { "put": { "operationId": "updateWebhookEndpoint", "description": "Updates an existing webhook endpoint.", "summary": "Update Webhook Endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook public id", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "`WebhookEndpointResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointResource" } }, "required": [ "data" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "422": { "description": "The request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_failed": { "value": { "error": "validation_failed", "message": "The request failed validation.", "action": "fix_request", "docs": "https://mintfax.com/docs/errors/validation-failed", "context": { "errors": { "to": [ "The to field is required." ], "file": [ "The file field is required." ] } } } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "description": "Permanently removes a webhook endpoint.", "summary": "Delete Webhook Endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook public id", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } }, "/webhooks/{webhook}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "description": "Generates a new signing secret for the endpoint. The previous secret is\nimmediately invalidated. The new secret is only shown once.", "summary": "Rotate Signing Secret", "tags": [ "Webhooks" ], "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "The webhook public id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`WebhookEndpointResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointResource" }, "signing_secret": { "type": "string" } }, "required": [ "data", "signing_secret" ] } } } }, "401": { "description": "The provided API key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "api_key_invalid": { "value": { "error": "api_key_invalid", "message": "The provided API key is not recognised.", "action": "check_credentials", "docs": "https://mintfax.com/docs/errors/api-key-invalid" } } } } } }, "403": { "description": "Live calls require account activation. Complete a first credit purchase to activate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "account_not_activated": { "value": { "error": "account_not_activated", "message": "Live calls require account activation. Complete a first credit purchase to activate.", "action": "activate_account", "docs": "https://mintfax.com/docs/errors/account-not-activated" } }, "key_not_scoped_for_operations": { "value": { "error": "key_not_scoped_for_operations", "message": "This API key cannot send faxes or read environment data. Use an mfx_test_ or mfx_live_ key.", "action": "use_operational_key", "docs": "https://mintfax.com/docs/errors/key-not-scoped-for-operations" } } } } } }, "404": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": "not_found", "message": "The requested resource was not found.", "action": "verify_id", "docs": "https://mintfax.com/docs/errors/not-found" } } } } } }, "500": { "description": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "internal_server_error": { "value": { "error": "internal_server_error", "message": "An unexpected error occurred. Please retry; if the problem persists, contact support.", "action": "retry_or_contact_support", "docs": "https://mintfax.com/docs/errors/internal-server-error" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "API key as Bearer token. Use an account key (`mfx_acct_...`) for\n`/account/*` endpoints, and an environment key (`mfx_test_...` for\nsandbox, `mfx_live_...` for live) for `/environment/*`, `/faxes`,\n`/webhooks`, and `/events`.", "scheme": "bearer" } }, "schemas": { "AccountResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Account identifier (acct_-prefixed).", "examples": [ "acct_4HGhJ7K2pNm9XqL3VtR8Wz" ] }, "name": { "type": "string", "description": "Account display name.", "examples": [ "Acme Corp" ] }, "email": { "type": "string", "format": "email", "description": "Primary account email.", "examples": [ "dev@acme.com" ] }, "created_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the account was created." }, "activated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the account was activated; null if not yet activated." }, "environment": { "type": "object", "properties": { "id": { "type": "string", "description": "Environment identifier (env_-prefixed).", "examples": [ "env_2BcD3eF4gH5iJ6kL7mN8oP" ] }, "name": { "type": "string", "description": "Human-readable environment name." }, "type": { "description": "Environment type.", "examples": [ "sandbox" ], "$ref": "#/components/schemas/EnvironmentType" }, "status": { "description": "Environment status.\nCurrently always 'active'. Future environment-level suspension would\nintroduce additional values; activation is reported via the account,\nnot here.", "examples": [ "active" ], "$ref": "#/components/schemas/EnvironmentStatus" } }, "required": [ "id", "name", "type", "status" ] } }, "required": [ "id", "name", "email", "created_at", "activated_at", "environment" ], "title": "AccountResource" }, "ApiKeyResource": { "type": "object", "properties": { "id": { "type": "string", "description": "API key identifier (key_-prefixed).", "examples": [ "key_4HGhJ7K2pNm9XqL3VtR8Wz" ] }, "name": { "type": "string", "description": "Human-readable key name.", "examples": [ "Production keys" ] }, "prefix": { "type": "string", "description": "First 16 chars of the key (e.g. mfx_test_abcd1234).", "examples": [ "mfx_test_abcd1234" ] }, "scope": { "type": "object", "properties": { "environments": { "type": "array", "description": "Environment slugs the key is scoped to (empty for account-only keys).", "items": { "type": "string" } }, "abilities": { "type": "array", "description": "Abilities granted (full account-admin set for account-level keys; empty for environment keys).", "items": { "type": "string" } } }, "required": [ "environments", "abilities" ] }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp the key was last used; null if never used." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp the key was created." } }, "required": [ "id", "name", "prefix", "scope", "last_used_at", "created_at" ], "title": "ApiKeyResource" }, "BalanceEventObject": { "type": "object", "description": "Account balance snapshot as carried in balance.* webhook payloads.", "properties": { "environment_id": { "type": "string", "description": "Environment identifier (env_-prefixed)." }, "available": { "type": "integer", "description": "Available balance in fractional currency units (e.g. cents)." }, "held": { "type": "integer", "description": "Funds currently held against in-flight faxes." }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" } }, "required": [ "environment_id", "available", "held", "currency" ] }, "BalanceLowEvent": { "type": "object", "description": "Webhook delivery for `balance.low`.", "properties": { "id": { "type": "string", "description": "Event identifier (evt_-prefixed). Stable across retry attempts.", "example": "evt_8aZqRm4yT3vK7pNxJ2bH9c" }, "type": { "type": "string", "enum": [ "balance.low" ], "description": "Event type. Always `balance.low` for this delivery." }, "created": { "type": "integer", "description": "Unix epoch seconds when the event was generated." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/BalanceEventObject" } }, "required": [ "object" ] } }, "required": [ "id", "type", "created", "data" ] }, "BalanceResource": { "type": "object", "properties": { "type": { "description": "Balance type.", "examples": [ "sandbox" ], "$ref": "#/components/schemas/WalletType" }, "available": { "type": "integer", "description": "Credits available for new faxes, in cents.", "examples": [ 4550 ] }, "held": { "type": "integer", "description": "Credits held for in-flight faxes, in cents.", "examples": [ 450 ] }, "auto_top_up": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether auto top-up is enabled for this balance.", "examples": [ false ] }, "threshold_amount": { "type": [ "integer", "null" ], "description": "Trigger threshold in cents (absolute amount). Auto top-up fires when the\nbalance falls below this value.", "examples": [ 1000 ] }, "package_id": { "type": [ "integer", "null" ], "description": "Package ID auto top-up will repurchase; null when no package is set." } }, "required": [ "enabled", "threshold_amount", "package_id" ] } }, "required": [ "type", "available", "held", "auto_top_up" ], "title": "BalanceResource" }, "BalanceTopupEvent": { "type": "object", "description": "Webhook delivery for `balance.topup`.", "properties": { "id": { "type": "string", "description": "Event identifier (evt_-prefixed). Stable across retry attempts.", "example": "evt_8aZqRm4yT3vK7pNxJ2bH9c" }, "type": { "type": "string", "enum": [ "balance.topup" ], "description": "Event type. Always `balance.topup` for this delivery." }, "created": { "type": "integer", "description": "Unix epoch seconds when the event was generated." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/BalanceEventObject" } }, "required": [ "object" ] } }, "required": [ "id", "type", "created", "data" ] }, "CompleteApiRegistrationRequest": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "code": { "type": "string", "pattern": "^[0-9]{6}$" } }, "required": [ "email", "code" ], "title": "CompleteApiRegistrationRequest" }, "EnvironmentResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Environment identifier (env_-prefixed).", "examples": [ "env_2BcD3eF4gH5iJ6kL7mN8oP" ] }, "name": { "type": "string", "description": "Human-readable environment name." }, "type": { "description": "Environment type.", "examples": [ "sandbox" ], "$ref": "#/components/schemas/EnvironmentType" }, "status": { "description": "Environment status.\nCurrently always 'active'. Future environment-level suspension would\nintroduce additional values; activation is reported via the account,\nnot here.", "examples": [ "active" ], "$ref": "#/components/schemas/EnvironmentStatus" } }, "required": [ "id", "name", "type", "status" ], "title": "EnvironmentResource" }, "EnvironmentStatus": { "type": "string", "enum": [ "active" ], "title": "EnvironmentStatus" }, "EnvironmentType": { "type": "string", "enum": [ "sandbox", "live" ], "title": "EnvironmentType" }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable error code.", "example": "insufficient_balance" }, "message": { "type": "string", "description": "Human-readable description.", "example": "Insufficient balance for this operation." }, "action": { "type": "string", "description": "Suggested next step for the caller.", "example": "top_up_balance" }, "docs": { "type": "string", "format": "uri", "description": "URL to the docs entry for this error code.", "example": "https://mintfax.com/docs/errors/insufficient-balance" }, "request_id": { "type": "string", "description": "Unique identifier for this API request, also returned in the X-Request-Id response header. Include this value in support requests for fast triage.", "pattern": "^req_[0-9A-HJKMNP-TV-Z]{26}$", "example": "req_01J9XYZQ8KH7B3R0WXAZP8VW6F" }, "context": { "type": "object", "description": "Error-specific extra fields (e.g. balances, validation errors).", "additionalProperties": [] } }, "required": [ "error", "message", "action", "docs", "request_id" ], "title": "Error" }, "EventResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "created": { "type": "integer" }, "data": { "type": "object", "properties": { "object": { "type": "object", "additionalProperties": [] } }, "required": [ "object" ] } }, "required": [ "id", "type", "created", "data" ], "title": "EventResource" }, "FaxAttempt": { "type": "object", "description": "Detail of one delivery attempt against the destination.", "properties": { "attempt_number": { "type": "integer", "minimum": 1, "description": "1-based index of the attempt." }, "started_at": { "type": "string", "format": "date-time", "description": "UTC time the attempt began." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC time the attempt finished. Null while in flight." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Wall-clock duration in milliseconds." }, "error_code": { "type": [ "string", "null" ], "description": "Failure code for this attempt. Null on success." }, "error_subcode": { "type": [ "string", "null" ], "description": "Optional finer-grained failure code." }, "error_message": { "type": [ "string", "null" ], "description": "Human-readable failure summary." } }, "required": [ "attempt_number", "started_at" ] }, "FaxDeliveredEvent": { "type": "object", "description": "Webhook delivery for `fax.delivered`.", "properties": { "id": { "type": "string", "description": "Event identifier (evt_-prefixed). Stable across retry attempts.", "example": "evt_8aZqRm4yT3vK7pNxJ2bH9c" }, "type": { "type": "string", "enum": [ "fax.delivered" ], "description": "Event type. Always `fax.delivered` for this delivery." }, "created": { "type": "integer", "description": "Unix epoch seconds when the event was generated." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/FaxEventObject" } }, "required": [ "object" ] } }, "required": [ "id", "type", "created", "data" ] }, "FaxEventObject": { "type": "object", "description": "Fax resource as carried in fax.* webhook payloads. Mirrors the shape returned by GET /faxes/{id} plus per-attempt detail.", "properties": { "id": { "type": "string", "description": "Unique fax identifier (fax_-prefixed).", "examples": [ "fax_8aZqRm4yT3vK7pNxJ2bH9c" ] }, "status": { "description": "Current fax status.", "examples": [ "queued" ], "$ref": "#/components/schemas/FaxStatus" }, "to": { "type": [ "string", "null" ], "description": "Destination fax number in E.164 format.", "examples": [ "+12125551234" ] }, "pages": { "type": [ "integer", "null" ], "description": "Number of pages, null until processing begins." }, "error_code": { "type": [ "string", "null" ], "description": "Machine-readable failure code, if any." }, "error_subcode": { "type": "string", "description": "Optional finer-grained mintfax-owned subcode, if any." }, "error_message": { "type": [ "string", "null" ], "description": "Human-readable failure description, if any." }, "max_attempts": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Configured retry cap for this fax (1-5)." }, "attempts": { "type": "array", "description": "Per-attempt delivery detail in chronological order.", "items": { "$ref": "#/components/schemas/FaxAttempt" } }, "webhook_url": { "type": [ "string", "null" ], "description": "Per-fax webhook override URL." }, "idempotency_key": { "type": [ "string", "null" ], "description": "Caller-supplied idempotency key." }, "tags": { "type": "object", "description": "Caller-supplied metadata map. Empty serializes as `{}`.", "additionalProperties": { "type": "string" } }, "csid": { "type": [ "string", "null" ], "description": "Sender CSID transmitted in the T.30 fax handshake (max 20 chars)." }, "page_size": { "anyOf": [ { "description": "Target page size for content mintfax renders. PDF inputs pass through unchanged.", "$ref": "#/components/schemas/PageSize" }, { "type": "null" } ] }, "resolution": { "anyOf": [ { "description": "T.30 transmission resolution.", "$ref": "#/components/schemas/FaxResolution" }, { "type": "null" } ] }, "optimize_for": { "anyOf": [ { "description": "Rasterizer optimization hint for non-PDF inputs.", "$ref": "#/components/schemas/FaxOptimization" }, { "type": "null" } ] }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the fax was submitted to a carrier. Null until submission." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the fax reached a terminal status. Null until completion." }, "created_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the fax record was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the fax record was last updated." } }, "required": [ "id", "status", "to", "pages", "error_code", "error_subcode", "error_message", "max_attempts", "attempts", "webhook_url", "idempotency_key", "tags", "csid", "page_size", "resolution", "optimize_for", "submitted_at", "completed_at", "created_at", "updated_at" ] }, "FaxFailedEvent": { "type": "object", "description": "Webhook delivery for `fax.failed`.", "properties": { "id": { "type": "string", "description": "Event identifier (evt_-prefixed). Stable across retry attempts.", "example": "evt_8aZqRm4yT3vK7pNxJ2bH9c" }, "type": { "type": "string", "enum": [ "fax.failed" ], "description": "Event type. Always `fax.failed` for this delivery." }, "created": { "type": "integer", "description": "Unix epoch seconds when the event was generated." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/FaxEventObject" } }, "required": [ "object" ] } }, "required": [ "id", "type", "created", "data" ] }, "FaxOptimization": { "type": "string", "enum": [ "text", "photo" ], "title": "FaxOptimization" }, "FaxQueuedEvent": { "type": "object", "description": "Webhook delivery for `fax.queued`.", "properties": { "id": { "type": "string", "description": "Event identifier (evt_-prefixed). Stable across retry attempts.", "example": "evt_8aZqRm4yT3vK7pNxJ2bH9c" }, "type": { "type": "string", "enum": [ "fax.queued" ], "description": "Event type. Always `fax.queued` for this delivery." }, "created": { "type": "integer", "description": "Unix epoch seconds when the event was generated." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/FaxEventObject" } }, "required": [ "object" ] } }, "required": [ "id", "type", "created", "data" ] }, "FaxResolution": { "type": "string", "enum": [ "standard", "fine" ], "title": "FaxResolution" }, "FaxResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique fax identifier (fax_-prefixed).", "examples": [ "fax_8aZqRm4yT3vK7pNxJ2bH9c" ] }, "status": { "description": "Current fax status.", "examples": [ "queued" ], "$ref": "#/components/schemas/FaxStatus" }, "to": { "type": [ "string", "null" ], "description": "Destination fax number in E.164 format.", "examples": [ "+12125551234" ] }, "pages": { "type": [ "integer", "null" ], "description": "Number of pages, null until processing begins." }, "error_code": { "type": [ "string", "null" ], "description": "Machine-readable failure code, if any." }, "error_subcode": { "type": "string", "description": "Optional finer-grained mintfax-owned subcode, if any." }, "error_message": { "type": [ "string", "null" ], "description": "Human-readable failure description, if any." }, "max_attempts": { "type": "string", "description": "Configured retry cap for this fax (1-5). See ADR-021.", "examples": [ "3" ] }, "attempts": { "type": "array", "description": "Per-attempt delivery detail in chronological order. See ADR-021.", "items": { "type": "object", "properties": { "attempt_number": { "type": "integer" }, "started_at": { "type": "string" }, "completed_at": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "error_subcode": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] } }, "required": [ "attempt_number", "started_at", "completed_at", "duration_ms", "error_code", "error_subcode", "error_message" ] } }, "webhook_url": { "type": [ "string", "null" ], "description": "Per-fax webhook override URL." }, "idempotency_key": { "type": [ "string", "null" ], "description": "Caller-supplied idempotency key." }, "tags": { "type": "object", "description": "Caller-supplied metadata map. Empty serializes as `{}`.", "additionalProperties": { "type": "string" } }, "csid": { "type": [ "string", "null" ], "description": "Sender CSID transmitted in the T.30 fax handshake (max 20 chars)." }, "page_size": { "anyOf": [ { "description": "Target page size for content mintfax renders. PDF inputs pass through unchanged.", "$ref": "#/components/schemas/PageSize" }, { "type": "null" } ] }, "resolution": { "anyOf": [ { "description": "T.30 transmission resolution.", "$ref": "#/components/schemas/FaxResolution" }, { "type": "null" } ] }, "optimize_for": { "anyOf": [ { "description": "Rasterizer optimization hint for non-PDF inputs.", "$ref": "#/components/schemas/FaxOptimization" }, { "type": "null" } ] }, "submitted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the fax was submitted to a carrier. Null until submission." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the fax reached a terminal status. Null until completion." }, "created_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the fax record was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the fax record was last updated." } }, "required": [ "id", "status", "to", "pages", "error_code", "error_subcode", "error_message", "max_attempts", "attempts", "webhook_url", "idempotency_key", "tags", "csid", "page_size", "resolution", "optimize_for", "submitted_at", "completed_at", "created_at", "updated_at" ], "title": "FaxResource" }, "FaxSendingEvent": { "type": "object", "description": "Webhook delivery for `fax.sending`.", "properties": { "id": { "type": "string", "description": "Event identifier (evt_-prefixed). Stable across retry attempts.", "example": "evt_8aZqRm4yT3vK7pNxJ2bH9c" }, "type": { "type": "string", "enum": [ "fax.sending" ], "description": "Event type. Always `fax.sending` for this delivery." }, "created": { "type": "integer", "description": "Unix epoch seconds when the event was generated." }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/FaxEventObject" } }, "required": [ "object" ] } }, "required": [ "id", "type", "created", "data" ] }, "FaxSettingsResource": { "type": "object", "properties": { "webhook_url": { "type": [ "string", "null" ], "format": "uri", "description": "Default per-fax webhook URL override." }, "max_attempts": { "type": "integer", "description": "Default attempt cap for faxes (1-5). See ADR-021.", "examples": [ 3 ] }, "csid": { "type": [ "string", "null" ], "description": "Default CSID for outbound faxes (max 20 chars)." }, "page_size": { "anyOf": [ { "description": "Default page size for rendered content. PDF inputs pass through unchanged.", "$ref": "#/components/schemas/PageSize" }, { "type": "null" } ] }, "resolution": { "anyOf": [ { "description": "Default T.30 transmission resolution.", "$ref": "#/components/schemas/FaxResolution" }, { "type": "null" } ] }, "optimize_for": { "anyOf": [ { "description": "Default rasterizer optimization hint for non-PDF inputs.", "$ref": "#/components/schemas/FaxOptimization" }, { "type": "null" } ] } }, "required": [ "webhook_url", "max_attempts", "csid", "page_size", "resolution", "optimize_for" ], "title": "FaxSettingsResource" }, "FaxStatus": { "type": "string", "enum": [ "queued", "submitted", "in_progress", "delivered", "failed" ], "title": "FaxStatus" }, "FaxSubmissionResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique fax identifier (fax_-prefixed).", "examples": [ "fax_8aZqRm4yT3vK7pNxJ2bH9c" ] }, "status": { "description": "Initial fax status.", "examples": [ "queued" ], "$ref": "#/components/schemas/FaxStatus" }, "to": { "type": [ "string", "null" ], "description": "Destination fax number in E.164 format.", "examples": [ "+12125551234" ] }, "tags": { "type": "object", "description": "Echo of caller-supplied metadata. Empty serializes as `{}`.", "additionalProperties": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the fax record was created." }, "resent_from": { "type": "string", "description": "Original fax identifier when this submission is a resend; only present on resends.", "examples": [ "fax_8aZqRm4yT3vK7pNxJ2bH9c" ] } }, "required": [ "id", "status", "to", "tags", "created_at" ], "title": "FaxSubmissionResource" }, "PageSize": { "type": "string", "enum": [ "letter", "legal", "a4", "b4" ], "title": "PageSize" }, "RegisterViaApiRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 } }, "required": [ "name", "email" ], "title": "RegisterViaApiRequest" }, "RegistrationCompleteResource": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Account identifier (acct_-prefixed).", "examples": [ "acct_4HGhJ7K2pNm9XqL3VtR8Wz" ] }, "name": { "type": "string", "description": "Account display name.", "examples": [ "Acme Corp" ] } }, "required": [ "id", "name" ] }, "user": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Registered email address (lowercased canonical form).", "examples": [ "dev@acme.com" ] } }, "required": [ "email" ] }, "environment": { "type": "object", "properties": { "id": { "type": "string", "description": "Environment identifier (env_-prefixed).", "examples": [ "env_2BcD3eF4gH5iJ6kL7mN8oP" ] }, "name": { "type": "string", "description": "Environment display name.", "examples": [ "Sandbox" ] }, "type": { "description": "Environment type.", "examples": [ "sandbox" ], "$ref": "#/components/schemas/EnvironmentType" } }, "required": [ "id", "name", "type" ] }, "api_key": { "type": "string", "description": "Plain-text sandbox API key (only shown once at registration).", "examples": [ "mfx_test_abc123def456..." ] }, "api_key_account": { "type": "string", "description": "Plain-text account-management API key (only shown once at registration).", "examples": [ "mfx_acct_qpr456stv789..." ] } }, "required": [ "account", "user", "environment", "api_key", "api_key_account" ], "title": "RegistrationCompleteResource" }, "RegistrationInitiatedResource": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The email address the activation code was sent to.", "examples": [ "dev@acme.com" ] }, "message": { "type": "string", "description": "Human-readable confirmation message.", "examples": [ "Activation code sent. Valid for 15 minutes." ] }, "expires_in": { "type": "integer", "description": "Seconds until the activation code expires.", "examples": [ 900 ] } }, "required": [ "email", "message", "expires_in" ], "title": "RegistrationInitiatedResource" }, "StoreWebhookEndpointRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "events": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "fax.queued", "fax.sending", "fax.delivered", "fax.failed", "balance.low", "balance.topup" ] }, "maxItems": 6 } }, "required": [ "url" ], "title": "StoreWebhookEndpointRequest" }, "SubmitFaxRequest": { "type": "object", "properties": { "to": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$" }, "file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "maxLength": 10240 }, "webhook_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "max_attempts": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 5 }, "csid": { "type": [ "string", "null" ], "maxLength": 20 }, "page_size": { "type": [ "string", "null" ], "enum": [ "letter", "legal", "a4", "b4" ] }, "resolution": { "type": [ "string", "null" ], "enum": [ "standard", "fine" ] }, "optimize_for": { "type": [ "string", "null" ], "enum": [ "text", "photo" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 255 }, "maxItems": 10 } }, "required": [ "to", "file" ], "title": "SubmitFaxRequest" }, "TransactionResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction identifier." }, "type": { "description": "Transaction type.", "$ref": "#/components/schemas/WalletLedgerEntryType" }, "balance_type": { "anyOf": [ { "description": "Balance affected by this transaction; null for transactions not tied to a balance.", "$ref": "#/components/schemas/WalletType" }, { "type": "null" } ] }, "amount": { "type": "integer", "description": "Amount in cents. Positive for credits, negative for debits." }, "balance_after": { "type": "integer", "description": "Balance after the transaction settled, in cents." }, "reference": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "const": "fax" }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "description": { "type": [ "string", "null" ], "description": "Human-readable transaction description." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the transaction settled." } }, "required": [ "id", "type", "balance_type", "amount", "balance_after", "reference", "description", "created_at" ], "title": "TransactionResource" }, "UpdateWebhookEndpointRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "is_active": { "type": "boolean" }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "events": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "fax.queued", "fax.sending", "fax.delivered", "fax.failed", "balance.low", "balance.topup" ] }, "maxItems": 6 } }, "title": "UpdateWebhookEndpointRequest" }, "WalletLedgerEntryType": { "type": "string", "enum": [ "purchase", "capture", "seed" ], "title": "WalletLedgerEntryType" }, "WalletType": { "type": "string", "enum": [ "live", "sandbox" ], "title": "WalletType" }, "WebhookAttemptResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook attempt identifier (wha_-prefixed ULID).", "examples": [ "wha_01J9XYZQ8KH7B3R0WXAZP8VW6F" ] }, "event_id": { "type": "string", "description": "Event identifier this attempt delivered (evt_-prefixed ULID)." }, "webhook_endpoint_id": { "type": "string", "description": "Webhook endpoint identifier that received this attempt." }, "attempt_number": { "type": "integer", "description": "Attempt number (1-indexed)." }, "status_code": { "type": [ "integer", "null" ], "description": "HTTP status code returned by the endpoint; null when the request never completed." }, "succeeded_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the attempt succeeded; null if it failed or is in flight." }, "failed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC timestamp when the attempt failed terminally; null if it succeeded or is in flight." }, "error_class": { "type": [ "string", "null" ], "description": "Exception class name when delivery failed transport-level; null otherwise." }, "error_message": { "type": [ "string", "null" ], "description": "Failure description; null when the attempt succeeded." }, "parent_attempt_id": { "type": [ "string", "null" ], "description": "Identifier of the prior attempt this one retried; null for the initial delivery." } }, "required": [ "id", "event_id", "webhook_endpoint_id", "attempt_number", "status_code", "succeeded_at", "failed_at", "error_class", "error_message", "parent_attempt_id" ], "title": "WebhookAttemptResource" }, "WebhookEndpointResource": { "type": "object", "properties": { "id": { "type": "string", "description": "Webhook endpoint identifier (we_-prefixed)." }, "url": { "type": "string", "description": "Destination URL receiving signed events." }, "events": { "type": [ "array", "null" ], "description": "Event types this endpoint subscribes to. Null means\nsubscribed to all event types (the WebhookEndpoint::subscribesTo\nruntime treats null as \"all\").", "examples": [ [ "fax.delivered", "fax.failed" ] ], "items": { "type": "string" } }, "is_active": { "type": "boolean", "description": "Whether the endpoint is currently delivering events." }, "description": { "type": [ "string", "null" ], "description": "Caller-provided description." }, "created_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the endpoint was created." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the endpoint was last updated." } }, "required": [ "id", "url", "events", "is_active", "description", "created_at", "updated_at" ], "title": "WebhookEndpointResource" }, "WebhookEnvelope": { "type": "object", "description": "Common envelope shared by every mintfax webhook delivery.", "properties": { "id": { "type": "string", "description": "Event identifier (evt_-prefixed). Stable across retry attempts.", "example": "evt_8aZqRm4yT3vK7pNxJ2bH9c" }, "type": { "type": "string", "description": "Event type, one of the values enumerated in this section." }, "created": { "type": "integer", "description": "Unix epoch seconds when the event was generated." }, "data": { "type": "object", "properties": { "object": { "type": "object", "description": "Resource snapshot at the time the event fired." } }, "required": [ "object" ] } }, "required": [ "id", "type", "created", "data" ] } } }, "webhooks": { "fax.queued": { "post": { "summary": "Sent when a fax has been accepted and is queued for delivery.", "description": "Fires once at submission, after the credit hold has been placed.", "tags": [ "Webhooks" ], "requestBody": { "description": "Event delivery to your subscribed webhook endpoint.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxQueuedEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged. mintfax treats any 2xx response as a successful delivery." } } } }, "fax.sending": { "post": { "summary": "Sent when a delivery attempt against the destination begins.", "description": "Fires at the start of each delivery attempt.", "tags": [ "Webhooks" ], "requestBody": { "description": "Event delivery to your subscribed webhook endpoint.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxSendingEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged. mintfax treats any 2xx response as a successful delivery." } } } }, "fax.delivered": { "post": { "summary": "Sent when a fax has been successfully delivered.", "description": "Fires once on terminal success.", "tags": [ "Webhooks" ], "requestBody": { "description": "Event delivery to your subscribed webhook endpoint.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxDeliveredEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged. mintfax treats any 2xx response as a successful delivery." } } } }, "fax.failed": { "post": { "summary": "Sent when a fax has failed terminally.", "description": "Fires once after every retryable attempt has been consumed or a terminal error code is returned.", "tags": [ "Webhooks" ], "requestBody": { "description": "Event delivery to your subscribed webhook endpoint.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxFailedEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged. mintfax treats any 2xx response as a successful delivery." } } } }, "balance.low": { "post": { "summary": "Sent when an environment's available balance crosses below the low-balance threshold.", "description": "Producer not yet shipped; see the page banner.", "tags": [ "Webhooks" ], "requestBody": { "description": "Event delivery to your subscribed webhook endpoint.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceLowEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged. mintfax treats any 2xx response as a successful delivery." } } } }, "balance.topup": { "post": { "summary": "Sent when funds are added to an environment.", "description": "Producer not yet shipped; see the page banner.", "tags": [ "Webhooks" ], "requestBody": { "description": "Event delivery to your subscribed webhook endpoint.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceTopupEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged. mintfax treats any 2xx response as a successful delivery." } } } } } }