{ "openapi": "3.1.0", "info": { "title": "OffshoreProz Agent API", "version": "1.0.0", "description": "REST + MCP API for agent-native company formation.\n\n**Authentication:** Include your API key as `Authorization: Bearer op_test_...` (sandbox) or `Authorization: Bearer op_live_...` (live).\n\n**Sandbox vs Live:** Sandbox keys (`op_test_`) simulate all providers — no charges, no real filings. Live keys (`op_live_`) trigger real Stripe / DocuSeal calls.\n\n**Consent gate:** Before creating a formation, call `POST /v1/jurisdictions/{code}/estimate` to get an `estimate_token`. Pass it with `user_confirmed_cost_and_process: true` in the create request.\n\n**MCP:** Claude and other LLMs can use this API via `POST /mcp` (JSON-RPC 2.0). See the MCP section for tool definitions.\n\n⚠️ This API automates operational processes. It does not provide legal, tax, or financial advice.", "contact": { "name": "OffshoreProz", "url": "https://docs.offshoreproz.com/api", "email": "api@offshoreproz.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.offshoreproz.com", "description": "Production" }, { "url": "https://api.offshoreproz.com", "description": "Production" }, { "url": "https://api-staging.offshoreproz.com", "description": "Staging" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "System", "description": "Health check and API metadata" }, { "name": "Keys", "description": "Self-serve API key management" }, { "name": "Jurisdictions", "description": "Available jurisdictions and pricing" }, { "name": "Formations", "description": "Company formation lifecycle" }, { "name": "Actions", "description": "Owner-facing action token confirmation (portal)" }, { "name": "Documents", "description": "Formation document upload and download" }, { "name": "Webhooks", "description": "Outbound webhook endpoint management" }, { "name": "Admin", "description": "Ops/admin endpoints (ADMIN_API_TOKEN required)" }, { "name": "MCP", "description": "Model Context Protocol server for AI agents" }, { "name": "Beta", "description": "Beta waitlist" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "op_test_<64hex> | op_live_<64hex>", "description": "API key. Use `op_test_` for sandbox, `op_live_` for live. Obtain via POST /v1/keys." }, "AdminToken": { "type": "http", "scheme": "bearer", "description": "Admin API token (ADMIN_API_TOKEN env var). Not a customer API key." } }, "schemas": { "ApiError": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } }, "FormationStatus": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "JurisdictionCode": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] }, "Formation": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "jurisdiction": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] }, "company_name": { "type": "string" }, "amount_total_usd": { "type": "integer", "description": "Amount in USD cents" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } } } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "name": { "type": "string" }, "key": { "type": "string", "description": "Raw key — shown ONCE at creation only" }, "tier": { "type": "string", "enum": [ "standard", "premium" ] }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "paths": { "/health": { "get": { "operationId": "getHealth", "summary": "Health check", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "Worker is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "env": { "type": "string" }, "version": { "type": "string" }, "portal_db": { "type": "object", "properties": { "reachable": { "type": "boolean" }, "migration_082_applied": { "type": "boolean" }, "portal_sync_enabled": { "type": "boolean" } } } } }, "request_id": { "type": "string" } } } } } } } } }, "/v1/keys": { "post": { "operationId": "createApiKey", "summary": "Create API key", "description": "**Test keys** are issued immediately. **Live keys** require email OTP verification (POST /v1/keys/verify) and a Stripe payment method on file. Rate-limited: 5 per hour per email, 10 per hour per IP.", "tags": [ "Keys" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode", "name", "email" ], "properties": { "mode": { "type": "string", "enum": [ "test", "live" ] }, "name": { "type": "string", "description": "Human label for the key, e.g. 'My Agent'" }, "email": { "type": "string", "format": "email", "description": "Owner email. Used for OTP (live) and key lookup." } } } } } }, "responses": { "201": { "description": "Test key created immediately", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key": { "type": "string", "description": "Raw key — copy now, never shown again" }, "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test" ] }, "name": { "type": "string" } } }, "request_id": { "type": "string" } } } } } }, "202": { "description": "Live key: OTP sent — call POST /v1/keys/verify", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verification_required" ] }, "message": { "type": "string" }, "expires_in_seconds": { "type": "integer" } } }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } }, "get": { "operationId": "listApiKeys", "summary": "List my API keys", "description": "Lists all active (non-revoked) keys for the authenticated email.", "tags": [ "Keys" ], "responses": { "200": { "description": "Key list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "name": { "type": "string" }, "key": { "type": "string", "description": "Raw key — shown ONCE at creation only" }, "tier": { "type": "string", "enum": [ "standard", "premium" ] }, "created_at": { "type": "string", "format": "date-time" }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "revoked_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/keys/verify": { "post": { "operationId": "verifyApiKey", "summary": "Verify OTP and activate live key", "description": "Complete live key creation. OTP is emailed at POST /v1/keys. Also checks that a Stripe payment method is on file (402 if not).", "tags": [ "Keys" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "otp" ], "properties": { "email": { "type": "string", "format": "email" }, "otp": { "type": "string", "description": "6-digit code from email" } } } } } }, "responses": { "201": { "description": "Live key activated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "key": { "type": "string", "description": "Raw live key — copy now, never shown again" }, "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "live" ] } } }, "request_id": { "type": "string" } } } } } }, "402": { "description": "Payment method required — add a card at https://docs.offshoreproz.com/billing", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Invalid OTP, expired, or too many attempts", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/keys/{id}": { "delete": { "operationId": "revokeApiKey", "summary": "Revoke API key", "description": "Permanently revoke a key. Can only revoke keys belonging to the authenticated email.", "tags": [ "Keys" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key ID" } ], "responses": { "200": { "description": "Key revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "403": { "description": "Forbidden — operation not permitted for this key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/jurisdictions": { "get": { "operationId": "listJurisdictions", "summary": "List available jurisdictions", "description": "Returns all jurisdictions with pricing, timelines, and requirements. Available: WY (available), MI (pilot). No authentication required.", "tags": [ "Jurisdictions" ], "security": [], "parameters": [ { "name": "include_coming_soon", "in": "query", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Jurisdiction list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jurisdictions": { "type": "array" } } }, "request_id": { "type": "string" } } } } } } } } }, "/v1/jurisdictions/{code}": { "get": { "operationId": "getJurisdiction", "summary": "Get jurisdiction details", "tags": [ "Jurisdictions" ], "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] } } ], "responses": { "200": { "description": "Jurisdiction detail" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/jurisdictions/{code}/requirements": { "get": { "operationId": "getJurisdictionRequirements", "summary": "Required fields for a jurisdiction", "tags": [ "Jurisdictions" ], "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] } } ], "responses": { "200": { "description": "Required fields list" }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/jurisdictions/{code}/estimate": { "post": { "operationId": "estimateCost", "summary": "Estimate formation cost", "description": "Returns all-in cost breakdown and an `estimate_token` (30-minute TTL). **Required** before calling POST /v1/formations.", "tags": [ "Jurisdictions" ], "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "obtain_ein": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Cost estimate + token", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "estimate_token": { "type": "string", "description": "Pass to POST /v1/formations; expires in 30 min" }, "total_usd": { "type": "number" }, "breakdown": { "type": "object" }, "valid_for_seconds": { "type": "integer", "default": 1800 } } }, "request_id": { "type": "string" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Unprocessable — validation or state machine error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/formations": { "post": { "operationId": "createFormation", "summary": "Create formation", "description": "Start a company formation. Requires `estimate_token` from POST /v1/jurisdictions/{code}/estimate and explicit cost confirmation. Sandbox: simulates all providers. Live: triggers real Stripe/DocuSeal flows.", "tags": [ "Formations" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "description": "Idempotency key — safe to retry" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jurisdiction", "company_name", "estimate_token", "user_confirmed_cost_and_process", "beneficial_owner" ], "properties": { "jurisdiction": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] }, "company_name": { "type": "string" }, "company_purpose": { "type": "string" }, "estimate_token": { "type": "string", "description": "Token from POST /estimate (30min TTL)" }, "user_confirmed_cost_and_process": { "type": "boolean", "enum": [ true ], "description": "Must be true — consent gate" }, "obtain_ein": { "type": "boolean", "description": "WY only" }, "governance_model": { "type": "string", "enum": [ "on_chain", "hybrid", "traditional" ], "description": "MI only" }, "smart_contract_address": { "type": "string", "description": "MI only (optional)" }, "blockchain_network": { "type": "string", "description": "MI only (optional)" }, "beneficial_owner": { "type": "object", "required": [ "full_name", "email", "address" ], "properties": { "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "address": { "type": "string" }, "id_document_type": { "type": "string", "enum": [ "passport", "drivers_license", "national_id" ] }, "ownership_percentage": { "type": "number", "description": "MI only — percentage of governance (25%+ triggers KYC)" } } } } } } } }, "responses": { "201": { "description": "Formation created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "jurisdiction": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] }, "company_name": { "type": "string" }, "amount_total_usd": { "type": "integer", "description": "Amount in USD cents" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } } } } }, "request_id": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "403": { "description": "Live mode not enabled or key mode mismatch", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "409": { "description": "Idempotency key conflict", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Unprocessable — validation or state machine error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } }, "get": { "operationId": "listFormations", "summary": "List formations", "description": "Lists formations associated with the authenticated API key.", "tags": [ "Formations" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] } }, { "name": "jurisdiction", "in": "query", "schema": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Formation list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "jurisdiction": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] }, "company_name": { "type": "string" }, "amount_total_usd": { "type": "integer", "description": "Amount in USD cents" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } } } } } }, "total": { "type": "integer" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/formations/{id}": { "get": { "operationId": "getFormation", "summary": "Get formation status", "description": "Returns current status, next required actions, and provider details.", "tags": [ "Formations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Formation detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "jurisdiction": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] }, "company_name": { "type": "string" }, "amount_total_usd": { "type": "integer", "description": "Amount in USD cents" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } } } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/formations/{id}/retry": { "post": { "operationId": "retryFormation", "summary": "Retry failed formation", "description": "Resets a failed or action_required formation back to pending_owner_confirmation.", "tags": [ "Formations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retry initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "jurisdiction": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] }, "company_name": { "type": "string" }, "amount_total_usd": { "type": "integer", "description": "Amount in USD cents" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } } } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Unprocessable — validation or state machine error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/formations/{id}/events": { "get": { "operationId": "listFormationEvents", "summary": "Formation audit trail", "description": "Full audit trail — status changes, provider events, token actions, webhook deliveries.", "tags": [ "Formations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } } ], "responses": { "200": { "description": "Event list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formation_id": { "type": "string" }, "events": { "type": "array", "items": { "type": "object" } }, "count": { "type": "integer" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/formations/{id}/actions/reissue": { "post": { "operationId": "reissueActionLink", "summary": "Reissue action link", "description": "Reissue a fresh link for the current step (e.g. expired or lost). Invalidates the outstanding link for that step.", "tags": [ "Formations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "New action link", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formation_id": { "type": "string" }, "action_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "purpose": { "type": "string" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Unprocessable — validation or state machine error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/formations/{id}/cancel": { "delete": { "operationId": "cancelFormation", "summary": "Cancel formation", "description": "Cancel a formation. Only possible from draft or pending_owner_confirmation.", "tags": [ "Formations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Formation cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "jurisdiction": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] }, "company_name": { "type": "string" }, "amount_total_usd": { "type": "integer", "description": "Amount in USD cents" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } } } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Unprocessable — validation or state machine error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/actions/{token}": { "get": { "operationId": "getAction", "summary": "Inspect action token", "description": "Returns the purpose, label, expiry, and formation summary for an action token. Used by the portal page to render the owner confirmation UI.", "tags": [ "Actions" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "act_... token from action email" } ], "responses": { "200": { "description": "Action token info", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "owner_confirmation", "kyc", "payment", "signature" ] }, "label": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "formation": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "jurisdiction": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] }, "company_name": { "type": "string" }, "amount_total_usd": { "type": "integer", "description": "Amount in USD cents" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "next_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "url": { "type": "string" } } } } } } } }, "request_id": { "type": "string" } } } } } }, "422": { "description": "Token not found, expired, or already used", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/actions/{token}/confirm": { "post": { "operationId": "confirmAction", "summary": "Confirm action / advance formation", "description": "Owner confirms the action. **Sandbox:** simulates provider immediately, returns next action. **Live:** initiates real provider (Stripe Identity/Checkout/DocuSeal) and returns redirect URL. Owner completes at the provider, then webhook advances the status automatically.", "tags": [ "Actions" ], "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Required for payment (Stripe pre-fill) and signature (DocuSeal)" }, "name": { "type": "string", "description": "Required for signature step (DocuSeal)" } } } } } }, "responses": { "200": { "description": "Step completed (sandbox) or already completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "next_action": { "type": "object", "nullable": true, "properties": { "type": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string" } } } } }, "request_id": { "type": "string" } } } } } }, "202": { "description": "Live provider initiated — redirect owner to redirect_url", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] }, "redirect_url": { "type": "string", "format": "uri" }, "redirect_note": { "type": "string" }, "pilot_review": { "type": "boolean", "description": "true for MI — formation parked for ops review" } } }, "request_id": { "type": "string" } } } } } }, "422": { "description": "Token invalid/expired/consumed, or formation not in expected status", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/formations/{id}/documents": { "post": { "operationId": "uploadDocument", "summary": "Upload document", "description": "Upload a document for a formation. Stored in R2 under `agent-api/formations/{id}/`.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "type": { "type": "string" } } } } } }, "responses": { "201": { "description": "Document uploaded", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "size": { "type": "integer" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } }, "get": { "operationId": "listDocuments", "summary": "List formation documents", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "documents": { "type": "array" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/documents/{id}": { "get": { "operationId": "getDocument", "summary": "Get document metadata + download URL", "description": "Returns document metadata and a short-lived (5 min) signed download URL.", "tags": [ "Documents" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Document info + download_url", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "download_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/documents/{id}/download": { "get": { "operationId": "downloadDocument", "summary": "Stream document bytes", "description": "Streams the document from R2. Authenticated via short-lived `?token=` query param from GET /v1/documents/{id}.", "tags": [ "Documents" ], "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Short-lived KV token from GET /v1/documents/{id}" } ], "responses": { "200": { "description": "Document bytes", "content": { "application/octet-stream": {} } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/webhooks": { "post": { "operationId": "createWebhook", "summary": "Register webhook endpoint", "description": "Register a URL to receive formation events. Returns a `webhook_secret` (whsec_...) for signature verification. Events: formation.created, formation.status_changed, formation.complete, formation.pilot_review_pending.", "tags": [ "Webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Omit for all events" } } } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "webhook_secret": { "type": "string", "description": "whsec_... — used to verify signatures. Shown ONCE." } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } }, "get": { "operationId": "listWebhooks", "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Webhook list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "webhooks": { "type": "array" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Get webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook detail" }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Deactivate webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deactivated" }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Recent delivery attempts", "description": "Returns last 50 delivery attempts for a webhook endpoint, including status codes and error messages.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delivery log" }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/webhooks/stripe": { "post": { "operationId": "stripeWebhook", "summary": "Stripe inbound webhook", "description": "Receives Stripe events (`identity.verification_session.verified`, `identity.verification_session.requires_input`, `checkout.session.completed`). Signature-verified via `Stripe-Signature` header. Always returns 200 — processing is async.", "tags": [ "Webhooks" ], "security": [], "responses": { "200": { "description": "Acknowledged" } } } }, "/webhooks/docseal": { "post": { "operationId": "docsealWebhook", "summary": "DocuSeal inbound webhook", "description": "Receives DocuSeal `form.completed` events. Signature-verified via `X-Docuseal-Signature` header. Always returns 200 — processing is async.", "tags": [ "Webhooks" ], "security": [], "responses": { "200": { "description": "Acknowledged" } } } }, "/v1/admin/formations": { "get": { "operationId": "adminListFormations", "summary": "List formations (admin)", "description": "List all formations with optional filters. Requires ADMIN_API_TOKEN.", "tags": [ "Admin" ], "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "jurisdiction", "in": "query", "schema": { "type": "string", "enum": [ "WY", "MI", "NV", "BVI", "PA", "UAE" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "pending_owner_confirmation", "portal_synced", "kyc_pending", "kyc_review", "kyc_approved", "kyc_failed", "payment_pending", "payment_authorized", "signature_pending", "filing_ready", "filing_in_progress", "registration_complete", "ein_pending", "documents_ready", "complete", "action_required", "failed", "cancelled" ] } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "test", "live" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Formation list" }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/admin/formations/{id}": { "get": { "operationId": "adminGetFormation", "summary": "Get formation detail (admin)", "description": "Full formation detail including event history. Requires ADMIN_API_TOKEN.", "tags": [ "Admin" ], "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Formation + event history" }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/admin/formations/{id}/pilot/approve": { "post": { "operationId": "adminPilotApprove", "summary": "Approve MI pilot review", "description": "Advance a formation from `action_required` (pilot review gate) to `kyc_pending`. Mints a KYC action token and emails the link to the owner.", "tags": [ "Admin" ], "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Formation advanced to kyc_pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "kyc_pending" ] }, "kyc_action_url": { "type": "string", "format": "uri" }, "kyc_token_expires_at": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Unprocessable — validation or state machine error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/admin/formations/{id}/pilot/reject": { "post": { "operationId": "adminPilotReject", "summary": "Reject MI pilot review", "description": "Set a formation from `action_required` to `failed` with a reason.", "tags": [ "Admin" ], "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "default": "rejected_by_ops" } } } } } }, "responses": { "200": { "description": "Formation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formation_id": { "type": "string" }, "status": { "type": "string" }, "reason": { "type": "string" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Unprocessable — validation or state machine error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/admin/formations/{id}/filing/start": { "post": { "operationId": "adminFilingStart", "summary": "Start filing (ops hand-off)", "description": "Advance formation from `filing_ready` to `filing_in_progress`. Called by ops when they begin the state filing.", "tags": [ "Admin" ], "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Filing started" }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Unprocessable — validation or state machine error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/admin/formations/{id}/filing/complete": { "post": { "operationId": "adminFilingComplete", "summary": "Complete filing", "description": "Walk the formation from `filing_in_progress` through `registration_complete → ein_pending → documents_ready → complete`. Emails the owner a registration completion notice.", "tags": [ "Admin" ], "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Filing complete", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "complete" ] }, "filing_reference": { "type": "string" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "422": { "description": "Unprocessable — validation or state machine error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/admin/keys": { "get": { "operationId": "adminListKeys", "summary": "List all API keys (admin)", "tags": [ "Admin" ], "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "test", "live" ] } }, { "name": "include_revoked", "in": "query", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Key list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "keys": { "type": "array" }, "total": { "type": "integer" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/admin/keys/{id}/revoke": { "post": { "operationId": "adminRevokeKey", "summary": "Force-revoke API key (admin)", "tags": [ "Admin" ], "security": [ { "AdminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Key revoked" }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/v1/admin/stats": { "get": { "operationId": "adminStats", "summary": "Aggregate stats (admin)", "description": "Formation counts by status and jurisdiction, key stats, and pilot review queue depth.", "tags": [ "Admin" ], "security": [ { "AdminToken": [] } ], "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "formations": { "type": "object", "properties": { "by_status": { "type": "array" }, "by_jurisdiction": { "type": "array" } } }, "api_keys": { "type": "object", "properties": { "total": { "type": "integer" }, "live": { "type": "integer" }, "test": { "type": "integer" }, "revoked": { "type": "integer" } } }, "pilot_review_queue": { "type": "integer", "description": "Live formations waiting for ops review (action_required)" } } }, "request_id": { "type": "string" } } } } } }, "401": { "description": "Unauthorized — invalid or missing API key", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } }, "/mcp": { "get": { "operationId": "mcpDiscovery", "summary": "MCP discovery hint", "description": "Human-readable page describing the MCP server. For programmatic access, use POST /mcp.", "tags": [ "MCP" ], "security": [], "responses": { "200": { "description": "HTML page" } } }, "post": { "operationId": "mcpRpc", "summary": "MCP JSON-RPC 2.0 server", "description": "Model Context Protocol server for AI agents (Claude, GPT-4, etc.).\n\n**Available tools:**\n- `offshoreproz_list_jurisdictions` — list available jurisdictions\n- `offshoreproz_get_jurisdiction_requirements` — required fields for a jurisdiction\n- `offshoreproz_estimate_cost` — estimate all-in cost + issue estimate_token\n- `offshoreproz_create_formation` — create company (requires estimate_token + API key)\n- `offshoreproz_get_formation_status` — get current status (requires API key)\n- `offshoreproz_list_documents` — list formation documents (requires API key)", "tags": [ "MCP" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method", "id" ], "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "method": { "type": "string", "enum": [ "tools/list", "tools/call" ] }, "id": { "type": [ "string", "integer", "null" ] }, "params": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name (for tools/call)" }, "arguments": { "type": "object", "description": "Tool input arguments" } } } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response (result or error)" } } } }, "/v1/beta/waitlist": { "post": { "operationId": "joinWaitlist", "summary": "Join beta waitlist", "description": "Request API access. Idempotent on email — safe to re-submit.", "tags": [ "Beta" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "name", "use_case" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "use_case": { "type": "string", "description": "What you'll build with the API" }, "company": { "type": "string" } } } } } }, "responses": { "200": { "description": "Already on waitlist" }, "201": { "description": "Added to waitlist" }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "request_id" ], "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "request_id": { "type": "string", "format": "uuid" }, "docs": { "type": "string", "format": "uri", "description": "Link to error documentation" } } } } } } } } } } }