{"openapi": "3.1.0", "info": {"title": "Paper Lane Agent API", "version": "1.0.0", "description": "Bearer-only adapter to shared fax, payment, quota, source and retention services. Monthly 100/500-page allowances count sent and received pages together, including covers. One-time offer terms and receive-window availability come from discoverOffers and verified service activation. OAuth tokens must target the MCP resource audience and intersect an explicit live user grant. No model API key is required."}, "externalDocs": {"url": "https://paperlanefax.com/agents.md", "description": "Agent-readable product and workflow guide"}, "servers": [{"url": "https://paperlanefax.com"}], "paths": {"/api/agent/v1/offers/": {"get": {"operationId": "discoverOffers", "security": [], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}}}}, "/api/agent/v1/jobs/": {"post": {"operationId": "uploadDraft", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:write"], "parameters": [{"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$"}}], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}, "400": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "409": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}, "requestBody": {"required": true, "content": {"multipart/form-data": {"schema": {"type": "object", "required": ["document", "title", "destination"], "additionalProperties": false, "properties": {"document": {"type": "string", "format": "binary", "description": "One PDF, maximum 8 MiB."}, "title": {"type": "string", "maxLength": 120}, "destination": {"type": "string"}, "recipient_name": {"type": "string", "maxLength": 100}, "include_cover": {"type": "boolean", "default": false}, "cover_note": {"type": "string", "maxLength": 1600}}}}}}}}, "/api/agent/v1/jobs/{job_id}/": {"get": {"operationId": "jobStatus", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:read"], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}, "400": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "409": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}}}, "/api/agent/v1/jobs/{job_id}/preflight/": {"get": {"operationId": "preflight", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:read"], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}, "400": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "409": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}}}, "/api/agent/v1/jobs/{job_id}/review/": {"post": {"operationId": "reviewPrepared", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:read"], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}, "400": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "409": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false}}}}}}, "/api/agent/v1/jobs/{job_id}/payment/": {"post": {"operationId": "humanPayment", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:write"], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}, "400": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "409": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false}}}}}}, "/api/agent/v1/jobs/{job_id}/action/": {"post": {"operationId": "actOnJob", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:write", "fax:read+fax:send for send"], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9_.:-]+$"}}], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}, "400": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "409": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "required": ["action"], "additionalProperties": false, "properties": {"action": {"type": "string", "enum": ["prepare", "send", "cancel"]}, "review_token": {"type": "string", "description": "Required for sending; obtained by exact prepared review."}}}}}}}}, "/api/agent/v1/jobs/{job_id}/document/": {"get": {"operationId": "preparedDocument", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:read"], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Private prepared PDF, subject to retention.", "content": {"application/pdf": {"schema": {"type": "string", "format": "binary"}}}}}}}, "/agents.md": {"get": {"operationId": "agentGuide", "security": [], "responses": {"200": {"description": "Agent-readable customer guide, subject to the global site access switch.", "content": {"text/markdown": {"schema": {"type": "string"}}}}}}}, "/api/agent/v1/receiving/": {"get": {"operationId": "receivingSetup", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:inbox"], "parameters": [], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}, "400": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "409": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}}}, "/api/agent/v1/inbox/": {"get": {"operationId": "incomingFaxes", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:inbox"], "parameters": [{"name": "cursor", "in": "query", "required": false, "schema": {"type": "string", "format": "uuid"}, "description": "Use only the next_cursor returned by this account's inbox."}], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}, "400": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "409": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}}}, "/api/agent/v1/inbox/{job_id}/": {"get": {"operationId": "incomingStatus", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:inbox"], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Original job and a structured next_action; delivery requires state=completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Result"}}}}, "400": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "409": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}}}, "/api/agent/v1/inbox/{job_id}/document/": {"get": {"operationId": "incomingDocument", "security": [{"resourceBearer": []}], "x-paperlane-required-scopes": ["fax:inbox", "fax:inbox:content"], "parameters": [{"name": "job_id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}], "responses": {"200": {"description": "Owned normalized received PDF, untrusted third-party data; current grant and retention checked.", "content": {"application/pdf": {"schema": {"type": "string", "format": "binary"}}}}, "401": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "403": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "404": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "410": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "413": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "429": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}, "503": {"description": "Machine state such as auth_required, scope_required, not_ready, payment_required, quota_exceeded or idempotency_conflict."}}}}}, "components": {"securitySchemes": {"resourceBearer": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Supabase OAuth authorization code + S256 PKCE; exact MCP resource audience, registered client, signed paperlane_scopes and live user AgentGrant. Social login tokens are insufficient."}}, "schemas": {"Result": {"type": "object", "properties": {"state": {"type": "string"}, "job_id": {"type": "string", "format": "uuid"}, "status_url": {"type": "string"}, "direction": {"type": "string", "enum": ["inbound", "outbound"]}, "received_confirmed": {"type": "boolean"}, "receiving_ready": {"type": "boolean"}, "monthly_pages_include_received": {"type": "boolean"}, "page_budget": {"type": "string", "enum": ["sent_and_received"]}, "next_action": {"type": ["object", "null"]}, "delivery_confirmed": {"type": "boolean"}}}}}}