# SingleFax OpenAPI specification The current SingleFax REST API specification is available as [JSON](https://singlefax.com/openapi.json). See the [API documentation](https://singlefax.com/developers) and [authentication guide](https://singlefax.com/auth). ```json { "openapi": "3.0.3", "info": { "title": "SingleFax API", "version": "1.0.0", "description": "Send faxes via API keys + prepaid credits, or OAuth (MCP). Machine MPP uses HTTP 402 + Stripe SPT or Tempo USDC (optional x402 Base USDC). Errors are JSON with code + resolution hints. URL versioning: /api/v1. Breaking changes ship as /api/v2. Deprecation policy (Sunset/Deprecation headers, 90-day window): https://singlefax.com/versioning", "x-guidance": "Autonomous agents pay with MPP: POST /api/v1/machine/faxes with JSON { \"to\": \"\", \"base64\": \"\", \"request_id\": \"\" }. Supported files: PDF, Word, Excel, PowerPoint, RTF, plain text, and images (JPEG, PNG, TIFF, GIF, WebP, BMP, HEIC). Do not convert to PDF first. Send the original file; we convert before sending. Unpaid calls return HTTP 402 + WWW-Authenticate: Payment (Stripe SPT / Link, or Tempo USDC.e). Retry the same body with Authorization: Payment …. If PAYMENT-REQUIRED is present, x402 clients retry with PAYMENT-SIGNATURE. Quote without charging at POST /api/v1/machine/faxes/validate (free). Chat apps (Cursor, Claude, Codex) should use MCP at /mcp (OAuth), not this 402 path. Do not send PHI on MCP, MPP, or this API. Covered Entities use the website HIPAA Secure path.", "contact": { "name": "SingleFax", "email": "info@singlefax.com", "url": "https://singlefax.com/contact" } }, "externalDocs": { "description": "API versioning and deprecation policy", "url": "https://singlefax.com/versioning" }, "servers": [ { "url": "https://singlefax.com" } ], "tags": [ { "name": "uploads", "description": "Document upload capabilities" }, { "name": "faxes", "description": "Send and poll faxes" }, { "name": "inbox", "description": "Received faxes (inbox:read)" }, { "name": "credits", "description": "Prepaid credit balance" }, { "name": "numbers", "description": "Fax numbers" }, { "name": "catalog", "description": "Product SKUs and HITL checkout" }, { "name": "machine", "description": "Autonomous MPP (HTTP 402)" }, { "name": "commerce", "description": "UCP / ACP credit packs with hosted buyer approval" } ], "paths": { "/api/v1/commerce/ap2/carts": { "post": { "operationId": "ap2Create", "summary": "AP2 Create credit purchase", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "description": "Human-present AP2 v0.1.0 merchant flow. Requires credits:checkout, a signed cart, a Stripe SPT and separate owner passkey approval before charging. The cart is the payment idempotency boundary. See /ap2.md.", "externalDocs": { "url": "https://singlefax.com/ap2.md" }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "product_id": { "type": "string", "enum": [ "credit-pack-20", "credit-pack-50", "credit-pack-100" ] }, "intent_mandate": { "type": "object", "additionalProperties": false, "properties": { "user_cart_confirmation_required": { "type": "boolean", "enum": [ true ] }, "natural_language_description": { "type": "string", "maxLength": 1000 }, "intent_expiry": { "type": "string", "format": "date-time" }, "merchants": { "type": "array", "nullable": true, "items": { "type": "string" } }, "skus": { "type": "array", "nullable": true, "items": { "type": "string" } }, "requires_refundability": { "type": "boolean", "enum": [ false ] } }, "required": [ "user_cart_confirmation_required", "natural_language_description", "intent_expiry" ] } }, "required": [ "product_id", "intent_mandate" ] } } } }, "responses": { "201": { "description": "Cart state; completed only after credit ledger fulfillment", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_mandate", "awaiting_approval", "approved", "processing", "requires_action", "completed", "failed", "canceled" ] }, "ap2.mandates.CartMandate": { "type": "object", "additionalProperties": false, "properties": { "contents": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "user_cart_confirmation_required": { "type": "boolean", "enum": [ true ] }, "merchant_name": { "type": "string", "enum": [ "SingleFax" ] }, "cart_expiry": { "type": "string", "format": "date-time" }, "payment_request": { "type": "object", "additionalProperties": false, "properties": { "method_data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "supported_methods": { "type": "string", "enum": [ "https://stripe.com/shared-payment-token" ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "stripe_profile_id": { "type": "string" } }, "required": [ "stripe_profile_id" ] } }, "required": [ "supported_methods" ] } }, "details": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "display_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "total": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "required": [ "id", "display_items", "total" ] }, "options": { "type": "object", "additionalProperties": false, "properties": { "request_shipping": { "type": "boolean", "enum": [ false ] } }, "required": [ "request_shipping" ] } }, "required": [ "method_data", "details", "options" ] } }, "required": [ "id", "user_cart_confirmation_required", "merchant_name", "cart_expiry", "payment_request" ] }, "merchant_authorization": { "type": "string", "description": "EdDSA compact JWS over the RFC 8785 contents hash" } }, "required": [ "contents", "merchant_authorization" ] }, "user_authorization": { "type": "string" }, "approval_url": { "type": "string", "format": "uri" }, "receipt": { "type": "string" }, "documentation_url": { "type": "string", "format": "uri" } }, "required": [ "id", "status", "ap2.mandates.CartMandate", "documentation_url" ] } } } }, "4XX": { "description": "Invalid mandate, scope, environment, approval or state" }, "5XX": { "description": "Payment outcome uncertain or service unavailable; retry the same cart/mandate" } } } }, "/api/v1/commerce/ap2/carts/{id}": { "get": { "operationId": "ap2Get", "summary": "AP2 Get credit purchase", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "description": "Human-present AP2 v0.1.0 merchant flow. Requires credits:checkout, a signed cart, a Stripe SPT and separate owner passkey approval before charging. The cart is the payment idempotency boundary. See /ap2.md.", "externalDocs": { "url": "https://singlefax.com/ap2.md" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^ap2_[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Cart state; completed only after credit ledger fulfillment", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_mandate", "awaiting_approval", "approved", "processing", "requires_action", "completed", "failed", "canceled" ] }, "ap2.mandates.CartMandate": { "type": "object", "additionalProperties": false, "properties": { "contents": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "user_cart_confirmation_required": { "type": "boolean", "enum": [ true ] }, "merchant_name": { "type": "string", "enum": [ "SingleFax" ] }, "cart_expiry": { "type": "string", "format": "date-time" }, "payment_request": { "type": "object", "additionalProperties": false, "properties": { "method_data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "supported_methods": { "type": "string", "enum": [ "https://stripe.com/shared-payment-token" ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "stripe_profile_id": { "type": "string" } }, "required": [ "stripe_profile_id" ] } }, "required": [ "supported_methods" ] } }, "details": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "display_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "total": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "required": [ "id", "display_items", "total" ] }, "options": { "type": "object", "additionalProperties": false, "properties": { "request_shipping": { "type": "boolean", "enum": [ false ] } }, "required": [ "request_shipping" ] } }, "required": [ "method_data", "details", "options" ] } }, "required": [ "id", "user_cart_confirmation_required", "merchant_name", "cart_expiry", "payment_request" ] }, "merchant_authorization": { "type": "string", "description": "EdDSA compact JWS over the RFC 8785 contents hash" } }, "required": [ "contents", "merchant_authorization" ] }, "user_authorization": { "type": "string" }, "approval_url": { "type": "string", "format": "uri" }, "receipt": { "type": "string" }, "documentation_url": { "type": "string", "format": "uri" } }, "required": [ "id", "status", "ap2.mandates.CartMandate", "documentation_url" ] } } } }, "4XX": { "description": "Invalid mandate, scope, environment, approval or state" }, "5XX": { "description": "Payment outcome uncertain or service unavailable; retry the same cart/mandate" } } } }, "/api/v1/commerce/ap2/carts/{id}/prepare": { "post": { "operationId": "ap2Prepare", "summary": "AP2 Prepare credit purchase", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "description": "Human-present AP2 v0.1.0 merchant flow. Requires credits:checkout, a signed cart, a Stripe SPT and separate owner passkey approval before charging. The cart is the payment idempotency boundary. See /ap2.md.", "externalDocs": { "url": "https://singlefax.com/ap2.md" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^ap2_[A-Za-z0-9_-]{43}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "ap2.mandates.PaymentMandate": { "type": "object", "additionalProperties": false, "properties": { "payment_mandate_contents": { "type": "object", "additionalProperties": false, "properties": { "payment_mandate_id": { "type": "string", "maxLength": 255 }, "payment_details_id": { "type": "string" }, "payment_details_total": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] }, "merchant_agent": { "type": "string", "format": "uri" }, "timestamp": { "type": "string", "format": "date-time" }, "payment_response": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string" }, "method_name": { "type": "string", "enum": [ "https://stripe.com/shared-payment-token" ] }, "details": { "type": "object", "additionalProperties": false, "properties": { "shared_payment_token": { "type": "string", "pattern": "^spt_[A-Za-z0-9_]{6,500}$" } }, "required": [ "shared_payment_token" ] } }, "required": [ "request_id", "method_name", "details" ] } }, "required": [ "payment_mandate_id", "payment_details_id", "payment_details_total", "merchant_agent", "timestamp", "payment_response" ] } }, "required": [ "payment_mandate_contents" ] } }, "required": [ "ap2.mandates.PaymentMandate" ] } } } }, "responses": { "200": { "description": "Cart state; completed only after credit ledger fulfillment", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_mandate", "awaiting_approval", "approved", "processing", "requires_action", "completed", "failed", "canceled" ] }, "ap2.mandates.CartMandate": { "type": "object", "additionalProperties": false, "properties": { "contents": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "user_cart_confirmation_required": { "type": "boolean", "enum": [ true ] }, "merchant_name": { "type": "string", "enum": [ "SingleFax" ] }, "cart_expiry": { "type": "string", "format": "date-time" }, "payment_request": { "type": "object", "additionalProperties": false, "properties": { "method_data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "supported_methods": { "type": "string", "enum": [ "https://stripe.com/shared-payment-token" ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "stripe_profile_id": { "type": "string" } }, "required": [ "stripe_profile_id" ] } }, "required": [ "supported_methods" ] } }, "details": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "display_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "total": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "required": [ "id", "display_items", "total" ] }, "options": { "type": "object", "additionalProperties": false, "properties": { "request_shipping": { "type": "boolean", "enum": [ false ] } }, "required": [ "request_shipping" ] } }, "required": [ "method_data", "details", "options" ] } }, "required": [ "id", "user_cart_confirmation_required", "merchant_name", "cart_expiry", "payment_request" ] }, "merchant_authorization": { "type": "string", "description": "EdDSA compact JWS over the RFC 8785 contents hash" } }, "required": [ "contents", "merchant_authorization" ] }, "user_authorization": { "type": "string" }, "approval_url": { "type": "string", "format": "uri" }, "receipt": { "type": "string" }, "documentation_url": { "type": "string", "format": "uri" } }, "required": [ "id", "status", "ap2.mandates.CartMandate", "documentation_url" ] } } } }, "4XX": { "description": "Invalid mandate, scope, environment, approval or state" }, "5XX": { "description": "Payment outcome uncertain or service unavailable; retry the same cart/mandate" } } } }, "/api/v1/commerce/ap2/carts/{id}/complete": { "post": { "operationId": "ap2Complete", "summary": "AP2 Complete credit purchase", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "description": "Human-present AP2 v0.1.0 merchant flow. Requires credits:checkout, a signed cart, a Stripe SPT and separate owner passkey approval before charging. The cart is the payment idempotency boundary. See /ap2.md.", "externalDocs": { "url": "https://singlefax.com/ap2.md" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^ap2_[A-Za-z0-9_-]{43}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "ap2.mandates.CartMandate": { "type": "object", "additionalProperties": false, "properties": { "contents": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "user_cart_confirmation_required": { "type": "boolean", "enum": [ true ] }, "merchant_name": { "type": "string", "enum": [ "SingleFax" ] }, "cart_expiry": { "type": "string", "format": "date-time" }, "payment_request": { "type": "object", "additionalProperties": false, "properties": { "method_data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "supported_methods": { "type": "string", "enum": [ "https://stripe.com/shared-payment-token" ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "stripe_profile_id": { "type": "string" } }, "required": [ "stripe_profile_id" ] } }, "required": [ "supported_methods" ] } }, "details": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "display_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "total": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "required": [ "id", "display_items", "total" ] }, "options": { "type": "object", "additionalProperties": false, "properties": { "request_shipping": { "type": "boolean", "enum": [ false ] } }, "required": [ "request_shipping" ] } }, "required": [ "method_data", "details", "options" ] } }, "required": [ "id", "user_cart_confirmation_required", "merchant_name", "cart_expiry", "payment_request" ] }, "merchant_authorization": { "type": "string", "description": "EdDSA compact JWS over the RFC 8785 contents hash" } }, "required": [ "contents", "merchant_authorization" ] }, "ap2.mandates.PaymentMandate": { "type": "object", "additionalProperties": false, "properties": { "payment_mandate_contents": { "type": "object", "additionalProperties": false, "properties": { "payment_mandate_id": { "type": "string", "maxLength": 255 }, "payment_details_id": { "type": "string" }, "payment_details_total": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] }, "merchant_agent": { "type": "string", "format": "uri" }, "timestamp": { "type": "string", "format": "date-time" }, "payment_response": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string" }, "method_name": { "type": "string", "enum": [ "https://stripe.com/shared-payment-token" ] }, "details": { "type": "object", "additionalProperties": false, "properties": { "shared_payment_token": { "type": "string", "pattern": "^spt_[A-Za-z0-9_]{6,500}$" } }, "required": [ "shared_payment_token" ] } }, "required": [ "request_id", "method_name", "details" ] } }, "required": [ "payment_mandate_id", "payment_details_id", "payment_details_total", "merchant_agent", "timestamp", "payment_response" ] }, "user_authorization": { "type": "string", "description": "Base64url W3C VP with the owner passkey-approved SingleFax JWT VC; GET the approved cart to retrieve it" } }, "required": [ "payment_mandate_contents", "user_authorization" ] } }, "required": [ "ap2.mandates.CartMandate", "ap2.mandates.PaymentMandate" ] } } } }, "responses": { "200": { "description": "Cart state; completed only after credit ledger fulfillment", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_mandate", "awaiting_approval", "approved", "processing", "requires_action", "completed", "failed", "canceled" ] }, "ap2.mandates.CartMandate": { "type": "object", "additionalProperties": false, "properties": { "contents": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "user_cart_confirmation_required": { "type": "boolean", "enum": [ true ] }, "merchant_name": { "type": "string", "enum": [ "SingleFax" ] }, "cart_expiry": { "type": "string", "format": "date-time" }, "payment_request": { "type": "object", "additionalProperties": false, "properties": { "method_data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "supported_methods": { "type": "string", "enum": [ "https://stripe.com/shared-payment-token" ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "stripe_profile_id": { "type": "string" } }, "required": [ "stripe_profile_id" ] } }, "required": [ "supported_methods" ] } }, "details": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "display_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "total": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "required": [ "id", "display_items", "total" ] }, "options": { "type": "object", "additionalProperties": false, "properties": { "request_shipping": { "type": "boolean", "enum": [ false ] } }, "required": [ "request_shipping" ] } }, "required": [ "method_data", "details", "options" ] } }, "required": [ "id", "user_cart_confirmation_required", "merchant_name", "cart_expiry", "payment_request" ] }, "merchant_authorization": { "type": "string", "description": "EdDSA compact JWS over the RFC 8785 contents hash" } }, "required": [ "contents", "merchant_authorization" ] }, "user_authorization": { "type": "string" }, "approval_url": { "type": "string", "format": "uri" }, "receipt": { "type": "string" }, "documentation_url": { "type": "string", "format": "uri" } }, "required": [ "id", "status", "ap2.mandates.CartMandate", "documentation_url" ] } } } }, "4XX": { "description": "Invalid mandate, scope, environment, approval or state" }, "5XX": { "description": "Payment outcome uncertain or service unavailable; retry the same cart/mandate" } } } }, "/api/v1/commerce/ap2/carts/{id}/cancel": { "post": { "operationId": "ap2Cancel", "summary": "AP2 Cancel credit purchase", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "description": "Human-present AP2 v0.1.0 merchant flow. Requires credits:checkout, a signed cart, a Stripe SPT and separate owner passkey approval before charging. The cart is the payment idempotency boundary. See /ap2.md.", "externalDocs": { "url": "https://singlefax.com/ap2.md" }, "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^ap2_[A-Za-z0-9_-]{43}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": {}, "required": [] } } } }, "responses": { "200": { "description": "Cart state; completed only after credit ledger fulfillment", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "awaiting_mandate", "awaiting_approval", "approved", "processing", "requires_action", "completed", "failed", "canceled" ] }, "ap2.mandates.CartMandate": { "type": "object", "additionalProperties": false, "properties": { "contents": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "user_cart_confirmation_required": { "type": "boolean", "enum": [ true ] }, "merchant_name": { "type": "string", "enum": [ "SingleFax" ] }, "cart_expiry": { "type": "string", "format": "date-time" }, "payment_request": { "type": "object", "additionalProperties": false, "properties": { "method_data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "supported_methods": { "type": "string", "enum": [ "https://stripe.com/shared-payment-token" ] }, "data": { "type": "object", "additionalProperties": false, "properties": { "stripe_profile_id": { "type": "string" } }, "required": [ "stripe_profile_id" ] } }, "required": [ "supported_methods" ] } }, "details": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "display_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "total": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string" }, "amount": { "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "value": { "type": "number", "enum": [ 20, 50, 100 ] } }, "required": [ "currency", "value" ] }, "refund_period": { "type": "integer", "enum": [ 0 ] } }, "required": [ "label", "amount", "refund_period" ] } }, "required": [ "id", "display_items", "total" ] }, "options": { "type": "object", "additionalProperties": false, "properties": { "request_shipping": { "type": "boolean", "enum": [ false ] } }, "required": [ "request_shipping" ] } }, "required": [ "method_data", "details", "options" ] } }, "required": [ "id", "user_cart_confirmation_required", "merchant_name", "cart_expiry", "payment_request" ] }, "merchant_authorization": { "type": "string", "description": "EdDSA compact JWS over the RFC 8785 contents hash" } }, "required": [ "contents", "merchant_authorization" ] }, "user_authorization": { "type": "string" }, "approval_url": { "type": "string", "format": "uri" }, "receipt": { "type": "string" }, "documentation_url": { "type": "string", "format": "uri" } }, "required": [ "id", "status", "ap2.mandates.CartMandate", "documentation_url" ] } } } }, "4XX": { "description": "Invalid mandate, scope, environment, approval or state" }, "5XX": { "description": "Payment outcome uncertain or service unavailable; retry the same cart/mandate" } } } }, "/api/v1/commerce/products": { "get": { "operationId": "listCommerceProducts", "tags": [ "commerce" ], "security": [], "summary": "List fixed USD credit packs", "responses": { "200": { "description": "Products and server prices in cents" } } } }, "/api/v1/commerce/ucp/checkout-sessions": { "post": { "operationId": "ucpCreate", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "summary": "UCP Create credit checkout", "description": "Requires a bearer SingleFax API key with credits:checkout. Buyer pays at hosted Stripe continue_url; GET confirms ledger fulfillment. No inline payment handlers. See /commerce.md.", "parameters": [ { "in": "header", "name": "UCP-Agent", "required": true, "schema": { "type": "string" }, "example": "profile=\"https://platform.example/.well-known/ucp\"" }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "Protocol checkout state", "content": { "application/json": { "schema": { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json" } } } }, "4XX": { "description": "Invalid request, authorization, unsupported feature or state conflict" }, "5XX": { "description": "Payment provider or service unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "line_items" ], "properties": { "line_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "item", "quantity" ], "properties": { "id": { "type": "string" }, "item": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "enum": [ "credit-pack-20", "credit-pack-50", "credit-pack-100" ] } } }, "quantity": { "type": "integer", "enum": [ 1 ] } } } } } } } } } } }, "/api/v1/commerce/ucp/checkout-sessions/{id}": { "get": { "operationId": "ucpGet", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "summary": "UCP Get credit checkout", "description": "Requires a bearer SingleFax API key with credits:checkout. Buyer pays at hosted Stripe continue_url; GET confirms ledger fulfillment. No inline payment handlers. See /commerce.md.", "parameters": [ { "in": "header", "name": "UCP-Agent", "required": true, "schema": { "type": "string" }, "example": "profile=\"https://platform.example/.well-known/ucp\"" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^com_[a-f0-9]{40}$" } } ], "responses": { "200": { "description": "Protocol checkout state", "content": { "application/json": { "schema": { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json" } } } }, "4XX": { "description": "Invalid request, authorization, unsupported feature or state conflict" }, "5XX": { "description": "Payment provider or service unavailable" } } }, "put": { "operationId": "ucpUpdate", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "summary": "UCP Update credit checkout", "description": "Requires a bearer SingleFax API key with credits:checkout. Buyer pays at hosted Stripe continue_url; GET confirms ledger fulfillment. No inline payment handlers. See /commerce.md.", "parameters": [ { "in": "header", "name": "UCP-Agent", "required": true, "schema": { "type": "string" }, "example": "profile=\"https://platform.example/.well-known/ucp\"" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^com_[a-f0-9]{40}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Protocol checkout state", "content": { "application/json": { "schema": { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json" } } } }, "4XX": { "description": "Invalid request, authorization, unsupported feature or state conflict" }, "5XX": { "description": "Payment provider or service unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "line_items" ], "properties": { "line_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "item", "quantity" ], "properties": { "id": { "type": "string" }, "item": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "enum": [ "credit-pack-20", "credit-pack-50", "credit-pack-100" ] } } }, "quantity": { "type": "integer", "enum": [ 1 ] } } } } } } } } } } }, "/api/v1/commerce/ucp/checkout-sessions/{id}/cancel": { "post": { "operationId": "ucpCancel", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "summary": "UCP Cancel credit checkout", "description": "Requires a bearer SingleFax API key with credits:checkout. Buyer pays at hosted Stripe continue_url; GET confirms ledger fulfillment. No inline payment handlers. See /commerce.md.", "parameters": [ { "in": "header", "name": "UCP-Agent", "required": true, "schema": { "type": "string" }, "example": "profile=\"https://platform.example/.well-known/ucp\"" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^com_[a-f0-9]{40}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Protocol checkout state", "content": { "application/json": { "schema": { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json" } } } }, "4XX": { "description": "Invalid request, authorization, unsupported feature or state conflict" }, "5XX": { "description": "Payment provider or service unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/api/v1/commerce/ucp/checkout-sessions/{id}/complete": { "post": { "operationId": "ucpComplete", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "summary": "UCP Complete credit checkout", "description": "Requires a bearer SingleFax API key with credits:checkout. Buyer pays at hosted Stripe continue_url; GET confirms ledger fulfillment. No inline payment handlers. See /commerce.md.", "parameters": [ { "in": "header", "name": "UCP-Agent", "required": true, "schema": { "type": "string" }, "example": "profile=\"https://platform.example/.well-known/ucp\"" }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^com_[a-f0-9]{40}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Protocol checkout state", "content": { "application/json": { "schema": { "$ref": "https://ucp.dev/2026-08-25/schemas/shopping/checkout.json" } } } }, "4XX": { "description": "Invalid request, authorization, unsupported feature or state conflict" }, "5XX": { "description": "Payment provider or service unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "payment" ], "properties": { "payment": { "type": "object", "additionalProperties": false } } } } } } } }, "/api/v1/commerce/acp/checkout_sessions": { "post": { "operationId": "acpCreate", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "summary": "ACP Create credit checkout", "description": "Requires a bearer SingleFax API key with credits:checkout. Buyer pays at hosted Stripe continue_url; GET confirms ledger fulfillment. No inline payment handlers. See /commerce.md.", "parameters": [ { "in": "header", "name": "API-Version", "required": true, "schema": { "type": "string", "enum": [ "2026-04-17" ] } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "201": { "description": "Protocol checkout state", "content": { "application/json": { "schema": { "$ref": "https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSessionBase" } } } }, "4XX": { "description": "Invalid request, authorization, unsupported feature or state conflict" }, "5XX": { "description": "Payment provider or service unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "line_items", "currency", "capabilities" ], "properties": { "line_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "enum": [ "credit-pack-20", "credit-pack-50", "credit-pack-100" ] } } } }, "currency": { "type": "string", "enum": [ "usd" ] }, "capabilities": { "type": "object", "description": "Agent capabilities; no extensions or inline payment handlers are negotiated" } } } } } } } }, "/api/v1/commerce/acp/checkout_sessions/{id}": { "get": { "operationId": "acpGet", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "summary": "ACP Get credit checkout", "description": "Requires a bearer SingleFax API key with credits:checkout. Buyer pays at hosted Stripe continue_url; GET confirms ledger fulfillment. No inline payment handlers. See /commerce.md.", "parameters": [ { "in": "header", "name": "API-Version", "required": true, "schema": { "type": "string", "enum": [ "2026-04-17" ] } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^com_[a-f0-9]{40}$" } } ], "responses": { "200": { "description": "Protocol checkout state", "content": { "application/json": { "schema": { "$ref": "https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSessionBase" } } } }, "4XX": { "description": "Invalid request, authorization, unsupported feature or state conflict" }, "5XX": { "description": "Payment provider or service unavailable" } } }, "post": { "operationId": "acpUpdate", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "summary": "ACP Update credit checkout", "description": "Requires a bearer SingleFax API key with credits:checkout. Buyer pays at hosted Stripe continue_url; GET confirms ledger fulfillment. No inline payment handlers. See /commerce.md.", "parameters": [ { "in": "header", "name": "API-Version", "required": true, "schema": { "type": "string", "enum": [ "2026-04-17" ] } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^com_[a-f0-9]{40}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Protocol checkout state", "content": { "application/json": { "schema": { "$ref": "https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSessionBase" } } } }, "4XX": { "description": "Invalid request, authorization, unsupported feature or state conflict" }, "5XX": { "description": "Payment provider or service unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": { "line_items": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "enum": [ "credit-pack-20", "credit-pack-50", "credit-pack-100" ] } } } } } } } } } } }, "/api/v1/commerce/acp/checkout_sessions/{id}/cancel": { "post": { "operationId": "acpCancel", "tags": [ "commerce" ], "security": [ { "apiKey": [] } ], "summary": "ACP Cancel credit checkout", "description": "Requires a bearer SingleFax API key with credits:checkout. Buyer pays at hosted Stripe continue_url; GET confirms ledger fulfillment. No inline payment handlers. See /commerce.md.", "parameters": [ { "in": "header", "name": "API-Version", "required": true, "schema": { "type": "string", "enum": [ "2026-04-17" ] } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^com_[a-f0-9]{40}$" } }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "Protocol checkout state", "content": { "application/json": { "schema": { "$ref": "https://raw.githubusercontent.com/agentic-commerce-protocol/agentic-commerce-protocol/main/spec/2026-04-17/json-schema/schema.agentic_checkout.json#/$defs/CheckoutSessionBase" } } } }, "4XX": { "description": "Invalid request, authorization, unsupported feature or state conflict" }, "5XX": { "description": "Payment provider or service unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/api/v1/uploads": { "post": { "operationId": "createUpload", "tags": [ "uploads" ], "summary": "Create a short-lived upload capability", "description": "Returns an uploadToken and a PUT URL. Requires fax:send (API key) or a dashboard session.", "security": [ { "apiKey": [] }, { "bearerAuth": [] }, { "oauth2": [ "fax:send" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contentType": { "type": "string", "description": "MIME type. Allowed: application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/rtf, text/rtf, text/plain, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, image/png, image/jpeg, image/gif, image/webp, image/bmp, image/heic, image/heif, image/tiff" }, "maxBytes": { "type": "integer" } } } } } }, "responses": { "200": { "description": "Upload token + PUT URL", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadCapability" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing fax:send scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/uploads/{token}": { "put": { "operationId": "putUpload", "tags": [ "uploads" ], "summary": "Upload file bytes for a previously issued uploadToken", "description": "HMAC uploadToken in the path is sufficient (no API key). Chat MCP uses this so bytes never go through a tool call. Optional fax:send Bearer must match the token user.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stored", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadStored" } } } }, "401": { "description": "Invalid or expired upload token", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "413": { "description": "Upload too large", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } }, "get": { "operationId": "getUpload", "tags": [ "uploads" ], "summary": "Check whether an uploadToken has received bytes", "description": "HMAC uploadToken in the path is sufficient. Used by /mcp-upload and MCP create_upload polling.", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upload status", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadStatus" } } } }, "401": { "description": "Invalid or expired upload token", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/faxes": { "post": { "operationId": "sendFax", "tags": [ "faxes" ], "summary": "Send a fax (debits prepaid credits)", "security": [ { "apiKey": [] }, { "bearerAuth": [] }, { "oauth2": [ "fax:send" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendFaxRequest" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "to", "file" ], "properties": { "to": { "type": "string", "description": "E.164 destination" }, "file": { "type": "string", "format": "binary" }, "cover": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Queued fax order", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxOrder" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "402": { "description": "Insufficient credits", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing fax:send scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "409": { "description": "Idempotency conflict", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "429": { "description": "Rate limited", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } }, "get": { "operationId": "listFaxes", "tags": [ "faxes" ], "summary": "List faxes", "security": [ { "apiKey": [] }, { "bearerAuth": [] }, { "oauth2": [ "fax:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Fax list", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxList" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing fax:read scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/faxes/{id}": { "get": { "operationId": "getFax", "tags": [ "faxes" ], "summary": "Get fax status including latest provider attempt", "security": [ { "apiKey": [] }, { "bearerAuth": [] }, { "oauth2": [ "fax:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fax order", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaxOrderDetail" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing fax:read scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "404": { "description": "Fax not found", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/credits": { "get": { "operationId": "getCredits", "tags": [ "credits" ], "summary": "Credit balance and ledger", "security": [ { "apiKey": [] }, { "bearerAuth": [] }, { "oauth2": [ "credits:read" ] } ], "responses": { "200": { "description": "Balance", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalance" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing credits:read scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/received-faxes": { "get": { "operationId": "listReceivedFaxes", "tags": [ "inbox" ], "summary": "List received faxes", "description": "Paginated inbound inbox. Requires inbox:read. List excludes full transcripts. Held, HIPAA Secure, EIN, and ambiguous legacy rows return envelope/state only.", "security": [ { "apiKey": [] }, { "bearerAuth": [] }, { "oauth2": [ "inbox:read" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Received faxes", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedFaxList" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing inbox:read scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/received-faxes/{id}": { "get": { "operationId": "getReceivedFax", "tags": [ "inbox" ], "summary": "Get a received fax", "description": "Non-HIPAA released rows include extracted fields and a bounded transcript slice (offset). HIPAA Secure transcripts stay on the website dashboard. Requires inbox:read.", "security": [ { "apiKey": [] }, { "bearerAuth": [] }, { "oauth2": [ "inbox:read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Received fax", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedFaxDetail" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing inbox:read scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "404": { "description": "Not found", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/numbers": { "get": { "operationId": "listNumbers", "tags": [ "numbers" ], "summary": "List fax numbers", "description": "Active fax numbers for this account (and org teammates). After checkout, poll this to read the E.164. Requires fax:read.", "security": [ { "apiKey": [] }, { "bearerAuth": [] }, { "oauth2": [ "fax:read" ] } ], "responses": { "200": { "description": "Fax numbers", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboundNumberList" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing fax:read scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } }, "post": { "operationId": "createInboundNumber", "tags": [ "numbers" ], "summary": "Get a fax number (Stripe Checkout)", "description": "Reserve a dedicated fax number. Sufficient account credit pays one-time purchases without Stripe Checkout; otherwise returns checkoutUrl. Default sku inbound_30day. Also lifetime and subscription number SKUs. Optional country US|CA and state. Requires credits:checkout. Same as MCP create_inbound_number.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string", "description": "inbound_30day (default) | lifetime-basic | lifetime-pro | monthly-basic | annual-basic | monthly-business | annual-business" }, "country": { "type": "string", "enum": [ "US", "CA" ] }, "state": { "type": "string" } } } } } }, "responses": { "200": { "description": "Checkout URL plus reserved phoneNumber", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuCheckout" } } } }, "400": { "description": "Unknown fax number SKU", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing credits:checkout scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/credits/checkout": { "post": { "operationId": "createCreditCheckout", "tags": [ "credits" ], "summary": "Start Stripe Checkout for a credit pack", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amountCents": { "type": "integer", "minimum": 50, "example": 2000 } } } } } }, "responses": { "200": { "description": "Checkout URL", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditCheckout" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/skus": { "get": { "operationId": "listSkus", "tags": [ "catalog" ], "summary": "List product SKUs and prices", "description": "Public catalog. MCP checkout SKUs plus website-only HIPAA/EIN/IRS with URLs. Same payload as MCP list_skus.", "security": [], "responses": { "200": { "description": "SKU list", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuList" } } } } } } }, "/api/v1/faxes/quote": { "post": { "operationId": "quoteFax", "tags": [ "catalog", "faxes" ], "summary": "Quote a retail send without charging", "security": [ { "apiKey": [] }, { "bearerAuth": [] }, { "oauth2": [ "fax:read" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "E.164 destination" }, "pages": { "type": "integer", "minimum": 1, "maximum": 100 }, "base64": { "type": "string", "description": "Document bytes as base64 for a live page count (PDF, Office, text, or image)" }, "contentType": { "type": "string", "description": "Optional MIME. Allowed: application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/rtf, text/rtf, text/plain, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, image/png, image/jpeg, image/gif, image/webp, image/bmp, image/heic, image/heif, image/tiff" } } } } } }, "responses": { "200": { "description": "Send quote", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendQuote" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing fax:read scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/checkout": { "post": { "operationId": "createSkuCheckout", "tags": [ "catalog" ], "summary": "Start Stripe Checkout for a catalog SKU", "description": "sku: credit_pack | inbound_30day | monthly-basic | annual-basic | monthly-business | annual-business | lifetime-basic | lifetime-pro. HIPAA/EIN/IRS return website_only. Requires credits:checkout.", "security": [ { "apiKey": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "sku" ], "properties": { "sku": { "type": "string" }, "amountCents": { "type": "integer", "minimum": 50, "example": 2000 }, "country": { "type": "string", "enum": [ "US", "CA" ] }, "state": { "type": "string" } } } } } }, "responses": { "200": { "description": "Checkout URL or website handoff", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkuCheckout" } } } }, "400": { "description": "Unknown SKU", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "401": { "description": "Missing or invalid credentials", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "403": { "description": "Missing credits:checkout scope", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/machine/faxes/validate": { "post": { "operationId": "validateMachineFax", "tags": [ "machine" ], "summary": "Quote a machine/MPP fax without side effects", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "base64", "request_id" ], "properties": { "to": { "type": "string", "description": "Destination fax number in E.164", "example": "+14155552671" }, "base64": { "type": "string", "description": "Original document encoded as base64 (PDF, Office, text, or image). Do not convert to PDF first. We convert before sending." }, "request_id": { "type": "string", "description": "Client idempotency key for challenge + charge", "example": "mpp-validate-1" } } } } } }, "responses": { "200": { "description": "Quote", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineFaxQuote" } } } }, "503": { "description": "Service unavailable", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v1/machine/faxes": { "post": { "operationId": "createMachineFax", "tags": [ "machine" ], "summary": "Create machine fax (HTTP 402 MPP challenge when unpaid)", "description": "No API key. Unpaid requests return 402 + WWW-Authenticate: Payment (Stripe SPT or Tempo USDC). x402 clients also see PAYMENT-REQUIRED when that rail is enabled. Retry with Authorization: Payment … or PAYMENT-SIGNATURE.", "security": [], "x-payment-info": { "intent": "charge", "method": "stripe", "amount": "99", "currency": "usd", "description": "Minimum retail amount in cents. Pricing is dynamic; the HTTP 402 challenge contains the authoritative amount and available payment methods.", "price": { "mode": "dynamic", "currency": "USD", "min": "0.99", "max": "25.00" }, "protocols": [ { "mpp": { "method": "stripe", "intent": "charge", "currency": "USD" } }, { "mpp": { "method": "tempo", "intent": "charge", "currency": "USD" } }, { "x402": { "network": "eip155:8453", "currency": "USDC" } } ], "offers": [ { "amount": "99", "currency": "usd", "intent": "charge", "method": "stripe", "description": "Retail floor $0.99 (10 pages). Authoritative amount is in the 402 challenge." } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "to", "request_id" ], "anyOf": [ { "required": [ "base64" ] }, { "required": [ "uploadToken" ] } ], "properties": { "to": { "type": "string", "description": "Destination fax number in E.164", "example": "+14155552671" }, "base64": { "type": "string", "description": "Original document encoded as base64 (PDF, Office, text, or image). Do not convert to PDF first. We convert before sending." }, "uploadToken": { "type": "string", "description": "Optional upload token instead of base64" }, "request_id": { "type": "string", "description": "Client idempotency key for challenge + charge", "example": "mpp-validate-1" }, "cover": { "type": "boolean" } } }, "example": { "to": "+14155552671", "base64": "JVBERi0xLjEKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKMiAwIG9iago8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PgplbmRvYmoKMyAwIG9iago8PC9UeXBlL1BhZ2UvTWVkaWFCb3hbMCAwIDYxMiA3OTJdPj4KZW5kb2JqCnhyZWYKMCA0CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDU4IDAwMDAwIG4gCjAwMDAwMDAxMTUgMDAwMDAgbiAKdHJhaWxlcgo8PAovU2l6ZSA0Ci9Sb290IDEgMCBSCj4+CnN0YXJ0eHJlZgoxNzMKJSVFT0YK", "request_id": "mpp-validate-1" } } } }, "responses": { "200": { "description": "Paid order", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "id" ], "properties": { "request_id": { "type": "string" }, "id": { "type": "string" }, "fulfillmentStatus": { "type": "string" }, "paymentStatus": { "type": "string" }, "replay": { "type": "boolean" } } } } } }, "402": { "description": "Payment required (MPP challenge)", "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Payment challenge (Stripe SPT and Tempo USDC)" }, "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Present when x402 Base USDC is enabled. Retry with PAYMENT-SIGNATURE." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "503": { "description": "Service unavailable", "headers": { "RateLimit": { "description": "IETF RateLimit header (limit, remaining, reset seconds)", "schema": { "type": "string", "example": "limit=60, remaining=59, reset=60" } }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed in the current window" }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the window resets" }, "RateLimit-Policy": { "schema": { "type": "string", "example": "120;w=60" }, "description": "Quota and window (requests;w=seconds)" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Present on HTTP 429" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } } }, "x-service-info": { "categories": [ "communication", "fax" ], "docs": { "homepage": "https://singlefax.com", "apiReference": "https://singlefax.com/openapi.json", "developers": "https://singlefax.com/developers", "llms": "https://singlefax.com/llms.txt", "agents": "https://singlefax.com/agents", "mcp": "https://singlefax.com/mcp" } }, "components": { "schemas": { "JsonError": { "type": "object", "required": [ "error", "statusCode", "message" ], "properties": { "error": { "type": "boolean", "example": true }, "url": { "type": "string" }, "statusCode": { "type": "integer" }, "statusMessage": { "type": "string" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code" }, "resolution": { "type": "string", "description": "How an agent should recover" } } } } }, "UploadCapability": { "type": "object", "required": [ "uploadToken", "uploadUrl", "expiresAt" ], "properties": { "uploadToken": { "type": "string" }, "uploadUrl": { "type": "string", "format": "uri" }, "method": { "type": "string", "enum": [ "PUT" ] }, "key": { "type": "string" }, "contentType": { "type": "string" }, "maxBytes": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "UploadStored": { "type": "object", "required": [ "ok", "key", "bytes" ], "properties": { "ok": { "type": "boolean" }, "key": { "type": "string" }, "bytes": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "UploadStatus": { "type": "object", "required": [ "stored" ], "properties": { "stored": { "type": "boolean" }, "bytes": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "SendFaxRequest": { "type": "object", "required": [ "to" ], "properties": { "to": { "oneOf": [ { "type": "string", "description": "E.164 destination" }, { "type": "array", "maxItems": 10, "items": { "type": "string" }, "description": "One fax order per destination; Checkout is one hold" } ], "description": "Destination fax number(s) in E.164" }, "uploadToken": { "type": "string" }, "base64": { "type": "string", "description": "Document bytes as base64 (PDF, Word, Excel, PowerPoint, RTF, text, or image)" }, "contentType": { "type": "string", "description": "Optional MIME when sniffing is needed. Allowed: application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/rtf, text/rtf, text/plain, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, image/png, image/jpeg, image/gif, image/webp, image/bmp, image/heic, image/heif, image/tiff" }, "cover": { "type": "boolean" } } }, "FaxOrder": { "type": "object", "required": [ "id", "fulfillmentStatus", "paymentStatus" ], "properties": { "id": { "type": "string" }, "ids": { "type": "array", "items": { "type": "string" }, "description": "All order ids when sending to multiple destinations" }, "recipientCount": { "type": "integer" }, "fulfillmentStatus": { "type": "string" }, "paymentStatus": { "type": "string" }, "subtotalCents": { "type": "integer" }, "taxCents": { "type": "integer" }, "totalCents": { "type": "integer" }, "currency": { "type": "string" }, "billablePages": { "type": "integer" }, "destinationCountry": { "type": "string" }, "destinationFaxNumber": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "paymentChannel": { "type": "string" } } }, "FaxList": { "type": "object", "required": [ "data", "limit", "offset" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FaxOrder" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } }, "FaxAttempt": { "type": "object", "properties": { "attemptNumber": { "type": "integer" }, "status": { "type": "string" }, "providerFaxId": { "type": "string", "nullable": true }, "failureReason": { "type": "string", "nullable": true }, "failureClass": { "type": "string", "nullable": true }, "submittedAt": { "type": "string", "format": "date-time", "nullable": true }, "finishedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "FaxOrderDetail": { "allOf": [ { "$ref": "#/components/schemas/FaxOrder" }, { "type": "object", "properties": { "providerStatus": { "type": "string", "nullable": true }, "providerFaxId": { "type": "string", "nullable": true }, "failureReason": { "type": "string", "nullable": true }, "failureClass": { "type": "string", "nullable": true }, "attemptCount": { "type": "integer" }, "attempts": { "type": "array", "items": { "$ref": "#/components/schemas/FaxAttempt" } }, "destinationFaxNumber": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } ] }, "CreditBalance": { "type": "object", "required": [ "availableCents", "reservedCents" ], "properties": { "availableCents": { "type": "integer" }, "reservedCents": { "type": "integer" }, "ledger": { "type": "array", "items": { "type": "object" } } } }, "CreditCheckout": { "type": "object", "required": [ "checkoutUrl" ], "properties": { "checkoutUrl": { "type": "string", "format": "uri" }, "sessionId": { "type": "string" }, "creditCents": { "type": "integer" } } }, "InboundNumberList": { "type": "object", "required": [ "numbers", "total" ], "properties": { "total": { "type": "integer" }, "numbers": { "type": "array", "items": { "type": "object", "required": [ "id", "phoneNumber", "status" ], "properties": { "id": { "type": "string" }, "phoneNumber": { "type": "string" }, "status": { "type": "string" }, "orderType": { "type": "string", "nullable": true }, "planType": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "hipaaMode": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "remainingFreePages": { "type": "integer" } } } } } }, "ReceivedFaxList": { "type": "object", "required": [ "data", "limit" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedFaxListItem" } }, "nextCursor": { "type": "string", "nullable": true }, "limit": { "type": "integer" } } }, "ReceivedFaxListItem": { "type": "object", "required": [ "id", "faxId", "phoneNumber", "receivedAt" ], "properties": { "id": { "type": "string" }, "faxId": { "type": "string" }, "phoneNumber": { "type": "string" }, "fromPhone": { "type": "string", "nullable": true }, "pageCount": { "type": "integer" }, "receivedAt": { "type": "string", "format": "date-time" }, "releaseStatus": { "type": "string" }, "aiStatus": { "type": "string", "nullable": true }, "summary": { "type": "string" } } }, "ReceivedFaxDetail": { "type": "object", "required": [ "id", "faxId" ], "properties": { "id": { "type": "string" }, "faxId": { "type": "string" }, "phoneNumber": { "type": "string" }, "fromPhone": { "type": "string", "nullable": true }, "pageCount": { "type": "integer" }, "receivedAt": { "type": "string", "format": "date-time" }, "releaseStatus": { "type": "string" }, "aiStatus": { "type": "string", "nullable": true }, "summary": { "type": "string" }, "fields": { "type": "object", "nullable": true }, "documentUrl": { "type": "string", "format": "uri", "nullable": true }, "transcript": { "type": "object", "properties": { "transcript": { "type": "string" }, "offset": { "type": "integer" }, "totalLength": { "type": "integer" }, "nextOffset": { "type": "integer", "nullable": true } } } } }, "SkuList": { "type": "object", "required": [ "skus" ], "properties": { "skus": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "availability" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "priceCents": { "type": "integer", "nullable": true }, "priceLabel": { "type": "string" }, "availability": { "type": "string", "enum": [ "mcp", "website" ] }, "tool": { "type": "string" }, "checkoutSku": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "notes": { "type": "string" } } } } } }, "SendQuote": { "type": "object", "required": [ "sku" ], "properties": { "sku": { "type": "string", "example": "send" }, "to": { "type": "string" }, "destinationCountry": { "type": "string" }, "billablePages": { "type": "integer" }, "subtotalCents": { "type": "integer" }, "destinationAdjustmentCents": { "type": "integer" }, "pageBaseCents": { "type": "integer" }, "assumedPages": { "type": "boolean" }, "priceLabel": { "type": "string" } } }, "SkuCheckout": { "type": "object", "required": [ "status", "sku" ], "properties": { "status": { "type": "string", "enum": [ "awaiting_payment", "website_only", "provisioning" ] }, "sku": { "type": "string" }, "checkoutUrl": { "type": "string", "format": "uri" }, "orderId": { "type": "string" }, "phoneNumber": { "type": "string" }, "creditCents": { "type": "integer" }, "websiteUrl": { "type": "string", "format": "uri" }, "notes": { "type": "string" } } }, "MachineFaxRequest": { "type": "object", "required": [ "to", "request_id" ], "anyOf": [ { "required": [ "base64" ] }, { "required": [ "uploadToken" ] } ], "properties": { "to": { "type": "string", "description": "Destination fax number in E.164", "example": "+14155552671" }, "base64": { "type": "string", "description": "Original document encoded as base64 (PDF, Office, text, or image). Do not convert to PDF first. We convert before sending." }, "uploadToken": { "type": "string", "description": "Optional upload token instead of base64" }, "request_id": { "type": "string", "description": "Client idempotency key for challenge + charge", "example": "mpp-validate-1" }, "cover": { "type": "boolean" } } }, "MachineFaxQuote": { "type": "object", "required": [ "request_id", "amountCents", "currency" ], "properties": { "request_id": { "type": "string" }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "billablePages": { "type": "integer" }, "destinationCountry": { "type": "string" }, "protocol": { "type": "string", "example": "mpp" }, "methods": { "type": "array", "items": { "type": "string" } } } }, "MachineFaxOrder": { "type": "object", "required": [ "request_id", "id" ], "properties": { "request_id": { "type": "string" }, "id": { "type": "string" }, "fulfillmentStatus": { "type": "string" }, "paymentStatus": { "type": "string" }, "replay": { "type": "boolean" } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key: `Authorization: Bearer sf_live_…` or `sf_test_…`. Same credential as bearerAuth. Create keys at /dashboard/api-keys." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key: `Authorization: Bearer sf_live_…` or `sf_test_…`. Create keys at /dashboard/api-keys. Scopes: fax:read, fax:send, inbox:read, credits:read." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.1 (PKCE + DCR) for MCP. Resource https://singlefax.com/mcp. Discovery: /.well-known/oauth-protected-resource", "flows": { "authorizationCode": { "authorizationUrl": "https://api.singlefax.com/api/auth/oauth2/authorize", "tokenUrl": "https://api.singlefax.com/api/auth/oauth2/token", "refreshUrl": "https://api.singlefax.com/api/auth/oauth2/token", "scopes": { "openid": "OpenID Connect identifier", "profile": "Display name and profile", "email": "Account email", "offline_access": "Refresh token for long-lived agent sessions", "fax:read": "Read fax status and history", "fax:draft": "Create fax drafts (MCP Checkout or page-pool send)", "fax:send": "Upload documents and send faxes", "inbox:read": "Read received faxes (non-HIPAA transcripts and fields)", "credits:read": "Read prepaid credit balance", "credits:checkout": "Start credit purchases; AP2 charges require separate passkey approval" } } } } } } } ```