{ "openapi": "3.1.0", "info": { "title": "Salesbooth API", "version": "1.0.0", "description": "REST API for managing deals, customers, products, contracts, and API keys in Salesbooth. Designed for both human and AI agent integration.\n\n**Authentication:** All API keys must be passed via the `Authorization: Bearer` header or `X-API-Key` header. The only exception is the SSE `/events/stream` endpoint, which accepts `api_key` as a query parameter because the browser EventSource API cannot send custom headers.", "contact": { "name": "Salesbooth", "url": "https://salesbooth.com" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "servers": [ { "url": "https://salesbooth.com/api/v1", "description": "Salesbooth API (Production)" }, { "url": "https://api-au.salesbooth.com/api/v1", "description": "Australia region" }, { "url": "https://api-eu.salesbooth.com/api/v1", "description": "Europe region" }, { "url": "https://api-us.salesbooth.com/api/v1", "description": "United States region" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "Deals", "description": "Manage deals and the deal lifecycle" }, { "name": "Customers", "description": "Manage customer records" }, { "name": "Products", "description": "Manage products and services" }, { "name": "Contracts", "description": "Manage contracts and agreements" }, { "name": "API Keys", "description": "Manage API keys (session auth required)" }, { "name": "Discovery", "description": "Agent deal discovery \u2014 browse available offers" }, { "name": "Negotiations", "description": "Agent-to-agent deal negotiation protocol" }, { "name": "Templates", "description": "Reusable deal templates for programmatic offer generation" }, { "name": "Delegations", "description": "Agent authorization delegations with spending limits and delegation chains" }, { "name": "Sandbox", "description": "Sandbox environment management \u2014 reset, seed test data, simulate webhooks. Requires test API key (sb_test_*)." }, { "name": "Webhooks", "description": "Webhook management, event replay, dead letter queue, and delivery monitoring" }, { "name": "Audit", "description": "Immutable audit trail retrieval, verification, and compliance evidence export" }, { "name": "Schema", "description": "Machine-readable schema definitions for state machines and entity metadata. No authentication required." }, { "name": "Payments", "description": "Payment lifecycle management via Stripe PaymentIntents \u2014 create, confirm, and refund payments for deals" }, { "name": "Stripe Webhooks", "description": "Incoming Stripe webhook event processing. Signature-verified, no API authentication required." }, { "name": "BundleRules", "description": "Bundle pricing rules \u2014 define discount conditions when multiple options are selected together" }, { "name": "CompatibilityRules", "description": "Option compatibility rules \u2014 define requires, excludes, and includes_price relationships between options" }, { "name": "OptionGroups", "description": "Option groups and individual options \u2014 reusable configuration building blocks" }, { "name": "ProductFamilies", "description": "Product families \u2014 top-level groupings for organizing related products" }, { "name": "ProductOptionGroups", "description": "Product-to-option-group links and per-product option availability overrides" }, { "name": "ProductRules", "description": "Aggregate product rules view and configuration validation" }, { "name": "Uploads", "description": "Image file uploads for product images, option swatches, and other assets" }, { "name": "SavedConfigs", "description": "Saved buyer configurations with shareable URLs \u2014 build snapshots for CPQ" }, { "name": "Configuration", "description": "Unified CPQ configuration \u2014 schema retrieval, validation, and pricing for AI agent deal building" }, { "name": "WidgetAnalytics", "description": "Per-widget conversion analytics \u2014 beacon ingestion and funnel metrics" }, { "name": "WidgetConfig", "description": "Widget configuration CRUD \u2014 manage embedded deal widget settings, step names, and CTA text" }, { "name": "WidgetIntelligence", "description": "Widget intelligence \u2014 aggregated social proof, popularity badges, and smart defaults for widget rendering" }, { "name": "Agent Tools", "description": "AI agent tool schema and MCP server \u2014 machine-readable capability discovery for LLM function-calling" }, { "name": "System", "description": "System health checks and observability endpoints" }, { "name": "Credits", "description": "Prepaid credit balance management \u2014 check balance, top up via Stripe Checkout, view ledger history, and estimate deal costs" }, { "name": "Trust", "description": "Tenant trust level system \u2014 view trust status, progress metrics, auto top-up ceilings, and level change history" }, { "name": "Billing", "description": "Billing dashboard \u2014 credit balance, top-up via Stripe Checkout, auto top-up configuration, ledger history, usage charts, and alert settings" }, { "name": "USDC", "description": "USDC payment rail for AI agent accounts. Agents deposit any supported crypto via Coinbase (auto-converted to USDC) and balances are consumed per request. Human accounts use the Stripe/Billing path instead." }, { "name": "AgentDiscovery", "description": "Agent discovery admin \u2014 merchant control plane for AI-visible offers, product discoverability, agent analytics, and deal preview" }, { "name": "Security", "description": "Security monitoring \u2014 CSP violation report collection and alerting" }, { "name": "AgentWorkflows", "description": "Autonomous deal orchestration \u2014 plan and execute multi-step deal workflows within delegation spending limits" }, { "name": "AgentTrust", "description": "Agent trust levels \u2014 per-API-key trust scoring, trust locks for capability gating, promotion/demotion, and abuse protection" }, { "name": "GDPR", "description": "GDPR compliance \u2014 data subject rights, erasure, consent management, retention policies, and processing register" }, { "name": "Federation", "description": "Cross-instance agent-to-agent deal negotiation protocol \u2014 discovery manifests, signed negotiation envelopes, escrow coordination, and federated audit trails" }, { "name": "Events", "description": "Real-time event streaming via Server-Sent Events \u2014 subscribe to deal, negotiation, payment, and other domain events with automatic reconnection and missed-event recovery" }, { "name": "Staff", "description": "Staff member management \u2014 create, schedule, and assign service providers to bookable products" }, { "name": "Availability", "description": "Calendar availability \u2014 check available dates and time slots for bookable products" }, { "name": "Bookings", "description": "Service booking lifecycle \u2014 hold, confirm, complete, cancel, and track appointment bookings" }, { "name": "Playground", "description": "SDK Playground \u2014 provision ephemeral sandbox sessions with auto-generated test API keys for interactive SDK exploration" }, { "name": "SiteSuggestions", "description": "AI-driven site optimization suggestions \u2014 list, accept, reject, and rollback conversion improvement recommendations generated from session replay analysis" }, { "name": "CustomerPortal", "description": "Customer portal authentication and self-service \u2014 magic-link login, deal viewing, contract signing, payment, and profile management" }, { "name": "Activity", "description": "Activity feed, notifications, and notification rules \u2014 real-time event log and configurable notification preferences" }, { "name": "Auth", "description": "Session-based authentication for SPA clients \u2014 login, session check, and logout" }, { "name": "Batch", "description": "Multi-resource batch operations \u2014 execute up to 25 API operations in a single request with transaction support" }, { "name": "Budget", "description": "Monthly budget settings and spend tracking \u2014 configure limits and alert thresholds for tenant usage spending" }, { "name": "BusinessProfile", "description": "Business profile management \u2014 store and retrieve the tenant's business description for AI website generation" }, { "name": "Cache", "description": "Cache statistics and admin \u2014 view cache metrics and flush or invalidate cache entries" }, { "name": "Channels", "description": "Communication channel settings \u2014 configure phone numbers and email addresses for tenant communications" }, { "name": "Chat", "description": "AI assistant chat \u2014 streaming conversation with the Salesbooth AI business assistant" }, { "name": "Dashboard", "description": "Dashboard statistics \u2014 consolidated counts, pipeline analytics, revenue time-series, and attention items" }, { "name": "Import", "description": "CSV import wizard \u2014 parse, validate, and execute bulk imports for customers and products" }, { "name": "NegotiationsDashboard", "description": "Merchant negotiation management \u2014 dashboard stats, active negotiations list, accept/counter/reject proposals, and auto-accept threshold" }, { "name": "Onboarding", "description": "User and workspace onboarding wizard \u2014 create new accounts and workspaces via 10-step guided flow" }, { "name": "Plugins", "description": "Plugin marketplace and installation \u2014 browse available plugins, install, and uninstall for a tenant" }, { "name": "Preferences", "description": "User and tenant preferences \u2014 display mode settings and per-scope metadata preferences" }, { "name": "Profile", "description": "Current user profile \u2014 read and update personal name and phone number" }, { "name": "TenantSettings", "description": "Tenant-level settings \u2014 business details, branding, and currency preference" }, { "name": "AnalyticsSettings", "description": "Analytics tracking settings \u2014 toggle tracking features and configure privacy options" }, { "name": "Queue", "description": "Job queue admin \u2014 monitor background job statistics, inspect dead jobs, retry failed jobs, and purge completed jobs" }, { "name": "Realtime", "description": "OpenAI Realtime API integration \u2014 ephemeral session tokens, function call execution, and usage reporting for voice assistant" }, { "name": "Search", "description": "Global search \u2014 full-text search across customers, products, deals, and contracts" }, { "name": "SiteBlocks", "description": "Reusable site content blocks \u2014 create, read, update, and delete reusable HTML blocks within a site" }, { "name": "SitePages", "description": "Website page CRUD \u2014 create, read, update, and delete pages within a site" }, { "name": "Sites", "description": "Website/site CRUD \u2014 create, read, update, and delete tenant websites" }, { "name": "SystemAdmin", "description": "System admin panel \u2014 tenant management, impersonation, system settings, key rotation, and credit grants (system admin only)" }, { "name": "TTS", "description": "Text-to-Speech \u2014 convert text to natural-sounding speech using OpenAI TTS, with streaming or base64 JSON response" }, { "name": "Twilio", "description": "SMS, voice, and email operations via Twilio/SendGrid \u2014 send messages, initiate calls, and manage Twilio credentials" }, { "name": "Usage", "description": "Usage logs and analytics \u2014 view usage logs, monthly summaries, and daily breakdowns for the current tenant" }, { "name": "Verify", "description": "Public credential verification \u2014 verify the signature and status of Salesbooth verifiable credentials (no authentication required)" }, { "name": "Websites", "description": "AI-powered website generation and domain management \u2014 generate complete websites using AI and check domain availability" }, { "name": "WidgetContract", "description": "Widget contract generation and signing \u2014 generate contract HTML from templates and capture digital signatures for the embedded deal widget" }, { "name": "WidgetDiscount", "description": "Widget promo code validation \u2014 validate discount codes with rate limiting for embedded deal widget checkout" }, { "name": "ABTests", "description": "A/B testing for widget configurations \u2014 create, promote, and resolve split tests for embedded widget variants" }, { "name": "FxRate", "description": "Foreign exchange rate lookups \u2014 retrieve live FX rates for multi-currency deal pricing" }, { "name": "Intelligence", "description": "Deal intelligence and scoring \u2014 AI-powered deal health scores, recommendations, and win probability analysis" }, { "name": "SavedConfigsAdmin", "description": "Admin management of saved configurations \u2014 list, inspect, and delete tenant saved CPQ configurations" }, { "name": "Subscriptions", "description": "Subscription management \u2014 manage recurring billing plans and subscription lifecycle" }, { "name": "Team", "description": "Team member management \u2014 invite, update roles, and remove team members from a tenant workspace" }, { "name": "Tenants", "description": "Multi-tenant context switching and workspace management" }, { "name": "Replays", "description": "Session replay collection \u2014 ingest and store client-side replay events for site analytics" }, { "name": "Documents", "description": "Agent quote and invoice generation, customer notification delivery, and contact preference retrieval \u2014 enables agents to communicate structured offers autonomously" }, { "name": "PricingSimulation", "description": "Simulate bundle pricing, compare cart scenarios, and analyze negotiation history" }, { "name": "WidgetPaymentPreview", "description": "Widget payment preview \u2014 estimate payment amounts and deposit breakdowns before checkout" }, { "name": "WidgetValidate", "description": "Widget form validation \u2014 server-side validation of customer input fields" } ], "x-tagGroups": [ { "name": "Core Commerce", "tags": [ "Deals", "Customers", "Products", "Contracts", "Payments", "Subscriptions", "Search", "CustomerPortal" ] }, { "name": "Deal Configuration (CPQ)", "tags": [ "Configuration", "ProductFamilies", "OptionGroups", "ProductOptionGroups", "ProductRules", "BundleRules", "CompatibilityRules", "SavedConfigs", "SavedConfigsAdmin", "Templates", "PricingSimulation" ] }, { "name": "Embedded Widgets", "tags": [ "WidgetConfig", "WidgetAnalytics", "WidgetIntelligence", "WidgetContract", "WidgetDiscount", "WidgetPaymentPreview", "WidgetValidate", "ABTests" ] }, { "name": "Bookings & Scheduling", "tags": [ "Bookings", "Staff", "Availability" ] }, { "name": "Websites", "tags": [ "Sites", "SitePages", "SiteBlocks", "SiteSuggestions", "Websites", "Replays" ] }, { "name": "AI Agents", "tags": [ "Agent Tools", "AgentDiscovery", "AgentWorkflows", "AgentTrust", "Delegations", "Discovery", "Negotiations", "NegotiationsDashboard", "Federation", "Documents" ] }, { "name": "Payments & Billing", "tags": [ "Billing", "Credits", "Budget", "Trust", "USDC", "FxRate" ] }, { "name": "Webhooks & Events", "tags": [ "Webhooks", "Events", "Stripe Webhooks", "Activity" ] }, { "name": "Intelligence & AI", "tags": [ "Intelligence", "Chat", "Realtime", "TTS" ] }, { "name": "Compliance", "tags": [ "GDPR", "Audit", "Security", "Verify" ] }, { "name": "Workspace Management", "tags": [ "Auth", "Tenants", "Team", "Profile", "Preferences", "TenantSettings", "BusinessProfile", "Channels", "AnalyticsSettings", "Onboarding", "Plugins", "Import", "Uploads", "Twilio" ] }, { "name": "Developer Tools", "tags": [ "API Keys", "Sandbox", "Playground", "Schema", "Batch", "Queue", "Cache", "Dashboard", "Usage", "SystemAdmin", "System" ] } ], "paths": { "/api": { "servers": [ { "url": "https://salesbooth.com", "description": "Salesbooth API root" } ], "get": { "tags": [ "System" ], "summary": "API discovery and endpoint listing", "description": "Returns API discovery information including available endpoints, authentication methods, agent integration details, and a link to the OpenAPI specification. No authentication required.", "operationId": "getApiIndex", "security": [], "responses": { "200": { "description": "API discovery information", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Salesbooth API" }, "version": { "type": "string", "example": "1.0.0" }, "base_url": { "type": "string" }, "documentation": { "type": "string" }, "openapi_spec": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/health": { "get": { "tags": [ "System" ], "summary": "Get system health status", "description": "Public endpoint returning system health for external monitoring tools. Supports probe types: liveness (PHP alive, no dependency checks), readiness (503 if dependencies are down), or default (full report, always 200). Use ?type=liveness for Nginx upstream health checks to prevent 'no healthy upstream' errors during partial outages.", "operationId": "getHealthCheck", "security": [], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Probe type: liveness (minimal, always 200), readiness (503 if unhealthy), or omit for full health report (always 200).", "schema": { "type": "string", "enum": [ "liveness", "readiness" ] } } ], "responses": { "200": { "description": "System is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "healthy", "unhealthy" ] }, "timestamp": { "type": "string", "format": "date-time" }, "checks": { "type": "object", "properties": { "job_queue": { "type": "object", "description": "Job queue depth per topic", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded", "unknown" ] }, "total_pending": { "type": "integer", "description": "Total pending jobs across all topics" }, "by_topic": { "type": "object", "description": "Per-topic queue depth with pending and processing counts", "additionalProperties": { "type": "object", "properties": { "pending": { "type": "integer" }, "processing": { "type": "integer" } } } } } }, "circuit_breakers": { "type": "object", "description": "Circuit breaker status for external service dependencies", "properties": { "status": { "type": "string", "enum": [ "healthy", "degraded" ] }, "services": { "type": "object", "properties": { "stripe": { "type": "string", "enum": [ "closed", "open", "half_open" ] }, "twilio": { "type": "string", "enum": [ "closed", "open", "half_open" ] }, "email": { "type": "string", "enum": [ "closed", "open", "half_open" ] } } } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" }, "503": { "description": "System is unhealthy" } } } }, "/collect": { "post": { "tags": [ "Replays" ], "summary": "Collect session replay events", "description": "Accepts base64-encoded session replay event payloads from SDK clients. Creates or updates a replay session record and appends events to a per-session JSONL file. No authentication required.", "operationId": "collectEvents", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "enc", "data", "host" ], "properties": { "session_id": { "type": "string", "description": "Client session identifier" }, "enc": { "type": "string", "enum": [ "b64" ], "description": "Encoding type for the data field" }, "data": { "type": "string", "description": "Base64-encoded JSON payload containing events array" }, "host": { "type": "string", "description": "Customer domain the events originated from" }, "timezone": { "type": "string", "description": "Client timezone (optional)" } } } } } }, "responses": { "204": { "description": "Events accepted" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/widget-analytics": { "post": { "tags": [ "WidgetAnalytics" ], "summary": "Record widget analytics event", "description": "Receives analytics beacon events from embedded widgets. Uses publishable API key for authentication. Non-blocking \u2014 always returns 202.", "operationId": "postWidgetAnalytics", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "api_key", "session_id", "event_type" ], "properties": { "api_key": { "type": "string", "description": "Publishable API key (sb_pub_*)" }, "session_id": { "type": "string", "description": "Client-generated session identifier" }, "event_type": { "type": "string", "enum": [ "impression", "step-change", "product-selected", "customer-entered", "payment-started", "deal-created", "payment-completed", "abandoned", "error", "terms-accepted" ] }, "step": { "type": "string", "description": "Current widget step" }, "data": { "type": "object", "description": "Event-specific data (PII-free)" } } } } } }, "responses": { "202": { "description": "Event accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "tags": [ "WidgetAnalytics" ], "summary": "Retrieve widget analytics data", "description": "Returns aggregated widget analytics including funnel data, conversion metrics, abandonment analysis, and trend data.", "operationId": "getWidgetAnalytics", "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "widget_id", "in": "query", "description": "Filter by specific widget ID", "required": false, "schema": { "type": "string" } }, { "name": "days", "in": "query", "description": "Number of days to look back (1-90, default 30)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 90, "default": 30 } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "events" ] }, "description": "Set to \"events\" to return the raw events list instead of aggregated analytics" } ], "responses": { "200": { "description": "Analytics data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "data": { "type": "object", "properties": { "funnel": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "sessions": { "type": "integer" } } } }, "metrics": { "type": "object", "properties": { "impressions": { "type": "integer" }, "completions": { "type": "integer" }, "deals_created": { "type": "integer" }, "conversion_rate": { "type": "number" }, "total_revenue": { "type": "number" }, "deal_count": { "type": "integer" }, "avg_deal_value": { "type": "number" } } }, "abandonment": { "type": "array", "items": { "type": "object", "properties": { "abandon_step": { "type": "string", "nullable": true }, "abandon_count": { "type": "integer" }, "avg_time_spent": { "type": "number", "nullable": true } } } }, "top_products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string", "nullable": true }, "product_name": { "type": "string", "nullable": true }, "selection_count": { "type": "integer" } } } }, "revenue_by_product": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string", "nullable": true }, "product_name": { "type": "string", "nullable": true }, "deal_count": { "type": "integer" }, "revenue": { "type": "number" } } } }, "revenue_trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "revenue": { "type": "number" }, "deal_count": { "type": "integer" } } } }, "trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "impressions": { "type": "integer" }, "completions": { "type": "integer" } } } }, "time_per_step": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Map of step name to average seconds spent" }, "widget_breakdown": { "type": "array", "items": { "type": "object", "properties": { "widget_id": { "type": "string" }, "widget_title": { "type": "string", "nullable": true }, "impressions": { "type": "integer" }, "completions": { "type": "integer" }, "revenue": { "type": "number" }, "conversion_rate": { "type": "number" } } } }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "widget_id": { "type": "string" }, "title": { "type": "string" } } } }, "filters": { "type": "object", "properties": { "widget_id": { "type": "string", "nullable": true }, "days": { "type": "integer" } } } }, "required": [ "funnel", "metrics", "abandonment", "top_products", "revenue_by_product", "revenue_trend", "trend", "time_per_step", "widget_breakdown", "widgets", "filters" ] }, "success": { "type": "boolean", "const": true } }, "required": [ "error", "data", "success" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/deals": { "get": { "tags": [ "Deals" ], "summary": "List, retrieve, or bulk export deals (action=export for CSV/JSON/JSONL)", "description": "Returns a paginated list of deals, or a single deal when `id` is provided.\n\nSupported actions (with `id`):\n- `terms` \u2014 Get structured deal terms\n- `audit` \u2014 Get deal audit trail\n- `valid_transitions` \u2014 Get valid status transitions\n\nSupported actions (without `id`):\n- `compare-terms` \u2014 Compare terms between two deals (requires `deal_id_1` and `deal_id_2`)\n- `export` \u2014 Bulk export deals as CSV/JSON/JSONL (no `id` required)", "operationId": "getDeals", "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Deal ID to retrieve a specific deal (e.g. `deal_xxxxxxxxxx`). When provided, returns a single deal object instead of a list.", "required": false, "schema": { "type": "string", "pattern": "^deal_[a-zA-Z0-9]+$" } }, { "name": "status", "in": "query", "description": "Filter by deal status", "required": false, "schema": { "type": "string", "enum": [ "draft", "in_progress", "pending_signature", "awaiting_signatures", "pending_payment", "partially_accepted", "closed", "cancelled", "expired" ] } }, { "name": "action", "in": "query", "description": "Action to perform. `terms` returns structured deal terms (requires `id`). `compare-terms` compares terms between two deals (requires `deal_id_1` and `deal_id_2`). `signing_certificate` returns a structured proof document of the signing event for legal purposes. `export` \u2014 Bulk export deals as CSV, JSON, or JSONL (supports filters and include options).", "required": false, "schema": { "type": "string", "enum": [ "terms", "compare-terms", "audit", "verify_audit", "escrow", "credential", "valid_transitions", "signing_certificate", "export" ] } }, { "name": "deal_id_1", "in": "query", "description": "First deal ID for `compare-terms` action", "required": false, "schema": { "type": "string" } }, { "name": "deal_id_2", "in": "query", "description": "Second deal ID for `compare-terms` action", "required": false, "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": false, "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "description": "Filter deals created after this datetime (ISO 8601)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "Filter deals created before this datetime (ISO 8601)", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/before" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/include" }, { "$ref": "#/components/parameters/exclude" }, { "$ref": "#/components/parameters/format" }, { "name": "min_value", "in": "query", "description": "Filter deals with total value >= this amount (used with `action=export`).", "required": false, "schema": { "type": "number", "minimum": 0 } }, { "name": "max_value", "in": "query", "description": "Filter deals with total value <= this amount (used with `action=export`).", "required": false, "schema": { "type": "number", "minimum": 0 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deals": { "type": "array", "items": { "$ref": "#/components/schemas/DealListItem" } }, "pagination": { "oneOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/CursorPagination" } ] } }, "required": [ "deals", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deal": { "$ref": "#/components/schemas/Deal" } }, "required": [ "deal" ] } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Deals" ], "summary": "Create a deal or perform deal actions (including partial_accept)", "description": "Without `id`: creates a new deal. With `id` and `action`: performs an action on an existing deal. With `action=create-configured` (no `id`): creates a fully configured deal atomically.\n\n**Scope note:** All actions require `deals:write` scope **except** `action=create-configured`, which accepts `agent:execute` scope instead of `deals:write`. API keys with only `agent:execute` scope will receive 403 for any action other than `create-configured`.\n\nSupported actions:\n- `add_item` \u2014 Add a line item to the deal\n- `update_item` \u2014 Update a line item (quantity and/or unit price); requires `item_id` query param\n- `apply_discount` \u2014 Apply a discount to the deal\n- `transition` \u2014 Change the deal status (requires `status` query param)\n- `sign` \u2014 Cryptographically sign a deal in `pending_signature` status\n- `set-terms` \u2014 Set structured machine-readable deal terms (payment, delivery, SLAs, etc.)\n- `create-configured` \u2014 Create a complete deal with customer, items, configurations, and discounts in one atomic call (accepts `agent:execute` scope; `deals:write` also accepted)\n- `partial_accept` \u2014 Accept a subset of line items; rejected items are removed and totals recalculated\n- `escrow` \u2014 Create an escrow hold (Stripe PaymentIntent with manual capture) with fulfillment conditions\n- `release_escrow` \u2014 Release held escrow funds to the seller (captures the PaymentIntent)\n- `refund_escrow` \u2014 Refund held escrow funds back to the buyer\n- `fulfill_condition` \u2014 Mark an escrow condition as fulfilled\n- `revoke_credential` \u2014 Revoke the verifiable credential associated with the deal\n- `unsign` \u2014 Remove a signature from the deal, reverting it to unsigned state\n- `record-outcome` \u2014 Record a win/loss outcome with reason and optional competitor information\n- `save-as-template` \u2014 Save the deal as a reusable template", "operationId": "postDeal", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Deal ID for actions on an existing deal", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Action to perform on the deal", "required": false, "schema": { "type": "string", "enum": [ "add_item", "update_item", "apply_discount", "transition", "sign", "set-terms", "create-configured", "partial_accept", "escrow", "release_escrow", "refund_escrow", "fulfill_condition", "revoke_credential", "unsign", "record-outcome", "save-as-template" ] } }, { "name": "item_id", "in": "query", "description": "Line item ID (required for `update_item` action)", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Target status for the `transition` action", "required": false, "schema": { "type": "string", "enum": [ "in_progress", "pending_signature", "awaiting_signatures", "pending_payment", "partially_accepted", "closed", "cancelled", "expired" ] } }, { "$ref": "#/components/parameters/validateOnly" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "description": "Request body varies by action. See schema options.", "required": false, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/DealCreateRequest" }, { "$ref": "#/components/schemas/DealAddItemRequest" }, { "$ref": "#/components/schemas/DealUpdateItemRequest" }, { "$ref": "#/components/schemas/DealApplyDiscountRequest" }, { "$ref": "#/components/schemas/DealSignRequest" }, { "$ref": "#/components/schemas/DealSetTermsRequest" }, { "$ref": "#/components/schemas/DealCreateConfiguredRequest" }, { "$ref": "#/components/schemas/DealPartialAcceptRequest" }, { "$ref": "#/components/schemas/DealEscrowRequest" }, { "$ref": "#/components/schemas/DealReleaseEscrowRequest" }, { "$ref": "#/components/schemas/DealRefundEscrowRequest" }, { "$ref": "#/components/schemas/DealFulfillConditionRequest" }, { "$ref": "#/components/schemas/DealRevokeCredentialRequest" }, { "$ref": "#/components/schemas/DealUnsignRequest" }, { "$ref": "#/components/schemas/DealRecordOutcomeRequest" }, { "$ref": "#/components/schemas/DealSaveAsTemplateRequest" } ] } } } }, "responses": { "201": { "description": "Deal created or action performed. The shape of `data` depends on the `action` parameter: `escrow` returns `{ escrow: Escrow }`, `save-as-template` returns `{ template: DealTemplate }`, all other actions return `{ deal: Deal }`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "oneOf": [ { "type": "object", "properties": { "deal": { "$ref": "#/components/schemas/Deal" } }, "required": [ "deal" ], "description": "Returned for standard deal creation and most actions" }, { "type": "object", "properties": { "escrow": { "$ref": "#/components/schemas/Escrow" } }, "required": [ "escrow" ], "description": "Returned when action=escrow" }, { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/DealTemplate" } }, "required": [ "template" ], "description": "Returned when action=save-as-template" } ], "description": "Returns `{ deal }` for standard create and action requests, `{ escrow }` when action=escrow, or `{ template }` when action=save-as-template." } }, "required": [ "error", "success", "data" ] } } } }, "200": { "description": "Action performed on existing deal, or validation passed (validate_only=true)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Deal" }, { "$ref": "#/components/schemas/ValidationResult" } ], "description": "Returns a Deal for action requests, or ValidationResult when validate_only=true." } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Deals" ], "summary": "Update a deal", "description": "Update fields on an existing deal. Requires `If-Match` header with the current ETag for optimistic locking. Returns 412 if the resource was modified since the ETag was obtained.", "operationId": "patchDeal", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Deal ID to update", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ifMatch" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealUpdateRequest" } } } }, "responses": { "200": { "description": "Deal updated", "headers": { "ETag": { "description": "New resource version after update", "schema": { "type": "string", "example": "W/\"2\"" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/Deal", "description": "The updated deal object." } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "description": "Unprocessable Entity \u2014 status changes must use the transition action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Deals" ], "summary": "Cancel a deal or remove a line item", "description": "Without `action`: cancels the deal (requires `If-Match` header). With `action=remove_item` and `item_id`: removes a specific line item.", "operationId": "deleteDeal", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Deal ID", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Action to perform. Use `remove_item` to remove a line item instead of cancelling.", "required": false, "schema": { "type": "string", "enum": [ "remove_item" ] } }, { "name": "item_id", "in": "query", "description": "Line item ID to remove (required when action=remove_item)", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ifMatch" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "responses": { "200": { "description": "Deal cancelled or item removed. When an already-cancelled deal is permanently deleted, returns `deal_id`. When cancelling or removing an item, returns the updated deal object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealDeleteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/deals/verify": { "get": { "tags": [ "Deals" ], "summary": "Verify deal or contract integrity", "description": "Public endpoint (no authentication required). Verifies that a deal or contract has not been tampered with after signing by comparing the current state hash against the signed state hash.", "operationId": "verifyDeal", "security": [], "parameters": [ { "name": "id", "in": "query", "description": "Deal ID to verify", "required": false, "schema": { "type": "string" } }, { "name": "contract_id", "in": "query", "description": "Contract ID to verify", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "verification": { "type": "object", "properties": { "deal_id": { "type": "string" }, "status": { "type": "string", "enum": [ "verified", "tampered", "unsigned" ], "description": "verified = deal matches signed state, tampered = deal modified after signing, unsigned = no signature exists" }, "message": { "type": "string" }, "deal_hash": { "type": "object", "properties": { "stored": { "type": "string", "nullable": true }, "current": { "type": "string" }, "matches": { "type": "boolean" } } }, "signature": { "type": "object", "nullable": true, "properties": { "signature_id": { "type": "string" }, "signer_type": { "type": "string" }, "signer_id": { "type": "string" }, "signature_method": { "type": "string" }, "signed_at": { "type": "string", "format": "date-time" }, "ip_address": { "type": "string" }, "valid": { "type": "boolean" } } }, "verified_at": { "type": "string", "format": "date-time" } } } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "List or retrieve customers", "description": "Returns a paginated list of customers, or a single customer when `id` is provided.", "operationId": "getCustomers", "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Customer ID to retrieve a specific customer (e.g. `cust_xxxxxxxxxx`). When provided, returns a single customer object.", "required": false, "schema": { "type": "string", "pattern": "^cust_[a-zA-Z0-9]+$" } }, { "name": "status", "in": "query", "description": "Filter by customer status", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "archived" ] } }, { "name": "search", "in": "query", "description": "Search by name, email, phone, or company", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/before" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/include" }, { "$ref": "#/components/parameters/exclude" }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerListItem" } }, "pagination": { "oneOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/CursorPagination" } ] } }, "required": [ "customers", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } }, "required": [ "customer" ] } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Customers" ], "summary": "Create a customer", "description": "Create a new customer record. Name and email are required.", "operationId": "createCustomer", "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/validateOnly" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateRequest" } } } }, "responses": { "200": { "description": "Success with no side-effects. Either request validation passed (validate_only=true) or an existing customer was returned via find-or-create (publishable-key requests only).", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidationResponse" }, { "type": "object", "description": "Existing customer returned by find-or-create (publishable-key requests). The existing field distinguishes this from a 201 created response.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerListItem" }, "existing": { "type": "boolean", "const": true, "description": "Always true when the customer already existed and was returned rather than created." } }, "required": [ "customer", "existing" ] } }, "required": [ "error", "success", "data" ] } ] } } } }, "201": { "description": "Customer created", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerListItem" } }, "required": [ "customer" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Customers" ], "summary": "Update a customer", "description": "Update fields on an existing customer. Requires `If-Match` header with the current ETag for optimistic locking.", "operationId": "updateCustomer", "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Customer ID to update", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ifMatch" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" } } } }, "responses": { "200": { "description": "Customer updated", "headers": { "ETag": { "description": "New resource version after update", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerListItem" } }, "required": [ "customer" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Customers" ], "summary": "Delete a customer", "description": "Permanently delete a customer record. Optionally accepts `If-Match` header with the current ETag for optimistic locking.", "operationId": "deleteCustomer", "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Customer ID to delete", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ifMatch" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "responses": { "200": { "description": "Customer deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/products": { "get": { "tags": [ "Products" ], "summary": "List or retrieve products", "description": "Returns a paginated list of products, or a single product when `id` is provided.", "operationId": "getProducts", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Product ID to retrieve a specific product (e.g. `prod_xxxxxxxxxx`). When provided, returns a single product object.", "required": false, "schema": { "type": "string", "pattern": "^prod_[a-zA-Z0-9]+$" } }, { "name": "status", "in": "query", "description": "Filter by product status", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "archived" ] } }, { "name": "type", "in": "query", "description": "Filter by product type", "required": false, "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by product category", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Search by name, SKU, or description", "required": false, "schema": { "type": "string" } }, { "name": "requires_booking", "in": "query", "description": "Filter to only return bookable service products (requires_booking=1)", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ] } }, { "name": "family", "in": "query", "description": "Filter products by family ID", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Sub-action. Use `options` together with an `id` parameter to return the product's configuration options schema.", "required": false, "schema": { "type": "string", "enum": [ "options" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/before" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/include" }, { "$ref": "#/components/parameters/exclude" }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductListItem" } }, "pagination": { "oneOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/CursorPagination" } ] } }, "required": [ "products", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" } }, "required": [ "product" ] } }, "required": [ "error", "success", "data" ] }, { "title": "Product options (action=options)", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "product_id": { "type": "string", "description": "The product ID whose options are returned" }, "option_groups": { "type": "array", "description": "Configuration option groups for this product", "items": { "$ref": "#/components/schemas/OptionGroup" } } }, "required": [ "product_id", "option_groups" ] } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Products" ], "summary": "Create a product", "description": "Create a new product. Name and price are required.", "operationId": "createProduct", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/validateOnly" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreateRequest" } } } }, "responses": { "200": { "description": "Validation passed (validate_only=true). Request body is valid but no product was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" } } } }, "201": { "description": "Product created", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductBase" } }, "required": [ "product" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Products" ], "summary": "Update a product", "description": "Update fields on an existing product. Requires `If-Match` header with the current ETag for optimistic locking.", "operationId": "updateProduct", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Product ID to update", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ifMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductUpdateRequest" } } } }, "responses": { "200": { "description": "Product updated", "headers": { "ETag": { "description": "New resource version after update", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/ProductBase" } }, "required": [ "product" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Products" ], "summary": "Delete a product", "description": "Permanently delete a product record. Optionally accepts `If-Match` header with the current ETag for optimistic locking.", "operationId": "deleteProduct", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Product ID to delete", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/ifMatch" } ], "responses": { "200": { "description": "Product deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contracts": { "get": { "tags": [ "Contracts" ], "summary": "List or retrieve contracts", "description": "Returns a paginated list of contracts, or a single contract when `id` is provided.", "operationId": "getContracts", "security": [ { "bearerAuth": [ "contracts:read" ] }, { "apiKeyHeader": [ "contracts:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Contract ID to retrieve a specific contract. When provided, returns a single contract object.", "required": false, "schema": { "type": "integer" } }, { "name": "action", "in": "query", "description": "Action to perform on a specific contract (requires `id`). `audit` returns the audit trail. `verify_audit` verifies hash chain integrity. `signing_certificate` returns a structured proof document of the signing event for legal purposes.", "required": false, "schema": { "type": "string", "enum": [ "audit", "verify_audit", "signing_certificate" ] } }, { "name": "status", "in": "query", "description": "Filter by contract status", "required": false, "schema": { "type": "string", "enum": [ "draft", "signed", "pending", "active", "terminated", "expired" ] } }, { "name": "customer_id", "in": "query", "description": "Filter by customer ID", "required": false, "schema": { "type": "string" } }, { "name": "renewal_type", "in": "query", "description": "Filter by renewal type", "required": false, "schema": { "type": "string", "enum": [ "manual", "auto", "none" ] } }, { "name": "expiring_soon", "in": "query", "description": "Filter contracts expiring within N days", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/before" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/fields" }, { "$ref": "#/components/parameters/include" }, { "$ref": "#/components/parameters/exclude" }, { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "contracts": { "type": "array", "items": { "$ref": "#/components/schemas/ContractListItem" } }, "pagination": { "oneOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/CursorPagination" } ] } }, "required": [ "contracts", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "contract": { "$ref": "#/components/schemas/Contract" } }, "required": [ "contract" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Response when action=audit. Returns the paginated audit trail for a specific contract.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "entries": { "type": "array", "description": "Audit trail entries in chronological order", "items": { "type": "object", "properties": { "log_id": { "type": "integer", "description": "Unique audit log entry ID" }, "entity_type": { "type": "string", "description": "Type of entity audited" }, "entity_id": { "type": "string", "description": "ID of the audited entity" }, "action": { "type": "string", "description": "Action that was performed" }, "actor_type": { "type": "string", "description": "Type of actor who performed the action (user, customer, agent, system)" }, "actor_id": { "type": "string", "description": "ID of the actor who performed the action" }, "changes": { "type": [ "object", "null" ], "description": "Field-level changes recorded for this entry" }, "snapshot": { "type": [ "object", "null" ], "description": "Full entity snapshot at time of action" }, "previous_hash": { "type": [ "string", "null" ], "description": "SHA-256 hash of the previous entry in the chain" }, "entry_hash": { "type": "string", "description": "SHA-256 hash of this entry (for chain integrity verification)" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when this audit entry was created" } }, "required": [ "log_id", "entity_type", "entity_id", "action", "created_at" ] } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of audit entries for this contract" }, "limit": { "type": "integer", "description": "Maximum entries returned per page" }, "offset": { "type": "integer", "description": "Number of entries skipped" }, "count": { "type": "integer", "description": "Number of entries returned in this response" } }, "required": [ "total", "limit", "offset", "count" ] } }, "required": [ "entries", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Response when action=verify_audit. Returns the hash chain integrity verification result for a contract's audit trail.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "entity_type": { "type": "string", "description": "Entity type that was verified", "example": "contract" }, "entity_id": { "type": "string", "description": "ID of the entity whose audit trail was verified" }, "status": { "type": "string", "enum": [ "verified", "tampered", "no_entries" ], "description": "Result of the hash chain integrity check. `verified` means all entries are intact. `tampered` means the chain has been broken or modified. `no_entries` means no audit entries exist." }, "message": { "type": "string", "description": "Human-readable description of the verification result" }, "total_entries": { "type": "integer", "description": "Total number of audit entries checked" }, "verified_at": { "type": "string", "format": "date-time", "description": "Timestamp when the verification was performed" }, "first_entry": { "type": "integer", "description": "Log ID of the first entry in the chain (present when status=verified)" }, "last_entry": { "type": "integer", "description": "Log ID of the last entry in the chain (present when status=verified)" }, "broken_at": { "type": "object", "description": "Details of where the chain was broken (present when status=tampered)", "properties": { "entry_index": { "type": "integer", "description": "Zero-based index of the entry where tampering was detected" }, "log_id": { "type": "integer", "description": "Log ID of the tampered entry" }, "reason": { "type": "string", "description": "Why the entry failed verification (e.g. 'previous_hash mismatch' or 'entry_hash mismatch')" } }, "required": [ "entry_index", "log_id", "reason" ] } }, "required": [ "entity_type", "entity_id", "status", "message", "total_entries", "verified_at" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Response when action=signing_certificate. Returns a structured legal compliance proof document for the contract signing event, referencing the Electronic Transactions Act 1999 (Cth).", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "certificate_version": { "type": "string", "description": "Version of the certificate format", "example": "1.0" }, "generated_at": { "type": "string", "format": "date-time", "description": "Timestamp when this certificate was generated" }, "legislation": { "type": "string", "description": "Applicable legislation under which the electronic signing is valid", "example": "Electronic Transactions Act 1999 (Cth) and state/territory equivalents" }, "contract": { "type": "object", "description": "Key metadata of the signed contract", "properties": { "contract_id": { "type": "string", "description": "Contract ID" }, "contract_number": { "type": [ "string", "null" ], "description": "Human-readable contract number" }, "title": { "type": [ "string", "null" ], "description": "Contract title" }, "status": { "type": "string", "description": "Contract status at time of certificate generation" }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency code" }, "value": { "type": [ "number", "null" ], "description": "Contract value" }, "start_date": { "type": [ "string", "null" ], "format": "date", "description": "Contract start date" }, "end_date": { "type": [ "string", "null" ], "format": "date", "description": "Contract end date" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the contract was created" } }, "required": [ "contract_id", "status" ] }, "signers": { "type": "array", "description": "List of parties who signed the contract", "items": { "type": "object", "properties": { "signer_type": { "type": [ "string", "null" ], "description": "Type of signer (user, customer, agent)" }, "signer_id": { "type": [ "string", "null" ], "description": "ID of the signer" }, "signature_method": { "type": [ "string", "null" ], "description": "Method used to sign (e.g. 'checkbox', 'typed_name', 'ed25519')" }, "signature_algorithm": { "type": [ "string", "null" ], "description": "Cryptographic algorithm used for the signature" }, "signature_hash": { "type": "string", "description": "Hash of the signature" }, "contract_hash": { "type": [ "string", "null" ], "description": "Hash of the contract content at time of signing" }, "signed_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the contract was signed" }, "is_agent_signer": { "type": "boolean", "description": "Whether the signer is an AI agent (true) or a human (false)" } }, "required": [ "signature_hash", "is_agent_signer" ] } }, "consent_events": { "type": "array", "description": "Audit log entries recording explicit consent to sign, providing evidence of informed consent", "items": { "type": "object", "properties": { "actor_type": { "type": [ "string", "null" ], "description": "Type of actor who granted consent" }, "actor_id": { "type": [ "string", "null" ], "description": "ID of the actor who granted consent" }, "consented_at": { "type": "string", "format": "date-time", "description": "Timestamp when consent was granted" }, "details": { "type": [ "object", "null" ], "description": "Additional details about the consent event" } }, "required": [ "consented_at" ] } }, "hash_chain_verification": { "type": "object", "description": "Summary of the audit trail hash chain integrity check performed at certificate generation time", "properties": { "status": { "type": "string", "enum": [ "verified", "tampered", "no_entries" ], "description": "Result of the hash chain integrity check" }, "total_entries": { "type": "integer", "description": "Total number of audit entries verified" }, "verified_at": { "type": "string", "format": "date-time", "description": "Timestamp when the verification was performed" } }, "required": [ "status", "total_entries", "verified_at" ] }, "note": { "type": "string", "description": "Disclaimer note about the certificate's legal standing" } }, "required": [ "certificate_version", "generated_at", "legislation", "contract", "signers", "consent_events", "hash_chain_verification", "note" ] } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Contracts" ], "summary": "Create a contract or perform contract actions", "description": "Without `id`: creates a new contract. With `id` and `action`: performs a lifecycle action.\n\nSupported actions:\n- `sign` \u2014 Sign a draft contract\n- `activate` \u2014 Activate a signed/pending contract\n- `terminate` \u2014 Terminate an active contract\n- `renew` \u2014 Manually trigger contract renewal (bypasses renewal_type check)\n- `opt_out_renewal` \u2014 Decline the upcoming auto-renewal\n\nUse `validate_only=true` when creating a contract to validate the request body without persisting it.", "operationId": "postContract", "security": [ { "bearerAuth": [ "contracts:write" ] }, { "apiKeyHeader": [ "contracts:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Contract ID for actions on an existing contract", "required": false, "schema": { "type": "integer" } }, { "name": "action", "in": "query", "description": "Lifecycle action to perform", "required": false, "schema": { "type": "string", "enum": [ "sign", "activate", "terminate", "renew", "opt_out_renewal" ] } }, { "$ref": "#/components/parameters/validateOnly" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "description": "Required when creating a contract. Not needed for lifecycle actions.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractCreateRequest" } } } }, "responses": { "201": { "description": "Contract created", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "contract": { "$ref": "#/components/schemas/ContractListItem" } }, "required": [ "contract" ] } }, "required": [ "error", "success", "data" ] } } } }, "200": { "description": "Lifecycle action performed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Contracts" ], "summary": "Update a contract", "description": "Update fields on an existing contract. Requires `If-Match` header with the current ETag for optimistic locking.", "operationId": "updateContract", "security": [ { "bearerAuth": [ "contracts:write" ] }, { "apiKeyHeader": [ "contracts:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Contract ID to update", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/ifMatch" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractUpdateRequest" } } } }, "responses": { "200": { "description": "Contract updated", "headers": { "ETag": { "description": "New resource version after update", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "contract": { "$ref": "#/components/schemas/ContractListItem" } }, "required": [ "contract" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Contracts" ], "summary": "Delete a contract", "description": "Delete a contract. Active contracts must be terminated first. Optionally accepts `If-Match` header with the current ETag for optimistic locking.", "operationId": "deleteContract", "security": [ { "bearerAuth": [ "contracts:write" ] }, { "apiKeyHeader": [ "contracts:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Contract ID to delete", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/ifMatch" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "responses": { "200": { "description": "Contract deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContractDeleteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/keys": { "get": { "tags": [ "API Keys" ], "summary": "List API keys", "description": "Returns a list of API keys for the authenticated user, or a single key when `id` is provided. Session authentication required \u2014 API keys cannot be used to manage API keys.\n\nWith `id` and `action=stats`: returns usage statistics for the key.\n\nNote: API responses include `X-Key-Rotation-Recommended: true` when the authenticating key has not been rotated in 90+ days.", "operationId": "getKeys", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Key ID to retrieve a specific key or its stats", "required": false, "schema": { "type": "string", "pattern": "^key_[a-zA-Z0-9]+$" } }, { "name": "action", "in": "query", "description": "Use `stats` to get usage statistics for a key", "required": false, "schema": { "type": "string", "enum": [ "stats" ] } }, { "name": "days", "in": "query", "description": "Number of days to include in stats (default: 7)", "required": false, "schema": { "type": "integer", "default": 7, "minimum": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "List of API keys", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "count": { "type": "integer" }, "available_scopes": { "type": "array", "items": { "type": "string" }, "description": "All valid scopes that can be assigned to API keys" } }, "required": [ "keys", "count" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Key usage statistics", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/ApiKeyStats" } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Single API key (returned when id is provided without action=stats)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "API Keys" ], "summary": "Create or rotate an API key", "description": "Without `action`: creates a new API key. With `action=rotate` and `id`: rotates an existing key \u2014 generates a new key value while preserving all settings. The full key value is only returned once \u2014 store it securely. Session authentication required.", "operationId": "createKey", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "description": "Use `rotate` with `id` to rotate an existing key instead of creating a new one", "required": false, "schema": { "type": "string", "enum": [ "rotate" ] } }, { "name": "id", "in": "query", "description": "Key ID to rotate (required when action=rotate)", "required": false, "schema": { "type": "string", "pattern": "^key_[a-zA-Z0-9]+$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } } }, "responses": { "201": { "description": "API key created or rotated. The `api_key` field contains the full key \u2014 store it securely, it will not be shown again.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/ApiKeyCreated" } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "API Keys" ], "summary": "Revoke an API key", "description": "Without `action`: revokes the key (soft delete). With `action=delete`: permanently deletes the key. Session authentication required.", "operationId": "deleteKey", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Key ID to revoke or delete", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Use `delete` for permanent deletion instead of revocation", "required": false, "schema": { "type": "string", "enum": [ "delete" ] } } ], "responses": { "200": { "description": "Key revoked or deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "API Keys" ], "summary": "Update API key settings", "description": "Update properties of an existing API key such as name, description, scopes, rate limit, or allowed origins. Session authentication required.", "operationId": "patchKey", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Key ID to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the API key" }, "description": { "type": "string", "nullable": true, "description": "Optional description of the key's purpose" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "*", "*:read", "deals:read", "deals:write", "deals:sign", "customers:read", "customers:write", "products:read", "products:write", "contracts:read", "contracts:write", "webhooks:read", "webhooks:write", "audit:export", "agent:*", "agent:discover", "agent:negotiate", "agent:execute", "intelligence:read", "intelligence:write", "billing:read", "billing:write", "trust:read", "trust:write", "staff:read", "staff:write", "team:read", "team:write", "bookings:read", "bookings:write", "queue:read", "queue:write", "sites:read", "sites:write", "delegations:read", "delegations:write", "admin" ] }, "description": "Permission scopes for the key" }, "rate_limit": { "type": "integer", "description": "Rate limit (requests per minute)" }, "allowed_origins": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Allowed CORS origins. Set to null or empty array to clear restrictions." } } } } } }, "responses": { "200": { "description": "API key updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/deal-discovery": { "get": { "tags": [ "Discovery" ], "summary": "Discover available deals", "description": "Returns a paginated list of discoverable deals. Filter by category, price range, currency, pricing model, or payment terms. Requires `agent:discover` scope.", "operationId": "discoverDeals", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter by deal category" }, { "name": "min_price", "in": "query", "schema": { "type": "number" }, "description": "Minimum deal total" }, { "name": "max_price", "in": "query", "schema": { "type": "number" }, "description": "Maximum deal total" }, { "name": "currency", "in": "query", "schema": { "type": "string" }, "description": "Filter by currency code" }, { "name": "pricing_model", "in": "query", "schema": { "type": "string", "enum": [ "fixed", "per_unit", "tiered", "usage_based", "subscription" ] }, "description": "Filter by pricing model" }, { "name": "payment_terms", "in": "query", "schema": { "type": "string", "enum": [ "due_on_receipt", "net_15", "net_30", "net_60", "net_90", "custom" ] }, "description": "Filter by payment terms" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "schema" ] }, "description": "Set to 'schema' to retrieve the deal terms JSON schema" } ], "responses": { "200": { "description": "Discoverable deals or terms schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [ "agent:discover" ] }, { "apiKeyHeader": [ "agent:discover" ] }, { "sessionAuth": [] } ] } }, "/deal-negotiations": { "get": { "tags": [ "Negotiations" ], "summary": "Get negotiation history for a deal", "description": "Returns the full round-by-round negotiation history for a deal, including term changes between rounds. Set action=intelligence for pricing intelligence. Requires `agent:negotiate` scope.", "operationId": "getNegotiationHistory", "parameters": [ { "name": "deal_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Deal ID to get negotiations for" }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "intelligence" ] }, "description": "Set to 'intelligence' for pricing suggestions" } ], "responses": { "200": { "description": "Negotiation history or pricing intelligence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "agent:negotiate" ] }, { "apiKeyHeader": [ "agent:negotiate" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Negotiations" ], "summary": "Propose, counter, accept, reject, or get AI suggestions for deal terms", "description": "Perform a negotiation action on a deal. Use action=propose for initial proposal, action=counter for counter-proposal, action=accept to accept, action=reject to reject, action=suggest to get AI counter-proposal suggestions. propose/counter/reject/suggest require `agent:negotiate` scope; accept requires `agent:execute` scope.", "operationId": "negotiateDeal", "parameters": [ { "name": "deal_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Deal ID to negotiate" }, { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "propose", "counter", "accept", "reject", "suggest" ] }, "description": "Negotiation action. Use 'suggest' to get AI counter-proposal suggestions." } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "proposed_terms": { "type": "object", "description": "Structured deal terms (required for propose/counter)" }, "message": { "type": "string", "description": "Optional message to accompany the proposal" }, "expires_at": { "type": "string", "format": "date-time", "description": "When this proposal expires" }, "reason": { "type": "string", "description": "Reason for rejection (reject action only)" }, "current_terms": { "type": "object", "description": "Current terms on the table (suggest action). If omitted, uses latest round's terms." } } } } } }, "responses": { "200": { "description": "Negotiation action completed (accept/reject)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "201": { "description": "Proposal or counter-proposal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "security": [ { "bearerAuth": [ "agent:negotiate" ] }, { "bearerAuth": [ "agent:execute" ] }, { "apiKeyHeader": [ "agent:negotiate" ] }, { "apiKeyHeader": [ "agent:execute" ] }, { "sessionAuth": [] } ] } }, "/deal-templates": { "get": { "tags": [ "Templates" ], "summary": "List or retrieve deal templates, versions, or diffs", "description": "Returns a paginated list of deal templates, a single template when `id` is provided, version history (action=versions), a specific version (action=version), or a diff between two versions (action=diff). Requires `deals:read` scope.", "operationId": "getDealTemplates", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Template ID for single retrieval or version operations" }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "versions", "version", "diff" ] }, "description": "Version action: versions (list history), version (get specific), diff (compare two)" }, { "name": "version", "in": "query", "schema": { "type": "integer" }, "description": "Version number (for action=version)" }, { "name": "from", "in": "query", "schema": { "type": "integer" }, "description": "From version number (for action=diff)" }, { "name": "to", "in": "query", "schema": { "type": "integer" }, "description": "To version number (for action=diff)" }, { "name": "is_active", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "1" }, "description": "Filter by active status (defaults to '1')" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by name or description" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Template(s), version history, version data, or diff retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealTemplateListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Templates" ], "summary": "Create a template, deal from template, or rollback", "description": "Create a new deal template, instantiate an existing template into a live deal (action=create-deal), or rollback to a previous version (action=rollback). Requires `deals:write` scope.", "operationId": "createDealTemplate", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Template ID (for instantiation or rollback)" }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "create", "create-deal", "create-from-deal", "clone", "rollback" ] }, "description": "Action to perform" }, { "name": "version", "in": "query", "schema": { "type": "integer" }, "description": "Version number to rollback to (for action=rollback)" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "template_data" ], "properties": { "name": { "type": "string", "maxLength": 255, "description": "Template name (required for create)" }, "description": { "type": "string" }, "template_data": { "type": "object", "description": "Template content: line_items, discounts, terms, currency, etc. (required for create)" }, "is_active": { "type": "boolean", "description": "Whether the template is active (default: true)" }, "category": { "type": "string" }, "default_terms": { "type": "object", "description": "Default structured deal terms" }, "line_items": { "type": "array", "description": "Default line items" }, "metadata": { "type": "object" }, "customer_id": { "type": "string", "description": "Customer ID (for instantiation)" }, "overrides": { "type": "object", "description": "Term/metadata overrides (for instantiation)" } } } } } }, "responses": { "201": { "description": "Template created or deal instantiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ] }, "patch": { "tags": [ "Templates" ], "summary": "Update a deal template", "description": "Update an existing deal template. Requires `templates:write` scope.", "operationId": "updateDealTemplate", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Template ID" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "template_data": { "type": "object", "description": "Template content: line_items, discounts, terms, currency, etc." }, "is_active": { "type": "boolean", "description": "Whether the template is active" }, "change_summary": { "type": "string", "maxLength": 500, "description": "Optional description of what changed (stored in version history)" } } } } } }, "responses": { "200": { "description": "Template updated (new version created)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ] }, "delete": { "tags": [ "Templates" ], "summary": "Soft-delete a deal template", "description": "Permanently delete a deal template. Requires `templates:write` scope.", "operationId": "deleteDealTemplate", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Template ID" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "responses": { "200": { "description": "Template deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ] } }, "/deal-participants": { "get": { "tags": [ "Deals" ], "summary": "List participants or settlements for a deal", "description": "Returns all participants for a deal (with `deal_id`), or settlement records when `action=settlements`.", "operationId": "getDealParticipants", "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "deal_id", "in": "query", "description": "Deal ID to list participants for", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Set to `settlements` to retrieve settlement records instead of participants", "required": false, "schema": { "type": "string", "enum": [ "settlements" ] } } ], "responses": { "200": { "description": "List of participants or settlements", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Participants list (default)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "participants": { "type": "array", "items": { "$ref": "#/components/schemas/DealParticipant" } } }, "required": [ "participants" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Settlements list (action=settlements)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "settlements": { "type": "array", "items": { "type": "object", "properties": { "settlement_id": { "type": "string" }, "participant_id": { "type": "integer" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "settled_at": { "type": "string", "format": "date-time", "nullable": true } } } } }, "required": [ "settlements" ] } }, "required": [ "error", "success", "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Deals" ], "summary": "Invite agent, or perform accept/complete actions", "description": "Invite an agent to a deal (with `deal_id`), or perform participant actions with `action=accept|complete` (with `id`).", "operationId": "postDealParticipant", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "deal_id", "in": "query", "description": "Deal ID to invite participant to (required for invite)", "required": false, "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Participant ID (required for accept/complete actions)", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Action: `accept` or `complete`", "required": false, "schema": { "type": "string", "enum": [ "accept", "complete" ] } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_api_key_id": { "type": "integer", "description": "Internal API key ID of the agent to invite" }, "role": { "type": "string", "enum": [ "primary", "subcontractor", "reviewer", "observer", "required_signer" ] }, "scope_description": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "revenue_share_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "revenue_share_fixed": { "type": "number", "minimum": 0 }, "delegation_id": { "type": "string" } }, "required": [ "agent_api_key_id", "role" ] } } } }, "responses": { "201": { "description": "Participant invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealParticipantResponse" } } } }, "200": { "description": "Action performed (accept or complete)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealParticipantResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "tags": [ "Deals" ], "summary": "Update participant role, scope, or revenue share", "operationId": "patchDealParticipant", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Participant ID to update", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "primary", "subcontractor", "reviewer", "observer", "required_signer" ] }, "scope_description": { "type": "string" }, "line_item_ids": { "type": "array", "items": { "type": "string" } }, "revenue_share_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "revenue_share_fixed": { "type": "number", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Participant updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealParticipantResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "description": "Updates a deal participant record. Modify the participant's role, notification preferences, or access permissions on the deal." }, "delete": { "tags": [ "Deals" ], "summary": "Remove (withdraw) a participant from a deal", "operationId": "deleteDealParticipant", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Participant ID to remove", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "responses": { "200": { "description": "Participant withdrawn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealParticipantResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "description": "Removes a participant from a deal by participant ID. The participant will no longer receive deal notifications or have access to the deal." } }, "/delegations": { "get": { "tags": [ "Delegations" ], "summary": "List or retrieve delegations; use action=check to validate the calling agent's active delegation; use action=spending&id={id} for spending totals; use action=analytics&id={id} for per-delegation analytics; use action=activity&id={id} for paginated/filtered audit trail", "description": "Returns a paginated list of active delegations for the current user, or a single delegation when `id` is provided.", "operationId": "getDelegations", "parameters": [ { "name": "id", "in": "query", "description": "Specific delegation ID to retrieve", "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Action to perform. Use `check` (no `id` required) to validate the calling agent's own active delegation and retrieve its allowed_actions. Use `spending` with an `id` to retrieve spending totals and limit utilisation for a delegation. Use `verify` with an `id` to check delegation validity. Use `analytics` with an `id` to retrieve per-delegation analytics (spending breakdown, deals created, activity log, ROI metrics, and 30-day spending chart). Use `activity` with an `id` to retrieve a paginated, filterable audit trail of all actions taken under this delegation (supports `from_date`, `to_date`, `action_type`, `entity_type` query parameters).", "schema": { "type": "string", "enum": [ "check", "spending", "verify", "analytics", "summary", "pending", "proposal", "activity" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "from_date", "in": "query", "description": "ISO 8601 start date for filtering activity results (used with action=activity)", "schema": { "type": "string", "format": "date-time" } }, { "name": "to_date", "in": "query", "description": "ISO 8601 end date for filtering activity results (used with action=activity)", "schema": { "type": "string", "format": "date-time" } }, { "name": "action_type", "in": "query", "description": "Filter activity by action type (e.g. deal_created, deal_signed). Used with action=activity.", "schema": { "type": "string" } }, { "name": "entity_type", "in": "query", "description": "Filter activity by entity type (e.g. deal, contract). Used with action=activity.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delegation(s) retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Delegation" }, { "type": "object", "properties": { "delegations": { "type": "array", "items": { "$ref": "#/components/schemas/Delegation" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } ] } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden \u2014 API key authentication required for action=check (session auth insufficient)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "delegations:read" ] }, { "apiKeyHeader": [ "delegations:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Delegations" ], "summary": "Create a new delegation", "description": "Create a new delegation or perform a proposal action. Use action=propose to propose agent-to-agent delegation, action=accept/reject/counter to respond to pending proposals.", "operationId": "createDelegation", "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "propose", "accept", "reject", "counter" ] }, "description": "Proposal action to perform (agent-to-agent delegation protocol)" }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Proposal ID for accept/reject/counter actions" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDelegationRequest" }, "example": { "grantee_agent_key_id": "key_abc123", "allowed_actions": [ "deals:read", "deals:write", "agent:negotiate" ], "max_transaction_amount": 5000, "max_daily_amount": 10000, "max_monthly_amount": 50000, "expires_at": "2026-04-01T00:00:00Z" } } } }, "responses": { "201": { "description": "Delegation created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/Delegation" } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden \u2014 API key authentication required for action=propose (session auth insufficient)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "security": [ { "bearerAuth": [ "delegations:write" ] }, { "apiKeyHeader": [ "delegations:write" ] }, { "sessionAuth": [] } ] }, "put": { "tags": [ "Delegations" ], "summary": "Update a delegation", "description": "Updates an existing delegation's allowed actions, spending limits, or expiry.", "operationId": "updateDelegation", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Delegation ID to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed_actions": { "type": "array", "items": { "type": "string" }, "description": "Updated list of allowed action scopes" }, "max_transaction_amount": { "type": "number", "nullable": true, "description": "Updated per-transaction spending limit" }, "max_daily_amount": { "type": "number", "nullable": true, "description": "Updated daily spending limit" }, "max_monthly_amount": { "type": "number", "nullable": true, "description": "Updated monthly spending limit" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Updated expiry datetime" }, "description": { "type": "string", "maxLength": 500, "nullable": true, "description": "Updated human-readable description" }, "approval_threshold": { "type": "number", "minimum": 0, "maximum": 99999999.99, "nullable": true, "description": "Updated transaction amount above which human approval is required" }, "approval_steps": { "type": "object", "nullable": true, "description": "Updated approval workflow definition. Maximum nesting depth of 3." }, "approval_timeout": { "type": "integer", "minimum": 0, "maximum": 86400, "nullable": true, "description": "Updated approval timeout in seconds (0\u201386400)" }, "auto_approve_policy": { "type": "object", "nullable": true, "description": "Updated auto-approve policy rules. Maximum nesting depth of 3." }, "alert_threshold_pct": { "type": "integer", "minimum": 1, "maximum": 100, "nullable": true, "description": "Updated budget alert threshold percentage (1\u2013100)" } } } } } }, "responses": { "200": { "description": "Delegation updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/Delegation" } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "delegations:write" ] }, { "apiKeyHeader": [ "delegations:write" ] }, { "sessionAuth": [] } ] }, "delete": { "tags": [ "Delegations" ], "summary": "Revoke a delegation", "description": "Revokes a delegation and cascades revocation to all sub-delegations in the chain.", "operationId": "revokeDelegation", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Delegation ID to revoke", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delegation revoked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "delegation_id": { "type": "string" }, "revoked": { "type": "boolean", "const": true } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "security": [ { "bearerAuth": [ "delegations:write" ] }, { "apiKeyHeader": [ "delegations:write" ] }, { "sessionAuth": [] } ] } }, "/sandbox/reset": { "post": { "tags": [ "Sandbox" ], "summary": "Reset sandbox environment", "description": "Delete all test-environment data for the authenticated tenant. Only available with test API keys (sb_test_*).", "operationId": "sandboxReset", "responses": { "200": { "description": "Test data cleared", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "environment": { "type": "string", "const": "test" }, "sandbox": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "action": { "type": "string", "const": "reset" }, "deleted": { "type": "object" }, "total_deleted": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error", "success", "data" ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [ "sandbox:write" ] }, { "apiKeyHeader": [ "sandbox:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body required. Resets all test-environment data for the authenticated tenant.", "properties": {} } } } } } }, "/sandbox/seed": { "post": { "tags": [ "Sandbox" ], "summary": "Seed test data", "description": "Populate the test environment with representative data: 5 customers, 10 products, deals in various statuses, and a sample contract.", "operationId": "sandboxSeed", "responses": { "201": { "description": "Test data created", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "environment": { "type": "string", "const": "test" }, "sandbox": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "action": { "type": "string", "const": "seed" }, "seeded": { "type": "object" }, "total_seeded": { "type": "integer" }, "message": { "type": "string" } } } }, "required": [ "error", "success", "data" ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [ "sandbox:write" ] }, { "apiKeyHeader": [ "sandbox:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body required. Seeds representative test data (customers, products, deals, contracts) for the authenticated tenant.", "properties": {} } } } } } }, "/sandbox/simulate_webhook": { "post": { "tags": [ "Sandbox" ], "summary": "Simulate a webhook event", "description": "Trigger webhook delivery with a synthetic event payload to all matching registered endpoints.", "operationId": "sandboxSimulateWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event_type" ], "properties": { "event_type": { "type": "string", "description": "Event type to simulate", "enum": [ "deal.created", "deal.updated", "deal.status_changed", "deal.closed", "deal.fulfilled", "deal.expired", "deal.unsigned", "deal.signature_added", "deal.signature_timeout", "deal.item_added", "deal.item_removed", "deal.item_updated", "deal.discount_applied", "deal.partially_accepted", "deal.created_configured", "deal.negotiation_proposed", "deal.negotiation_counter_proposed", "deal.negotiation_accepted", "deal.negotiation_rejected", "deal.payment_received", "deal.payment_failed", "deal.payment_refunded", "deal.payment_overdue", "deal.settlement_created", "deal.settlement_initiated", "deal.settlement_completed", "deal.settlement_failed", "deal.settlement_all_completed", "deal.participant_invited", "deal.participant_accepted", "deal.participant_withdrawn", "deal.participant_completed", "negotiation.expired", "negotiation.proposed", "negotiation.countered", "negotiation.accepted", "negotiation.rejected", "negotiation.suggestion_generated", "contract.signed", "contract.activated", "contract.terminated", "contract.tamper_detected", "contract.auto_renewed", "contract.renewal_failed", "contract.renewal_opted_out", "contract.renewal_upcoming", "payment.received", "subscription.created", "subscription.renewed", "subscription.renewal_upcoming", "subscription.paused", "subscription.resumed", "subscription.cancelled", "subscription.upgraded", "subscription.downgraded", "subscription.changed", "subscription.past_due", "subscription.suspended", "subscription.cycle_changed", "subscription.payment_failed", "subscription.payment_retried", "subscription.proration_credit", "subscription.meter_added", "subscription.meter_removed", "subscription.usage_recorded", "subscription.usage_charges_applied", "customer.created", "customer.updated", "customer.deleted", "booking.created", "booking.cancelled", "booking.completed", "booking.no_show", "booking.held", "booking.hold_expired", "booking.rescheduled", "escrow.created", "escrow.released", "escrow.refunded", "escrow.condition_fulfilled", "escrow.reauthorization_pending", "escrow.reauthorized", "escrow.reauthorization_failed", "saved_config.created", "saved_config.viewed", "saved_config.converted", "saved_config.expiring", "saved_config.expired", "delegation.proposed", "delegation.accepted", "delegation.rejected", "delegation.countered", "delegation.granted", "delegation.revoked", "delegation.expired", "delegation.budget_warning", "agent.workflow.planned", "agent.workflow.completed", "agent.workflow.failed", "agent.workflow.step_completed", "agent.workflow.step_retried", "agent.workflow.dead_lettered", "agent.workflow.cancelled", "agent.workflow.degraded", "agent.workflow.approved", "workflow.step_approved", "agent.approval_required", "agent.approval_resent", "agent.approval_escalated", "agent.trust.level_changed", "agent.trust.abuse_detected", "agent.trust.decay_warning", "agent.trust.credential_issued", "agent.trust.credential_presented", "agent.trust.credential_revoked", "agent.trust_cap_exceeded", "agent.anomaly_detected", "agent.spending_ceiling", "workflow.sell.proposal_received", "workflow.fulfill.delivered", "product_family.created", "product_family.updated", "product_family.deleted", "option_group.created", "option_group.updated", "option_group.deleted", "option.created", "option.updated", "option.deleted", "compatibility_rule.created", "compatibility_rule.updated", "compatibility_rule.deleted", "bundle_rule.created", "bundle_rule.updated", "bundle_rule.deleted", "billing.low_balance", "billing.credit_added", "billing.credit_deducted", "billing.auto_topup", "billing.widget_degraded", "tenant.trust_level_changed", "tenant.trust_promoted", "tenant.trust_level_decay_warning", "trust.demoted", "trust.fraud_signal", "credential.issued", "api_key.rotated", "encryption.rekey_completed", "consent.expiring_soon", "consent.expired", "job.completed", "job.failed", "queue.depth_alert", "system.job_dead_letter", "service.circuit_opened", "service.circuit_closed", "circuit-breaker.backoff-increased", "security.csp_spike", "federation.settlement_completed", "federation.settlement_failed", "federation.escrow_disputed", "federation.escrow_expired", "portal.payment_completed", "portal.contract_signed", "portal.change_requested" ] }, "data": { "type": "object", "description": "Optional custom event payload. If omitted, a synthetic payload is generated." } } } } } }, "responses": { "200": { "description": "Webhook event dispatched", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "environment": { "type": "string", "const": "test" }, "sandbox": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "action": { "type": "string", "const": "simulate_webhook" }, "event": { "type": "string" }, "deliveries": { "type": "integer" }, "webhook_ids": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } } }, "required": [ "error", "success", "data" ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [ "sandbox:write" ] }, { "apiKeyHeader": [ "sandbox:write" ] }, { "sessionAuth": [] } ] } }, "/sandbox/status": { "get": { "tags": [ "Sandbox" ], "summary": "Get sandbox environment status", "description": "Returns counts of test-environment data for the authenticated tenant.", "operationId": "sandboxStatus", "responses": { "200": { "description": "Sandbox status", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "environment": { "type": "string", "const": "test" }, "sandbox": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "counts": { "type": "object" }, "total_test_records": { "type": "integer" } } } }, "required": [ "error", "success", "data" ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [ "sandbox:read" ] }, { "apiKeyHeader": [ "sandbox:read" ] }, { "sessionAuth": [] } ] } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List all webhooks (or get single with ?id=X)", "description": "Returns all registered webhooks for the current tenant. Supports both offset-based and cursor-based pagination.", "operationId": "listWebhooks", "parameters": [ { "name": "id", "in": "query", "description": "If provided, returns a single webhook by ID instead of a list", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by webhook status", "schema": { "type": "string", "enum": [ "active", "paused" ] } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/before" }, { "$ref": "#/components/parameters/sort" } ], "responses": { "200": { "description": "List of webhooks or a single webhook", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "pagination": { "oneOf": [ { "$ref": "#/components/schemas/Pagination" }, { "$ref": "#/components/schemas/CursorPagination" } ] } }, "required": [ "webhooks", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" } } } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "webhooks:read" ] }, { "apiKeyHeader": [ "webhooks:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Register a new webhook", "description": "Creates a new webhook endpoint. The signing secret is returned only in the creation response \u2014 store it securely.", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL to receive webhook events" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "Event types to subscribe to (e.g. deal.created, customer.updated)" }, "description": { "type": "string", "description": "Optional human-readable description" } } } } } }, "responses": { "201": { "description": "Webhook created. The secret is only shown once.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "webhook": { "type": "object", "properties": { "webhook_id": { "type": "string", "description": "Unique webhook identifier (wh_*)" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active" ] }, "secret": { "type": "string", "description": "Signing secret (whsec_*). Only returned on creation \u2014 store securely." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "webhook_id", "url", "events", "status", "secret", "created_at" ] } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] }, { "apiKeyHeader": [ "webhooks:write" ] }, { "sessionAuth": [] } ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "description": "Updates an existing webhook's URL, subscribed events, status, or description.", "operationId": "updateWebhook", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Webhook ID to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "New HTTPS endpoint URL" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "New set of event types to subscribe to" }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Webhook status. Setting to 'active' resets the failure counter." }, "description": { "type": "string", "description": "Human-readable description" } } } } } }, "responses": { "200": { "description": "Updated webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/Webhook" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] }, { "apiKeyHeader": [ "webhooks:write" ] }, { "sessionAuth": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "description": "Permanently removes a webhook registration. Future events will no longer be delivered to this endpoint.", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Webhook ID to delete", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeleteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] }, { "apiKeyHeader": [ "webhooks:write" ] }, { "sessionAuth": [] } ] } }, "/webhooks/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Get delivery history for a webhook", "description": "Returns delivery history for a specific webhook, including status, response codes, and error details.", "operationId": "getWebhookDeliveries", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Webhook ID to get deliveries for", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by delivery status", "schema": { "type": "string", "enum": [ "pending", "success", "failed" ] } }, { "name": "event_type", "in": "query", "description": "Filter by event type", "schema": { "$ref": "#/components/schemas/WebhookEventType" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Delivery history", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "type": "object", "properties": { "delivery_id": { "type": "string", "description": "Unique delivery identifier (whd_*)" }, "webhook_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "attempts": { "type": "integer" }, "response_code": { "type": "integer", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "delivery_id", "webhook_id", "event_type", "status", "attempts", "created_at" ] } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "webhooks:read" ] }, { "apiKeyHeader": [ "webhooks:read" ] }, { "sessionAuth": [] } ] } }, "/webhooks/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test event to a webhook", "description": "Sends a test webhook event to the specified endpoint. The payload includes `\"test\": true` to distinguish it from real events.", "operationId": "testWebhook", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Webhook ID to send test event to", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "default": "deal.created", "description": "Event type to simulate" } } } } } }, "responses": { "200": { "description": "Test event delivery result", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "response_code": { "type": "integer", "nullable": true }, "response_body": { "type": "string", "nullable": true }, "latency_ms": { "type": "integer", "description": "Round-trip latency in milliseconds" }, "error": { "type": "string", "nullable": true }, "event_type": { "type": "string", "description": "The event type that was simulated" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] }, { "apiKeyHeader": [ "webhooks:write" ] }, { "sessionAuth": [] } ] } }, "/webhooks/rotate_secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate a webhook's signing secret", "description": "Generates a new signing secret for the specified webhook. The new secret is returned only in this response \u2014 store it securely. The old secret is immediately invalidated.", "operationId": "rotateWebhookSecret", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Webhook ID to rotate secret for", "schema": { "type": "string" } } ], "responses": { "200": { "description": "New signing secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "webhook_id": { "type": "string" }, "secret": { "type": "string", "description": "New signing secret (whsec_*). Store securely." } }, "required": [ "webhook_id", "secret" ] } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] }, { "apiKeyHeader": [ "webhooks:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body required. The webhook ID is specified via the `id` query parameter.", "properties": {} } } } } } }, "/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "List webhook event history", "description": "Returns paginated event history with cursor-based pagination. Use `since_sequence` for cursor-based replay positioning.", "operationId": "listWebhookEvents", "parameters": [ { "name": "since_sequence", "in": "query", "description": "Return events after this sequence number (cursor-based pagination)", "schema": { "type": "integer", "format": "int64" } }, { "name": "since_timestamp", "in": "query", "description": "Return events created at or after this timestamp (ISO 8601)", "schema": { "type": "string", "format": "date-time" } }, { "name": "event_type", "in": "query", "description": "Filter by event type", "schema": { "$ref": "#/components/schemas/WebhookEventType" } }, { "name": "status", "in": "query", "description": "Filter by event delivery status", "schema": { "type": "string", "enum": [ "pending", "delivered", "partially_delivered", "failed" ] } }, { "name": "limit", "in": "query", "description": "Maximum events to return (1-100, default 50)", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Event history with cursor metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "cursor": { "type": "object", "properties": { "last_sequence": { "type": "integer", "description": "Sequence number of the last event in this page" }, "has_more": { "type": "boolean", "description": "Whether more events exist after this page" } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [ "webhooks:read" ] }, { "apiKeyHeader": [ "webhooks:read" ] }, { "sessionAuth": [] } ] } }, "/webhooks/dead_letter": { "get": { "tags": [ "Webhooks" ], "summary": "List dead letter queue entries", "description": "Returns deliveries that exhausted all retry attempts (max 3). Includes original payload, all attempt details, and final error.", "operationId": "listDeadLetters", "parameters": [ { "name": "event_type", "in": "query", "description": "Filter by event type", "schema": { "$ref": "#/components/schemas/WebhookEventType" } }, { "name": "webhook_id", "in": "query", "description": "Filter by webhook ID", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Dead letter entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "dead_letters": { "type": "array", "items": { "$ref": "#/components/schemas/DeadLetterEntry" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [ "webhooks:read" ] }, { "apiKeyHeader": [ "webhooks:read" ] }, { "sessionAuth": [] } ] } }, "/webhooks/replay": { "post": { "tags": [ "Webhooks" ], "summary": "Replay webhook events from cursor", "description": "Re-delivers events from a given sequence number or timestamp to a specific webhook endpoint. Rate limited to 100 events per request. Replayed deliveries include `X-Salesbooth-Replayed: true` header.", "operationId": "replayWebhookEvents", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_id" ], "properties": { "webhook_id": { "type": "string", "description": "Target webhook to replay events to" }, "since_sequence": { "type": "integer", "format": "int64", "description": "Replay events after this sequence number" }, "since_timestamp": { "type": "string", "format": "date-time", "description": "Replay events created at or after this timestamp" }, "event_type": { "$ref": "#/components/schemas/WebhookEventType", "description": "Only replay events of this type" } } } } } }, "responses": { "200": { "description": "Replay results", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "replayed": { "type": "integer", "description": "Number of events replayed" }, "webhook_id": { "type": "string" }, "has_more": { "type": "boolean", "description": "Whether more events exist beyond the 100-event limit" }, "events": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string" }, "event_sequence": { "type": "integer" }, "event_type": { "type": "string" }, "delivery_id": { "type": "string" } } } } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] }, { "apiKeyHeader": [ "webhooks:write" ] }, { "sessionAuth": [] } ] } }, "/webhooks/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Retry a failed webhook delivery", "description": "Manually retry a specific failed delivery. Resets the delivery to pending and attempts immediate re-delivery.", "operationId": "retryWebhookDelivery", "parameters": [ { "name": "delivery_id", "in": "query", "required": false, "description": "The delivery ID to retry (can also be provided in the request body)", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "required": [ "delivery_id" ], "properties": { "delivery_id": { "type": "string", "description": "ID of the failed delivery to retry" } } } } } }, "responses": { "200": { "description": "Retry result with updated delivery status", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "webhook_id": { "type": "string" }, "event_type": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "attempts": { "type": "integer" }, "response_code": { "type": "integer", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true }, "retried_at": { "type": "string", "format": "date-time" } } } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] }, { "apiKeyHeader": [ "webhooks:write" ] }, { "sessionAuth": [] } ] } }, "/webhooks/cleanup": { "post": { "tags": [ "Webhooks" ], "summary": "Run webhook event retention cleanup", "description": "Deletes delivered webhook events older than the retention period. Cron-compatible endpoint.", "operationId": "cleanupWebhookEvents", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "retention_days": { "type": "integer", "default": 30, "description": "Days to retain events (default: 30)" }, "batch_size": { "type": "integer", "default": 10000, "description": "Maximum records to delete per run" } } } } } }, "responses": { "200": { "description": "Cleanup results", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "cutoff_date": { "type": "string", "format": "date-time" }, "retention_days": { "type": "integer" }, "events_deleted": { "type": "integer" }, "deliveries_deleted": { "type": "integer" } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [ "webhooks:write" ] }, { "apiKeyHeader": [ "webhooks:write" ] }, { "sessionAuth": [] } ] } }, "/schema/state-machine": { "get": { "tags": [ "Schema" ], "summary": "Get state machine definitions", "description": "Returns machine-readable state machine definitions for entity types (deals, contracts). No authentication required \u2014 this is metadata. Responses are cacheable (1 hour client, 24 hours CDN).", "operationId": "getStateMachine", "security": [], "parameters": [ { "name": "entity", "in": "query", "description": "Filter by entity type. Omit to get all entity types.", "required": false, "schema": { "type": "string", "enum": [ "deals", "contracts" ] } } ], "responses": { "200": { "description": "State machine definitions", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=3600, s-maxage=86400" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/StateMachineResponse" } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/schema/deal-terms": { "get": { "tags": [ "Schema" ], "summary": "Get deal terms JSON schema", "description": "Returns the JSON Schema document defining the structure of machine-readable deal terms. Agents can fetch this schema to understand what terms are expressible. No authentication required \u2014 this is metadata.", "operationId": "getDealTermsSchema", "security": [], "responses": { "200": { "description": "Deal terms JSON schema", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=3600, s-maxage=86400" } }, "content": { "application/json": { "schema": { "type": "object", "description": "JSON Schema document (draft 2020-12)" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/deals/{id}/valid-transitions": { "get": { "tags": [ "Deals" ], "summary": "Get valid status transitions for a deal", "description": "Returns context-aware valid transitions for a specific deal, checking both state machine rules and business rules (has line items, has customer, signature status).", "operationId": "getDealValidTransitions", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "string", "pattern": "^deal_[a-zA-Z0-9]+$" } } ], "responses": { "200": { "description": "Valid transitions for this deal", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/ValidTransitionsResponse" } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ] } }, "/audit/export": { "get": { "operationId": "exportAuditTrail", "summary": "Export audit trail as a compliance evidence package", "description": "Produces a self-contained, verifiable compliance evidence package from the immutable audit trail. Supports three export modes:\n\n1. **Single entity**: Provide `entity_type` and `entity_id` for a complete audit package including hash chain verification, entity snapshot, and signature data.\n2. **Date range**: Provide `start_date` and `end_date` to export all audit entries within the period.\n3. **Bulk by type**: Provide `entity_type` alone to export all audit entries for that entity type.\n\nExports include a `verification_hash` (SHA-256) covering the entire payload for tamper detection.", "tags": [ "Audit" ], "parameters": [ { "name": "entity_type", "in": "query", "description": "Entity type to export audit trail for", "schema": { "type": "string", "enum": [ "deal", "contract", "customer", "product" ] } }, { "name": "entity_id", "in": "query", "description": "Specific entity ID (required with entity_type for single-entity export)", "schema": { "type": "string" } }, { "name": "format", "in": "query", "description": "Export format", "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" } }, { "name": "start_date", "in": "query", "description": "Start date for date-range export (Y-m-d or Y-m-d H:i:s)", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "End date for date-range export (Y-m-d or Y-m-d H:i:s)", "schema": { "type": "string", "format": "date" } }, { "name": "limit", "in": "query", "description": "Maximum number of entries to return (for paginated exports)", "schema": { "type": "integer", "default": 1000, "maximum": 10000 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Audit export package", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "export_version": { "type": "string", "example": "1.0" }, "export_metadata": { "type": "object", "properties": { "generated_at": { "type": "string", "format": "date-time" }, "generated_by": { "type": "string", "example": "salesbooth" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "total_entries": { "type": "integer" }, "salesbooth_version": { "type": "string" } } }, "audit_entries": { "type": "array", "items": { "type": "object", "properties": { "log_id": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "action": { "type": "string" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "changes": { "type": "object", "nullable": true }, "snapshot": { "type": "object", "nullable": true }, "previous_hash": { "type": "string", "nullable": true }, "entry_hash": { "type": "string" }, "created_at": { "type": "string" } } } }, "hash_chain_verification": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verified", "tampered", "no_entries" ] }, "message": { "type": "string" }, "total_entries": { "type": "integer" } } }, "entity_snapshot": { "type": "object", "nullable": true }, "signature_data": { "type": "object", "nullable": true }, "verification_hash": { "type": "string", "description": "SHA-256 hash of the complete export payload for tamper detection" } } } }, "required": [ "error", "success", "data" ] } }, "text/csv": { "schema": { "type": "string", "description": "CSV with columns: timestamp, actor_type, actor_id, entity_type, entity_id, action, changes_summary, entry_hash" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [ "audit:export" ] }, { "apiKeyHeader": [ "audit:export" ] }, { "sessionAuth": [] } ] } }, "/payments": { "get": { "tags": [ "Payments" ], "summary": "Get payment status for a deal or payment settings", "description": "Returns the current payment status for a deal, or payment settings (Stripe Connect status, payment method toggles, invoice settings) when action=settings.", "operationId": "getPayment", "parameters": [ { "name": "action", "in": "query", "description": "Action to perform. Use 'settings' to get payment settings.", "schema": { "type": "string", "enum": [ "settings" ] } }, { "name": "deal_id", "in": "query", "description": "The deal ID to get payment status for (required when action is not 'settings')", "required": true, "schema": { "type": "string", "pattern": "^deal_[a-zA-Z0-9]+$" } } ], "responses": { "200": { "description": "Payment status or payment settings", "content": { "application/json": { "schema": { "oneOf": [ { "title": "PaymentStatusResponse", "description": "Payment status for a deal (returned when deal_id is provided)", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "deal_id": { "type": "string" }, "payment_processor": { "type": "string", "nullable": true }, "payment_intent_id": { "type": "string", "nullable": true }, "payment_charge_id": { "type": "string", "nullable": true }, "payment_status": { "type": "string" }, "payment_amount": { "type": "string", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "deposit_collected": { "type": "string", "nullable": true }, "balance_due": { "type": "string", "nullable": true }, "total": { "type": "string" }, "currency": { "type": "string" }, "stripe_status": { "type": "string", "description": "Raw Stripe PaymentIntent status (e.g. succeeded, requires_payment_method). Present when Stripe is the payment processor.", "nullable": true } } } }, "required": [ "error", "success", "data" ] }, { "title": "PaymentSettingsResponse", "description": "Payment settings (returned when action=settings)", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "stripe": { "type": "object", "description": "Stripe Connect status and configuration", "properties": { "connected": { "type": "boolean", "description": "Whether a Stripe Connect account is linked" }, "account_id": { "type": "string", "nullable": true, "description": "The Stripe Connect account ID" }, "key_configured": { "type": "boolean", "description": "Whether a Stripe secret key is configured" } } }, "payment_methods": { "type": "object", "description": "Enabled payment method toggles", "properties": { "accept_card": { "type": "boolean", "description": "Whether card payments are accepted" }, "accept_bank": { "type": "boolean", "description": "Whether bank/ACH payments are accepted" }, "accept_manual": { "type": "boolean", "description": "Whether manual payments are accepted" } } }, "invoice_settings": { "type": "object", "description": "Invoice configuration", "properties": { "invoice_prefix": { "type": "string", "description": "Prefix for invoice numbers (e.g. INV-)" }, "payment_terms_days": { "type": "integer", "description": "Default payment terms in days" } } } } } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Payments" ], "summary": "Create a payment intent or perform payment actions", "description": "Perform payment operations on a deal or manage payment settings. Use the `action` query parameter to specify the operation:\n\n- `create-intent`: Create a Stripe PaymentIntent for a deal\n- `confirm`: Confirm a payment has succeeded\n- `capture`: Capture a previously-authorized PaymentIntent (auth-only flows)\n- `refund`: Process a partial or full refund\n- `record-manual`: Record a manual (non-Stripe) payment\n- `charge-saved-method`: Charge a customer's saved payment method off-session (agent use)\n- `poll-intent`: Poll Stripe PaymentIntent status without webhook dependency\n- `generate-link`: Generate a Stripe Checkout Session URL for customer payment\n- `save-settings`: Save payment method toggles and invoice settings\n- `connect-stripe`: Initiate Stripe Connect onboarding\n- `disconnect-stripe`: Disconnect Stripe account", "operationId": "postPayment", "parameters": [ { "name": "action", "in": "query", "description": "Payment action to perform", "required": true, "schema": { "type": "string", "enum": [ "confirm", "capture", "refund", "record-manual", "charge-saved-method", "poll-intent", "generate-link", "save-settings", "connect-stripe", "disconnect-stripe", "create-intent" ] } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "description": "Request body varies by action. Each action requires different fields \u2014 see the per-action schemas.", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentConfirmRequest" }, { "$ref": "#/components/schemas/PaymentCaptureRequest" }, { "$ref": "#/components/schemas/PaymentRefundRequest" }, { "$ref": "#/components/schemas/PaymentRecordManualRequest" }, { "$ref": "#/components/schemas/PaymentChargeSavedMethodRequest" }, { "$ref": "#/components/schemas/PaymentPollIntentRequest" }, { "$ref": "#/components/schemas/PaymentGenerateLinkRequest" }, { "$ref": "#/components/schemas/PaymentSaveSettingsRequest" }, { "$ref": "#/components/schemas/PaymentConnectStripeRequest" }, { "$ref": "#/components/schemas/PaymentDisconnectStripeRequest" }, { "$ref": "#/components/schemas/PaymentCreateIntentRequest" } ] } } } }, "responses": { "201": { "description": "Payment intent created (create-intent action)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "client_secret": { "type": "string" }, "payment_intent_id": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string", "description": "Stripe PaymentIntent status (e.g. requires_payment_method, requires_confirmation, requires_action)" }, "existing": { "type": "boolean", "description": "Whether an existing PaymentIntent was reused (true) or a new one was created (false)" } } } }, "required": [ "error", "success", "data" ] } } } }, "200": { "description": "Payment action completed successfully", "content": { "application/json": { "schema": { "oneOf": [ { "title": "CaptureResponse", "description": "Response for capture action", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "payment_intent_id": { "type": "string" }, "captured_amount": { "type": "number" }, "currency": { "type": "string" }, "payment_status": { "type": "string" }, "deal_status": { "type": "string" } } } }, "required": [ "error", "success", "data" ] }, { "title": "ChargeSavedMethodResponse", "description": "Response for charge-saved-method action", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "payment_intent_id": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "payment_status": { "type": "string" }, "deal_status": { "type": "string" }, "balance_due": { "type": "number" } } } }, "required": [ "error", "success", "data" ] }, { "title": "PollIntentResponse", "description": "Response for poll-intent action", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "payment_intent_id": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "number" }, "amount_received": { "type": "number" }, "currency": { "type": "string" }, "last_payment_error": { "type": [ "object", "null" ] } } } }, "required": [ "error", "success", "data" ] }, { "title": "GenerateLinkResponse", "description": "Response for generate-link action", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "payment_link": { "type": "string", "format": "uri" }, "checkout_session_id": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "required": [ "error", "success", "data" ] }, { "title": "ConfirmPaymentResponse", "description": "Response for confirm action \u2014 full payment status after confirmation", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deal_id": { "type": "string" }, "payment_processor": { "type": "string", "nullable": true }, "payment_intent_id": { "type": "string", "nullable": true }, "payment_charge_id": { "type": "string", "nullable": true }, "payment_status": { "type": "string" }, "payment_amount": { "type": "string", "nullable": true }, "paid_at": { "type": "string", "format": "date-time", "nullable": true }, "deposit_collected": { "type": "string", "nullable": true }, "balance_due": { "type": "string", "nullable": true }, "total": { "type": "string" }, "currency": { "type": "string" } } } }, "required": [ "error", "success", "data" ] }, { "title": "RefundPaymentResponse", "description": "Response for refund action", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "refund_id": { "type": "string", "description": "Stripe refund ID" }, "deal_id": { "type": "string" }, "payment_intent_id": { "type": "string" }, "refund_amount": { "type": "string", "description": "Refunded amount as decimal string" }, "currency": { "type": "string" }, "refund_type": { "type": "string", "enum": [ "full", "partial" ], "description": "Whether this was a full or partial refund" }, "payment_status": { "type": "string", "description": "Updated deal payment status (refunded or partially_refunded)" }, "balance_due": { "type": "string", "description": "Updated balance due after refund" }, "status": { "type": "string", "description": "Stripe refund status" } } } }, "required": [ "error", "success", "data" ] }, { "title": "RecordManualPaymentResponse", "description": "Response for record-manual action", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deal_id": { "type": "string" }, "payment_processor": { "type": "string", "description": "Always 'manual' for manually recorded payments" }, "payment_status": { "type": "string", "description": "Always 'captured' for manually recorded payments" }, "payment_amount": { "type": "string", "description": "Amount recorded as decimal string" }, "method": { "type": "string", "enum": [ "cash", "wire", "cheque", "bank_transfer", "other" ], "description": "Payment method used" }, "reference": { "type": "string", "description": "Optional reference number or identifier" }, "paid_at": { "type": "string", "format": "date-time", "description": "Timestamp when payment was recorded" }, "deposit_collected": { "type": "string", "description": "Total deposit collected to date" }, "balance_due": { "type": "string", "description": "Remaining balance due" } } } }, "required": [ "error", "success", "data" ] }, { "title": "SaveSettingsResponse", "description": "Response for save-settings action", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Payment settings saved" } } } }, "required": [ "error", "success", "data" ] }, { "title": "ConnectStripeResponse", "description": "Response for connect-stripe action", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Stripe Account Link URL for onboarding" }, "account_id": { "type": "string", "description": "The newly created Stripe Connect account ID" } } } }, "required": [ "error", "success", "data" ] }, { "title": "DisconnectStripeResponse", "description": "Response for disconnect-stripe action", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "message": { "type": "string", "example": "Stripe account disconnected" } } } }, "required": [ "error", "success", "data" ] }, { "title": "SuccessResponse", "description": "Generic success response for other actions", "$ref": "#/components/schemas/SuccessResponse" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ] } }, "/subscriptions": { "get": { "tags": [ "Subscriptions" ], "summary": "List subscriptions or get subscription detail", "description": "Returns subscriptions for the authenticated tenant. Use query parameters to filter by status or get a specific subscription by deal ID. Use `?action=analytics` for MRR/ARR/churn metrics. Use `?action=usage_summary&id={deal_id}` for current cycle usage. Use `?action=usage_history&id={deal_id}` for historical usage. Use `?action=meters&id={deal_id}` to list meters.", "operationId": "getSubscriptions", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Deal ID to get subscription detail" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "paused", "cancelled", "past_due", "suspended" ] }, "description": "Filter by subscription status" }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "analytics", "usage_summary", "usage_history", "meters" ] }, "description": "Set to 'analytics' for MRR/ARR/churn metrics, 'usage_summary' for current cycle usage, 'usage_history' for historical records, 'meters' to list active meters" }, { "name": "preview_cycle", "in": "query", "schema": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ] }, "description": "Preview proration for changing billing cycle (requires id parameter)" }, { "name": "metric", "in": "query", "schema": { "type": "string" }, "description": "Filter usage history by metric name (for action=usage_history)" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Subscription data or analytics", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "List of subscriptions with pagination", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "subscriptions", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "$ref": "#/components/schemas/SuccessResponse" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Subscriptions" ], "summary": "Create or manage subscriptions", "description": "Perform subscription lifecycle operations. Use the `action` parameter to specify the operation: create, renew, pause, resume, cancel, change, change-cycle, retry-payment, add-meter, remove-meter, or record-usage.", "operationId": "postSubscription", "requestBody": { "description": "Request body varies by action. Each action requires different fields \u2014 see the per-action schemas.", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SubscriptionCreateRequest" }, { "$ref": "#/components/schemas/SubscriptionRenewRequest" }, { "$ref": "#/components/schemas/SubscriptionPauseRequest" }, { "$ref": "#/components/schemas/SubscriptionResumeRequest" }, { "$ref": "#/components/schemas/SubscriptionCancelRequest" }, { "$ref": "#/components/schemas/SubscriptionChangeRequest" }, { "$ref": "#/components/schemas/SubscriptionChangeCycleRequest" }, { "$ref": "#/components/schemas/SubscriptionRetryPaymentRequest" }, { "$ref": "#/components/schemas/SubscriptionAddMeterRequest" }, { "$ref": "#/components/schemas/SubscriptionRemoveMeterRequest" }, { "$ref": "#/components/schemas/SubscriptionRecordUsageRequest" } ] } } } }, "responses": { "200": { "description": "Subscription action completed. Returns the updated Deal for pause, resume, cancel, change, change-cycle, and retry-payment actions. For cancel/change/change-cycle, an optional proration object is included alongside the Deal fields. Returns a meter archived confirmation for remove-meter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Deal" }, { "$ref": "#/components/schemas/SubscriptionMeterArchived" } ], "description": "Returns a Deal for pause/resume/cancel/change/change-cycle/retry-payment actions. For cancel, change, and change-cycle, the Deal includes an additional proration object with proration_amount, remaining_days, and cycle_days. Returns a SubscriptionMeterArchived object for remove-meter." } }, "required": [ "error", "success", "data" ] } } } }, "201": { "description": "Resource created. Returns a Deal for create and renew actions (subscription activated/renewed). Returns a SubscriptionMeter object for add-meter. Returns a SubscriptionUsageRecord for record-usage.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Deal" }, { "$ref": "#/components/schemas/SubscriptionMeter" }, { "$ref": "#/components/schemas/SubscriptionUsageRecord" } ], "description": "Returns a Deal for create/renew actions. Returns a SubscriptionMeter for add-meter. Returns a SubscriptionUsageRecord (or SubscriptionUsageRecord with records array for batch) for record-usage." } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "create", "renew", "pause", "resume", "cancel", "change", "change-cycle", "retry-payment", "add-meter", "remove-meter", "record-usage" ] }, "description": "The subscription lifecycle operation to perform." }, { "$ref": "#/components/parameters/idempotencyKey" } ] } }, "/tenant/public-key": { "get": { "tags": [ "Trust" ], "summary": "Get tenant's Ed25519 public key", "description": "Returns a tenant's Ed25519 public key for third-party deal verification. This is a public endpoint \u2014 no authentication required.", "operationId": "getPublicKey", "security": [], "parameters": [ { "name": "tenant_id", "in": "query", "description": "Tenant ID to retrieve the public key for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant public key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "public_key": { "type": "string", "description": "Base64-encoded Ed25519 public key" }, "algorithm": { "type": "string", "const": "Ed25519" } } } }, "required": [ "error", "success", "data" ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/stripe-webhook": { "post": { "tags": [ "Stripe Webhooks" ], "summary": "Process incoming Stripe webhook events", "description": "Receives Stripe webhook events and processes payment lifecycle updates. Verifies the webhook signature using the `Stripe-Signature` header.\n\nHandled event types:\n- `payment_intent.succeeded` \u2014 Confirms payment, transitions deal to closed\n- `payment_intent.payment_failed` \u2014 Marks payment as failed\n- `charge.refunded` \u2014 Handles refunds initiated from Stripe Dashboard", "operationId": "handleStripeWebhook", "security": [], "parameters": [ { "name": "Stripe-Signature", "in": "header", "description": "Stripe webhook signature for event verification", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Raw Stripe event payload" } } } }, "responses": { "200": { "description": "Webhook processed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "processed": { "type": "boolean" }, "event_type": { "type": "string" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/bundle-rules": { "get": { "tags": [ "BundleRules" ], "summary": "List or retrieve bundle pricing rules", "operationId": "listBundleRules", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Bundle rule ID to retrieve a specific rule", "required": false, "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "description": "Filter by product ID", "required": false, "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "description": "Filter by active status", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRuleListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Returns bundle pricing rules for the tenant. Bundle rules define discount conditions that apply when multiple product options are selected together." }, "post": { "tags": [ "BundleRules" ], "summary": "Create a bundle pricing rule", "operationId": "createBundleRule", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "discount_type", "discount_value", "option_ids" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "discount_type": { "type": "string", "enum": [ "fixed", "percent" ] }, "discount_value": { "type": "number", "minimum": 0.01 }, "product_id": { "type": "string", "maxLength": 50 }, "min_options": { "type": "integer", "minimum": 0 }, "is_active": { "type": "boolean" }, "option_ids": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 100 } } } } } }, "responses": { "201": { "description": "Bundle rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRuleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Creates a new bundle pricing rule. Define which option combination triggers the discount and the discount amount or percentage to apply." }, "patch": { "tags": [ "BundleRules" ], "summary": "Update a bundle pricing rule", "operationId": "updateBundleRule", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Bundle rule ID to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "discount_type": { "type": "string", "enum": [ "fixed", "percent" ] }, "discount_value": { "type": "number", "minimum": 0.01 }, "min_options": { "type": "integer", "minimum": 0 }, "is_active": { "type": "boolean" }, "option_ids": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 100 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRuleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Updates an existing bundle rule by ID. Modify trigger conditions, discount value, or active status." }, "delete": { "tags": [ "BundleRules" ], "summary": "Delete a bundle pricing rule", "operationId": "deleteBundleRule", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Bundle rule ID to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bundle rule deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleRuleDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Deletes a bundle rule by ID. Removing a rule immediately stops it from applying to new configurations." } }, "/compatibility-rules": { "get": { "tags": [ "CompatibilityRules" ], "summary": "List or retrieve compatibility rules", "operationId": "listCompatibilityRules", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Compatibility rule ID to retrieve a specific rule", "required": false, "schema": { "type": "string" } }, { "name": "product_id", "in": "query", "description": "Filter by product ID", "required": false, "schema": { "type": "string" } }, { "name": "rule_type", "in": "query", "description": "Filter by rule type", "required": false, "schema": { "type": "string", "enum": [ "requires", "excludes", "includes_price" ] } }, { "name": "source_option_id", "in": "query", "description": "Filter by source option ID", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityRuleListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Returns compatibility rules for the tenant. Compatibility rules define `requires`, `excludes`, and `includes_price` relationships between product options." }, "post": { "tags": [ "CompatibilityRules" ], "summary": "Create a compatibility rule", "operationId": "createCompatibilityRule", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_option_id", "target_option_id", "rule_type" ], "properties": { "source_option_id": { "type": "string", "maxLength": 50 }, "target_option_id": { "type": "string", "maxLength": 50 }, "rule_type": { "type": "string", "enum": [ "requires", "excludes", "includes_price" ] }, "product_id": { "type": "string", "maxLength": 50 }, "message": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "201": { "description": "Compatibility rule created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityRuleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Creates a new compatibility rule between two product options. Use to prevent incompatible option combinations or enforce dependency relationships." }, "patch": { "tags": [ "CompatibilityRules" ], "summary": "Update a compatibility rule", "operationId": "updateCompatibilityRule", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Compatibility rule ID to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_option_id": { "type": "string", "maxLength": 50 }, "target_option_id": { "type": "string", "maxLength": 50 }, "rule_type": { "type": "string", "enum": [ "requires", "excludes", "includes_price" ] }, "product_id": { "type": "string", "maxLength": 50 }, "message": { "type": "string" }, "is_active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityRuleResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Updates an existing compatibility rule by ID. Modify the rule type, option targets, or conditions." }, "delete": { "tags": [ "CompatibilityRules" ], "summary": "Delete a compatibility rule", "operationId": "deleteCompatibilityRule", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Compatibility rule ID to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Compatibility rule deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityRuleDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Deletes a compatibility rule by ID." } }, "/option-groups": { "get": { "tags": [ "OptionGroups" ], "summary": "List or retrieve option groups", "operationId": "getOptionGroups", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Option group ID to retrieve a specific group. Use with `action=options` to list options within the group.", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Action to perform: `options` to manage options within a group", "required": false, "schema": { "type": "string", "enum": [ "options" ] } }, { "name": "option_id", "in": "query", "description": "Option ID for single option operations (requires `action=options`)", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "archived" ] } }, { "name": "search", "in": "query", "description": "Search by name", "required": false, "schema": { "type": "string" } }, { "name": "include_options", "in": "query", "description": "Include options in group list response", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Returns option groups and their options for the tenant. Option groups are reusable sets of selectable options (e.g. colour, size) attached to products." }, "post": { "tags": [ "OptionGroups" ], "summary": "Create an option group or option", "description": "Create a new option group, or create an option within a group when `id` and `action=options` are provided. The two modes accept different field sets \u2014 see the request body oneOf schemas for details.", "operationId": "createOptionGroup", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Option group ID (required when creating an option within a group)", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Set to `options` when creating an option within a group", "required": false, "schema": { "type": "string", "enum": [ "options" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Create option group", "description": "Create a new option group (no `id` or `action` query params). Only group-level fields are accepted.", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "selection_type": { "type": "string", "enum": [ "single", "multiple" ] }, "is_required": { "type": "boolean" }, "min_selections": { "type": "integer", "minimum": 0, "maximum": 100 }, "max_selections": { "type": "integer", "minimum": 0, "maximum": 100 }, "display_style": { "type": "string", "enum": [ "cards", "dropdown", "pills", "swatches", "checkboxes" ] }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 99999 }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] } } }, { "title": "Create option within a group", "description": "Create an individual option inside a group (requires `?id=X&action=options`). Only option-level fields are accepted.", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "price_modifier": { "type": "number", "minimum": -99999999.99, "maximum": 99999999.99 }, "price_type": { "type": "string", "enum": [ "fixed", "percent" ] }, "billing_type": { "type": "string", "enum": [ "once_off", "recurring" ], "default": "once_off", "description": "Whether this option represents a one-time or recurring charge" }, "is_default": { "type": "boolean" }, "image_url": { "type": "string", "maxLength": 500 }, "sku_fragment": { "type": "string", "maxLength": 50 }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 99999 }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] }, "metadata": { "type": "object", "description": "Arbitrary key-value metadata (max 3 levels deep, 4096 bytes)" } } } ] } } } }, "responses": { "201": { "description": "Option group or option created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "OptionGroups" ], "summary": "Update an option group or option", "operationId": "updateOptionGroup", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Option group ID to update", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Set to `options` when updating an option within a group", "required": false, "schema": { "type": "string", "enum": [ "options" ] } }, { "name": "option_id", "in": "query", "description": "Option ID when updating a specific option (requires `action=options`)", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "Update option group", "description": "Used when updating a group (`id` only, no `action=options`). Only group-level fields are accepted; option-only fields (price_modifier, price_type, billing_type, is_default, image_url, sku_fragment, metadata) are not valid here and will be stripped.", "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "selection_type": { "type": "string", "enum": [ "single", "multiple" ] }, "is_required": { "type": "boolean" }, "min_selections": { "type": "integer", "minimum": 0, "maximum": 100 }, "max_selections": { "type": "integer", "minimum": 0, "maximum": 100 }, "display_style": { "type": "string", "enum": [ "cards", "dropdown", "pills", "swatches", "checkboxes" ] }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 99999 }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] } } }, { "title": "Update option within a group", "description": "Used when updating an individual option (`id` + `action=options` + `option_id`). Only option-level fields are accepted; group-only fields (selection_type, is_required, min_selections, max_selections, display_style) are not valid here.", "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "price_modifier": { "type": "number", "minimum": -99999999.99, "maximum": 99999999.99 }, "price_type": { "type": "string", "enum": [ "fixed", "percent" ] }, "billing_type": { "type": "string", "enum": [ "once_off", "recurring" ], "description": "Whether this option represents a one-time or recurring charge" }, "is_default": { "type": "boolean" }, "image_url": { "type": "string", "maxLength": 500 }, "sku_fragment": { "type": "string", "maxLength": 50 }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 99999 }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] }, "metadata": { "type": "object", "description": "Arbitrary key-value metadata (max 3 levels deep, 4096 bytes)" } } } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Updates an option group or individual option. Use `?id=X` to update a group (GROUP_SCHEMA fields only). Use `?id=X&action=options&option_id=Y` to update an individual option (OPTION_SCHEMA fields only). The two modes accept different field sets \u2014 see the request body oneOf schemas for details." }, "delete": { "tags": [ "OptionGroups" ], "summary": "Archive an option group or option", "operationId": "deleteOptionGroup", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Option group ID to archive", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Set to `options` when archiving an option within a group", "required": false, "schema": { "type": "string", "enum": [ "options" ] } }, { "name": "option_id", "in": "query", "description": "Option ID to archive (requires `action=options`)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Deletes an option group by ID. Only groups not referenced by any product can be deleted." } }, "/product-families": { "get": { "tags": [ "ProductFamilies" ], "summary": "List or retrieve product families", "operationId": "getProductFamilies", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Product family ID to retrieve a specific family", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive", "archived" ] } }, { "name": "search", "in": "query", "description": "Search by name", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Returns product families for the tenant. Product families are top-level groupings for organizing related products in the catalogue." }, "post": { "tags": [ "ProductFamilies" ], "summary": "Create a product family", "operationId": "createProductFamily", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "slug": { "type": "string", "maxLength": 255 }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 99999 }, "image_url": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] }, "display_template": { "type": "string", "enum": [ "grid", "configurator", "comparison", "bundle_builder" ], "description": "How products in this family should be presented in widgets" }, "default_option_types": { "type": "array", "items": { "type": "string" }, "description": "Common option types for products in this family" }, "icon": { "type": "string", "maxLength": 100, "description": "Family icon for admin navigation and widget headers" }, "configurator_settings": { "type": "object", "description": "Family-level widget defaults (suggested_title_template, suggested_cta, suggested_step_names)", "properties": { "suggested_title_template": { "type": "string" }, "suggested_cta": { "type": "string" }, "suggested_step_names": { "type": "array", "items": { "type": "string" } } } }, "metadata": { "type": "object" } } } } } }, "responses": { "201": { "description": "Product family created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Creates a new product family. Use families to group products by category, brand, or product line." }, "patch": { "tags": [ "ProductFamilies" ], "summary": "Update a product family", "operationId": "updateProductFamily", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Product family ID to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": "string" }, "slug": { "type": "string", "maxLength": 255 }, "sort_order": { "type": "integer", "minimum": 0, "maximum": 99999 }, "image_url": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] }, "display_template": { "type": "string", "enum": [ "grid", "configurator", "comparison", "bundle_builder" ], "description": "How products in this family should be presented in widgets" }, "default_option_types": { "type": "array", "items": { "type": "string" }, "description": "Common option types for products in this family" }, "icon": { "type": "string", "maxLength": 100, "description": "Family icon for admin navigation and widget headers" }, "configurator_settings": { "type": "object", "description": "Family-level widget defaults (suggested_title_template, suggested_cta, suggested_step_names)", "properties": { "suggested_title_template": { "type": "string" }, "suggested_cta": { "type": "string" }, "suggested_step_names": { "type": "array", "items": { "type": "string" } } } }, "metadata": { "type": "object" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Updates a product family by ID. Modify the family name, description, or display order." }, "delete": { "tags": [ "ProductFamilies" ], "summary": "Archive a product family", "operationId": "deleteProductFamily", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Product family ID to archive", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Deletes a product family by ID. Products in the family are not deleted but will no longer be grouped." } }, "/product-option-groups": { "get": { "tags": [ "ProductOptionGroups" ], "summary": "Get product option groups or availability", "description": "Returns all option groups and options linked to a product, used as the configurator data source.", "operationId": "getProductOptions", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "product_id", "in": "query", "description": "Product ID to get option groups for (required)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "ProductOptionGroups" ], "summary": "Link option group to product or set availability", "description": "Link an option group to a product, or set option-level availability with `action=availability`.", "operationId": "linkOptionGroup", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "description": "Set to `availability` to manage option availability instead of linking groups", "required": false, "schema": { "type": "string", "enum": [ "availability" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string", "maxLength": 50 }, "group_id": { "type": "string", "maxLength": 50 }, "sort_order_override": { "type": "integer", "minimum": 0, "maximum": 99999 }, "is_required_override": { "type": "boolean" }, "option_id": { "type": "string", "maxLength": 50 }, "is_available": { "type": "boolean" }, "price_modifier_override": { "type": "number" } } } } } }, "responses": { "201": { "description": "Link or availability created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "ProductOptionGroups" ], "summary": "Update link overrides or availability", "operationId": "updateOptionGroupLink", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "product_id", "in": "query", "description": "Product ID", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "query", "description": "Option group ID (for link updates)", "required": false, "schema": { "type": "string" } }, { "name": "option_id", "in": "query", "description": "Option ID (for availability updates)", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Set to `availability` for option availability updates", "required": false, "schema": { "type": "string", "enum": [ "availability" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sort_order_override": { "type": "integer", "minimum": 0, "maximum": 99999 }, "is_required_override": { "type": "boolean" }, "is_available": { "type": "boolean" }, "price_modifier_override": { "type": "number" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Updates a product-to-option-group link. Modify per-product option overrides \u2014 which options are available, default selections, or display order for this specific product." }, "delete": { "tags": [ "ProductOptionGroups" ], "summary": "Unlink option group from product or remove availability", "operationId": "unlinkOptionGroup", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "product_id", "in": "query", "description": "Product ID", "required": true, "schema": { "type": "string" } }, { "name": "group_id", "in": "query", "description": "Option group ID to unlink", "required": false, "schema": { "type": "string" } }, { "name": "option_id", "in": "query", "description": "Option ID (for availability removal)", "required": false, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Set to `availability` for option availability removal", "required": false, "schema": { "type": "string", "enum": [ "availability" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Removes a product-to-option-group link by ID. The option group remains available for other products." } }, "/product-rules": { "get": { "tags": [ "ProductRules" ], "summary": "Get all compatibility and bundle rules for a product", "operationId": "getProductRules", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "product_id", "in": "query", "description": "Product ID to get rules for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Returns an aggregated view of all rules configured for a product \u2014 bundle rules, compatibility rules, and option-level constraints. Use to validate a product's rule consistency before publishing." }, "post": { "tags": [ "ProductRules" ], "summary": "Validate a set of selected options against product rules", "description": "Validates a configuration of selected options against all compatibility and bundle rules for a product. Returns errors, warnings, and applicable bundle discounts.", "operationId": "validateConfiguration", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "product_id", "in": "query", "description": "Product ID to validate against", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Must be `validate`", "required": true, "schema": { "type": "string", "enum": [ "validate" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "option_ids" ], "properties": { "option_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of selected option IDs to validate" } } } } } }, "responses": { "200": { "description": "Validation result with errors, warnings, and applicable bundles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/uploads": { "post": { "tags": [ "Uploads" ], "summary": "Upload an image file", "description": "Upload an image file (JPEG, PNG, GIF, WebP, SVG). Requires admin privileges. Max file size: 2MB.", "operationId": "uploadImage", "security": [ { "bearerAuth": [ "products:write" ] }, { "apiKeyHeader": [ "products:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Image file to upload (max 2MB, supported: JPEG, PNG, GIF, WebP, SVG)" } } } } } }, "responses": { "200": { "description": "Image uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "Relative URL path to the uploaded file" }, "filename": { "type": "string" }, "size": { "type": "integer", "description": "File size in bytes" }, "mime_type": { "type": "string" } }, "required": [ "url", "filename", "size", "mime_type" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/saved-configs": { "get": { "tags": [ "SavedConfigs" ], "summary": "Retrieve a saved configuration by short code", "description": "Public endpoint \u2014 retrieves a saved product configuration by its unique short code. Uses publishable API key auth (Bearer sb_pub_...). Returns product selections, option choices, pricing snapshot, and expiration status.", "operationId": "getSavedConfig", "security": [], "parameters": [ { "name": "code", "in": "query", "description": "The unique short code of the saved configuration (8-16 hex characters)", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{8,16}$" } } ], "responses": { "200": { "description": "Saved configuration retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "short_code": { "type": "string" }, "widget_id": { "type": "string" }, "product_selections": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "configured_price": { "type": "number" } } } }, "option_selections": { "type": "object", "nullable": true }, "pricing_snapshot": { "type": "object" }, "subtotal": { "type": "number" }, "currency": { "type": "string" }, "customer_name": { "type": "string", "nullable": true }, "customer_email": { "type": "string", "nullable": true }, "expired": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "share_url": { "type": "string", "description": "Public shareable URL for this configuration" }, "price_changes": { "type": "array", "description": "Products whose prices have changed since the configuration was saved", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "snapshot_price": { "type": "number" }, "current_price": { "type": "number" }, "difference": { "type": "number" } } } } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "SavedConfigs" ], "summary": "Create a saved configuration or convert to deal", "description": "Public endpoint \u2014 creates a saved product configuration snapshot with a shareable short code, or converts an existing saved configuration to a deal (action=to_deal). Uses publishable API key auth (Bearer sb_pub_...).", "operationId": "postSavedConfig", "security": [], "parameters": [ { "name": "action", "in": "query", "description": "Action to perform. Use 'to_deal' to convert a saved configuration to a deal.", "required": false, "schema": { "type": "string", "enum": [ "to_deal" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "For creation: product_selections, pricing_snapshot, subtotal, currency. For to_deal: short_code, customer_name, customer_email.", "properties": { "product_selections": { "type": "array", "description": "Array of product selections with quantities and configured prices", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "configured_price": { "type": "number" }, "configuration": { "type": "object" } } } }, "option_selections": { "type": "object", "nullable": true, "description": "Per-product option choices keyed by product_id" }, "pricing_snapshot": { "type": "object", "description": "Pricing details at save time including discounts" }, "subtotal": { "type": "number" }, "currency": { "type": "string" }, "customer_name": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "short_code": { "type": "string", "description": "Required for to_deal action" }, "expires_in": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Expiration TTL in days (1-365, default 30). Falls back to widget default if not specified." } } } } } }, "responses": { "201": { "description": "Saved configuration created or deal created from saved configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object" } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "description": "Saved configuration has expired (to_deal only)" } } }, "patch": { "tags": [ "SavedConfigs" ], "summary": "Update a saved configuration", "description": "Public endpoint \u2014 updates mutable fields of a saved configuration (customer_name, customer_email, option_selections). Uses publishable API key auth (Bearer sb_pub_...).", "operationId": "patchSavedConfig", "security": [], "parameters": [ { "name": "id", "in": "query", "description": "Short code of the saved configuration to update", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_name": { "type": "string", "nullable": true }, "customer_email": { "type": "string", "format": "email", "nullable": true }, "option_selections": { "type": "object", "nullable": true, "description": "Per-product option choices keyed by product_id" } } } } } }, "responses": { "200": { "description": "Saved configuration updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "updated": { "type": "boolean" }, "short_code": { "type": "string" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "SavedConfigs" ], "summary": "Delete a saved configuration", "description": "Public endpoint \u2014 permanently deletes a saved configuration by its short code. Uses publishable API key auth (Bearer sb_pub_...).", "operationId": "deleteSavedConfig", "security": [], "parameters": [ { "name": "id", "in": "query", "description": "Short code of the saved configuration to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Saved configuration deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/saved-configs-admin": { "get": { "tags": [ "SavedConfigsAdmin" ], "summary": "List saved configurations, get stats, or analytics", "description": "Admin endpoint \u2014 lists all saved product configurations with search, filter, and sort. Use action=stats for aggregate statistics, action=analytics for conversion funnel analytics. Session or API key auth required.", "operationId": "getSavedConfigsAdmin", "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Saved configuration ID to retrieve a single config", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "description": "Use 'stats' for aggregate statistics or 'analytics' for conversion funnel analytics", "schema": { "type": "string", "enum": [ "stats", "analytics" ] } }, { "name": "period", "in": "query", "description": "Time period in days for analytics (7, 30, or 90). Only used with action=analytics", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } }, { "name": "search", "in": "query", "description": "Search by short code, customer name, or email", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "schema": { "type": "string", "enum": [ "active", "expired", "converted" ] } }, { "name": "sort", "in": "query", "description": "Sort order", "schema": { "type": "string", "enum": [ "newest", "oldest", "highest_value", "most_viewed" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Saved configurations list or stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean" }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object" } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "SavedConfigsAdmin" ], "summary": "Convert saved configuration to deal", "description": "Admin endpoint \u2014 converts a saved product configuration into a deal with line items and customer. Requires id and action=convert parameters.", "operationId": "postSavedConfigAdmin", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Saved configuration ID", "required": true, "schema": { "type": "integer" } }, { "name": "action", "in": "query", "description": "Must be 'convert'", "required": true, "schema": { "type": "string", "enum": [ "convert" ] } } ], "responses": { "201": { "description": "Deal created from saved configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean" }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "deal_id": { "type": "string" }, "deal": { "type": "object" }, "converted_from": { "type": "string" } } } }, "required": [ "error", "success", "data" ] } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body required. The saved config ID is specified via the `id` query parameter and `action=convert`.", "properties": {} } } } } }, "patch": { "tags": [ "SavedConfigsAdmin" ], "summary": "Update a saved configuration by numeric ID", "description": "Admin endpoint \u2014 updates customer info or option selections for a saved configuration, identified by numeric ID. Used by SDK smart routing when update() is called with a numeric ID.", "operationId": "patchSavedConfigAdmin", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Saved configuration numeric ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_name": { "type": "string" }, "customer_email": { "type": "string", "format": "email" }, "option_selections": { "type": "object", "nullable": true } } } } } }, "responses": { "200": { "description": "Configuration updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean" }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "updated": { "type": "boolean" }, "id": { "type": "integer" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "SavedConfigsAdmin" ], "summary": "Delete a saved configuration", "description": "Admin endpoint \u2014 permanently deletes a saved product configuration.", "operationId": "deleteSavedConfigAdmin", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Saved configuration ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Configuration deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/configuration": { "get": { "tags": [ "Configuration" ], "summary": "Get configuration schema with rules for a product, or list product families", "description": "Returns the full configuration schema (option groups, compatibility rules, bundle pricing rules) for a product. Also supports listing product families and retrieving family products via the action parameter.", "operationId": "getConfigurationSchema", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "product_id", "in": "query", "description": "Product ID to get schema for (required unless using action=families, action=family, or action=family_products)", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Action: families, family, or family_products", "schema": { "type": "string", "enum": [ "families", "family", "family_products" ] } }, { "name": "id", "in": "query", "description": "Family ID (for action=family or action=family_products)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Configuration" ], "summary": "Validate a configuration or calculate pricing", "description": "Validates a product configuration against compatibility and bundle rules (action=validate), or calculates the full price breakdown including base price, option modifiers, and bundle discounts (action=price).", "operationId": "configurationAction", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "product_id", "in": "query", "description": "Product ID to validate/price against", "required": true, "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Action to perform: validate or price", "required": true, "schema": { "type": "string", "enum": [ "validate", "price" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "option_ids" ], "properties": { "option_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of selected option IDs" } } } } } }, "responses": { "200": { "description": "Validation or pricing result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/tools": { "get": { "tags": [ "Agent Tools" ], "summary": "List available agent tool definitions", "description": "Returns curated tool definitions optimized for LLM function-calling. Supports OpenAI, Anthropic, and universal formats. Tools map to high-level business operations.", "operationId": "listAgentTools", "security": [ { "bearerAuth": [ "agent:discover" ] }, { "apiKeyHeader": [ "agent:discover" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "format", "in": "query", "description": "Output format: universal (default), openai, or anthropic", "schema": { "type": "string", "enum": [ "universal", "openai", "anthropic" ], "default": "universal" } }, { "name": "category", "in": "query", "description": "Filter tools by category", "schema": { "type": "string", "enum": [ "discovery", "deals", "products", "negotiation", "execution" ] } } ], "responses": { "200": { "description": "Tool definitions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "schema_version": { "type": "string", "example": "1.0" }, "format": { "type": "string" }, "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "required_scope": { "type": "string" }, "parameters": { "type": "object" }, "returns": { "type": "object" } } } }, "total": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/mcp": { "post": { "tags": [ "Agent Tools" ], "summary": "Handle MCP JSON-RPC requests", "description": "Model Context Protocol server endpoint. Accepts JSON-RPC 2.0 requests for tool listing (tools/list), tool execution (tools/call), resource browsing (resources/list, resources/read, resources/templates/list), prompt templates (prompts/list, prompts/get), resource subscriptions (resources/subscribe, resources/unsubscribe), and protocol handshake (initialize).", "operationId": "handleMcpRequest", "security": [ { "bearerAuth": [ "agent:discover" ] }, { "apiKeyHeader": [ "agent:discover" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": "string", "description": "Request ID for response correlation" }, "method": { "type": "string", "enum": [ "initialize", "tools/list", "tools/call", "resources/list", "resources/templates/list", "resources/read", "resources/subscribe", "resources/unsubscribe", "prompts/list", "prompts/get", "ping" ] }, "params": { "type": "object", "description": "Method-specific parameters" } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": "string" }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/fx-rate": { "get": { "tags": [ "FxRate" ], "summary": "Get current exchange rate between two currencies", "description": "Returns the current exchange rate between two ISO 4217 currencies. Public endpoint for widget currency conversion. Rate-limited to 100 requests/hour per IP. Responses are cacheable for 1 hour.", "operationId": "getFxRate", "security": [], "parameters": [ { "name": "from", "in": "query", "description": "Source currency code (ISO 4217, e.g. AUD)", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } }, { "name": "to", "in": "query", "description": "Target currency code (ISO 4217, e.g. JPY)", "required": true, "schema": { "type": "string", "pattern": "^[A-Z]{3}$" } } ], "responses": { "200": { "description": "Exchange rate returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "from": { "type": "string", "description": "Source currency code" }, "to": { "type": "string", "description": "Target currency code" }, "rate": { "type": "number", "description": "Exchange rate multiplier (from * rate = to)" }, "provider": { "type": "string", "description": "Rate data source (e.g. stripe, identity)" }, "fetched_at": { "type": "string", "description": "ISO 8601 timestamp when rate was fetched" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "Exchange rate temporarily unavailable" } } } }, "/ab-tests": { "get": { "tags": [ "ABTests" ], "summary": "List or retrieve A/B tests", "operationId": "getABTests", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "A/B test ID for single test retrieval with stats", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A/B test data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "oneOf": [ { "description": "List of A/B tests (no id param)", "type": "object", "properties": { "tests": { "type": "array", "items": { "type": "object", "properties": { "ab_test_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "paused", "completed" ] }, "widget_a_id": { "type": "string" }, "widget_a_title": { "type": "string", "nullable": true }, "widget_b_id": { "type": "string" }, "widget_b_title": { "type": "string", "nullable": true }, "traffic_weight_b": { "type": "integer", "minimum": 1, "maximum": 99 }, "auto_promote": { "type": "boolean" }, "winner_widget_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "ab_test_id", "name", "status", "widget_a_id", "widget_b_id", "traffic_weight_b", "auto_promote" ] } }, "count": { "type": "integer" } }, "required": [ "tests", "count" ] }, { "description": "Single A/B test with stats (when id param provided)", "allOf": [ { "type": "object", "properties": { "ab_test_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "paused", "completed" ] }, "widget_a_id": { "type": "string" }, "widget_a_title": { "type": "string", "nullable": true }, "widget_b_id": { "type": "string" }, "widget_b_title": { "type": "string", "nullable": true }, "traffic_weight_b": { "type": "integer", "minimum": 1, "maximum": 99 }, "auto_promote": { "type": "boolean" }, "winner_widget_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "ab_test_id", "name", "status", "widget_a_id", "widget_b_id", "traffic_weight_b", "auto_promote" ] }, { "type": "object", "properties": { "stats": { "type": "object", "properties": { "variant_a": { "type": "object", "properties": { "impressions": { "type": "integer" }, "conversions": { "type": "integer" }, "completions": { "type": "integer" }, "revenue": { "type": "number" }, "conversion_rate": { "type": "number" }, "avg_deal_value": { "type": "number" } } }, "variant_b": { "type": "object", "properties": { "impressions": { "type": "integer" }, "conversions": { "type": "integer" }, "completions": { "type": "integer" }, "revenue": { "type": "number" }, "conversion_rate": { "type": "number" }, "avg_deal_value": { "type": "number" } } }, "significance": { "type": "object", "properties": { "chi_squared": { "type": "number" }, "p_value": { "type": "number" }, "significant": { "type": "boolean" }, "confidence": { "type": "number" }, "min_sample_met": { "type": "boolean" }, "leader": { "type": "string", "enum": [ "A", "B" ], "nullable": true } } } }, "required": [ "variant_a", "variant_b", "significance" ] } }, "required": [ "stats" ] } ] } ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Returns a list of A/B tests for the tenant, or a single test when `id` is provided. Use A/B tests to measure the impact of pricing, copy, or configuration changes on conversion rates." }, "post": { "tags": [ "ABTests" ], "summary": "Create an A/B test", "operationId": "postABTest", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "widget_id" ], "properties": { "widget_id": { "type": "string", "description": "Source widget to create A/B test from" }, "name": { "type": "string", "description": "Test name" }, "traffic_weight_b": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Percentage of traffic to variant B (default 50)" }, "auto_promote": { "type": "boolean", "description": "Auto-promote winner at 95% significance" } } } } } }, "responses": { "201": { "description": "A/B test created", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "ab_test_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "running" ] }, "widget_a_id": { "type": "string" }, "widget_b_id": { "type": "string" }, "widget_b_api_key": { "type": "string" }, "traffic_weight_b": { "type": "integer" }, "auto_promote": { "type": "boolean" } }, "required": [ "ab_test_id", "name", "status" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Creates a new A/B test or performs an action on an existing test. Use `action=promote` to promote the winning variant, making it the new default configuration." }, "patch": { "tags": [ "ABTests" ], "summary": "Update an A/B test", "operationId": "patchABTest", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "running", "paused" ] }, "traffic_weight_b": { "type": "integer" }, "auto_promote": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "A/B test updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "updated": { "type": "boolean" } }, "required": [ "updated" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Updates an existing A/B test by ID. Modify the test name, variants, allocation split, or targeting criteria." } }, "/ab-tests/promote": { "post": { "tags": [ "ABTests" ], "summary": "Promote A/B test winner", "operationId": "postPromoteABTest", "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ab_test_id", "winner_widget_id" ], "properties": { "ab_test_id": { "type": "string" }, "winner_widget_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Winner promoted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "promoted": { "type": "boolean" }, "winner_widget_id": { "type": "string" }, "archived_widget_id": { "type": "string" } }, "required": [ "promoted", "winner_widget_id", "archived_widget_id" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Promotes the winning variant of an A/B test to become the default configuration. This action ends the test and applies the winner's settings permanently." } }, "/ab-tests/resolve": { "get": { "tags": [ "ABTests" ], "summary": "Resolve which variant to show a visitor", "operationId": "getResolveABTest", "security": [], "parameters": [ { "name": "api_key", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Variant resolution data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "oneOf": [ { "description": "Widget is not part of a running A/B test", "type": "object", "properties": { "variant": { "type": "null" }, "api_key": { "type": "string" } }, "required": [ "variant", "api_key" ] }, { "description": "Active A/B test variant data", "type": "object", "properties": { "ab_test_id": { "type": "string" }, "api_key_a": { "type": "string" }, "api_key_b": { "type": "string" }, "weight_b": { "type": "integer", "minimum": 1, "maximum": 99 }, "widget_a_id": { "type": "string" }, "widget_b_id": { "type": "string" } }, "required": [ "ab_test_id", "api_key_a", "api_key_b", "weight_b", "widget_a_id", "widget_b_id" ] } ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Resolves the active variant for a given widget or session context. Used by the widget SDK to determine which variant to display for a specific visitor." } }, "/widget-config": { "get": { "tags": [ "WidgetConfig" ], "summary": "List or retrieve widget configurations", "description": "List all widgets for the tenant, or retrieve a specific widget by ID. Public access via api_key parameter returns limited config for embedded widgets.", "operationId": "getWidgetConfig", "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Widget ID to retrieve a specific widget", "required": false, "schema": { "type": "string" } }, { "name": "api_key", "in": "query", "description": "Publishable API key (sb_pub_*) for public widget config access. No auth required when using this parameter.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Widget config(s) returned successfully. Response shape depends on auth method and parameters:\n- Authenticated + no id: returns list with widgets array, count, and available_sites\n- Authenticated + ?id=: returns a single flat widget config object\n- Public access (?api_key=): returns limited config with merchant_available and Stripe key for widget embedding", "content": { "application/json": { "schema": { "type": "object", "description": "Successful response. Shape varies by auth method and parameters: authenticated list (no ?id=) returns data.widgets array + data.count + data.available_sites (items are WidgetConfigItem); authenticated single (?id=) returns data as WidgetConfigSingle; public (?api_key=) returns data as WidgetConfigPublic.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "description": "Response data. Shape depends on auth method and parameters: public access (?api_key=) returns WidgetConfigPublic; authenticated single (?id=) returns WidgetConfigSingle; authenticated list (no ?id=) returns widgets[], count, and available_sites[].", "properties": { "booking_config": { "type": "object", "nullable": true, "description": "Widget-level booking step configuration (enable_booking, staff_ids, duration, availability_source, custom_hours, buffer_time, max_advance_days, confirmation)" }, "deal_template_id": { "type": "string", "nullable": true, "description": "Deal template ID used to pre-populate the widget with template products and pricing" }, "deal_template": { "type": "object", "nullable": true, "description": "Deal template data for pre-populating the widget. Included when deal_template_id is set and template is active.", "properties": { "name": { "type": "string", "description": "Template name, used as widget title fallback" }, "template_data": { "type": "object", "description": "Template configuration including line_items, discounts, terms, and metadata" } } } }, "oneOf": [ { "$ref": "#/components/schemas/WidgetConfigPublic" }, { "$ref": "#/components/schemas/WidgetConfigSingle" }, { "type": "object", "description": "Authenticated list response \u2014 returns all widgets for the tenant", "properties": { "widgets": { "type": "array", "items": { "$ref": "#/components/schemas/WidgetConfigItem" } }, "count": { "type": "integer", "description": "Total number of widget configurations for the tenant" }, "available_sites": { "type": "array", "description": "Sites available to assign to widgets", "items": { "type": "object", "properties": { "site_id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string", "description": "Site domain name" } } } } } } ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "WidgetConfig" ], "summary": "Create a widget configuration", "description": "Creates a new widget config tied to a site. Auto-generates a publishable API key (sb_pub_*) for the widget.", "operationId": "postWidgetConfig", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "site_id" ], "properties": { "site_id": { "type": "string" }, "title": { "type": "string" }, "theme_color": { "type": "string" }, "currency": { "type": "string" }, "display_currencies": { "type": "array", "items": { "type": "string" }, "description": "ISO 4217 currency codes available for buyer display conversion" }, "products": { "type": "string" }, "cta_text": { "type": "string" }, "step_1_name": { "type": "string", "description": "Custom label for Products step" }, "step_2_name": { "type": "string", "description": "Custom label for Configure step" }, "step_3_name": { "type": "string", "description": "Custom label for Summary step" }, "step_4_name": { "type": "string", "description": "Custom label for Negotiate step (8-step flow)" }, "step_5_name": { "type": "string", "description": "Custom label for Customer/Details step (8-step flow)" }, "step_6_name": { "type": "string", "description": "Custom label for Terms step (8-step flow)" }, "step_7_name": { "type": "string", "description": "Custom label for Payment step (8-step flow)" }, "step_8_name": { "type": "string", "description": "Custom label for Confirmation step (8-step flow)" }, "enable_promo_codes": { "type": "boolean" }, "enable_discount_step": { "type": "boolean", "description": "Enable a dedicated discount step in the widget flow" }, "auto_discounts": { "type": "object", "nullable": true }, "contract_template_id": { "type": "string", "nullable": true }, "deal_template_id": { "type": "string", "nullable": true }, "enable_negotiation": { "type": "boolean" }, "negotiation_mode": { "type": "string", "enum": [ "price_only", "item_selection", "terms_only", "full" ] }, "auto_accept_threshold": { "type": "number", "nullable": true }, "locale": { "type": "string", "nullable": true, "description": "Widget UI language code (e.g. en, en-AU, es, de, fr, ja)" }, "locale_overrides": { "type": "object", "nullable": true, "description": "Custom string overrides for widget i18n labels (dot-separated keys)" }, "show_social_proof": { "type": "boolean", "description": "Show social proof indicators (e.g. purchase counts) in the widget (default: true)" }, "show_smart_defaults": { "type": "boolean", "description": "Pre-select smart default options based on popular choices (default: true)" }, "social_proof_threshold": { "type": "integer", "description": "Minimum purchase count before social proof is displayed (1-100, default: 5)" }, "show_stock_quantity": { "type": "boolean", "description": "Display remaining stock quantity next to products" }, "saved_config_ttl_days": { "type": "integer", "description": "Days a buyer's saved configuration is retained (1-365, default: 30)" }, "payment_type": { "type": "string", "enum": [ "full", "deposit", "quote" ], "description": "Payment collection mode" }, "deposit_type": { "type": "string", "enum": [ "fixed", "percentage" ], "nullable": true, "description": "Deposit calculation method" }, "deposit_value": { "type": "number", "nullable": true, "description": "Deposit amount (fixed) or percentage (0-100)" }, "deposit_note": { "type": "string", "nullable": true, "description": "Note about remaining balance shown to buyer" }, "logo_url": { "type": "string", "nullable": true, "description": "Merchant logo URL displayed in widget header (internal upload path)" }, "font_family": { "type": "string", "nullable": true, "description": "Font family name (web-safe or Google Font)" }, "custom_css": { "type": "string", "nullable": true, "description": "Custom CSS injected into widget Shadow DOM (sanitised server-side)" }, "dark_mode": { "type": "boolean", "description": "Enable dark colour scheme for the widget" }, "border_radius": { "type": "integer", "nullable": true, "description": "Border radius in pixels (0-16, default 12)" }, "button_style": { "type": "string", "enum": [ "filled", "outlined", "text" ], "description": "CTA button rendering style" }, "product_selection_mode": { "type": "string", "enum": [ "single", "multiple" ], "description": "Whether buyers can select one or multiple products (default: single)" }, "analytics_mode": { "type": "string", "nullable": true, "description": "Comma-separated analytics targets (gtm, ga4, segment, callback)" }, "analytics_callback": { "type": "string", "nullable": true, "description": "Global JS function name for custom analytics callback" }, "analytics_consent": { "type": "boolean", "description": "Whether analytics requires user consent before firing (GDPR)" }, "booking_config": { "type": "object", "nullable": true, "description": "Widget-level booking step configuration (enable_booking, staff_ids, duration, availability_source, custom_hours, buffer_time, max_advance_days, confirmation)" }, "network_config": { "type": "object", "nullable": true, "description": "Network and cache tuning (retry_attempts, timeout_ms, cache_ttl_seconds)" }, "signature_mode": { "type": "string", "enum": [ "checkbox", "type", "draw", "digital" ], "description": "Contract signature capture method (default: checkbox)" }, "step_order": { "type": "string", "description": "Custom step ordering: comma-separated step names (e.g. products,summary,customer,payment,confirmation)" }, "skip_steps": { "type": "string", "description": "Steps to skip from default flow: comma-separated step names (payment and confirmation cannot be skipped)" }, "step_conditions": { "type": "object", "description": "Conditional step visibility rules: JSON object mapping step names to conditions", "additionalProperties": { "type": "object", "properties": { "minTotal": { "type": "number" }, "maxTotal": { "type": "number" }, "dealType": { "type": "string" } } } } } } } } }, "responses": { "201": { "description": "Widget created successfully. Returns the full widget config including the auto-generated publishable API key (api_key) that must be used to embed the widget.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "allOf": [ { "$ref": "#/components/schemas/WidgetConfigSingle" }, { "type": "object", "description": "create-only fields", "properties": { "created_at": { "type": "string", "description": "ISO 8601 datetime when the widget was created" } } } ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "WidgetConfig" ], "summary": "Update a widget configuration", "description": "Partially updates a widget config. Only provided fields are changed.", "operationId": "patchWidgetConfig", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "theme_color": { "type": "string" }, "currency": { "type": "string" }, "products": { "type": "string" }, "cta_text": { "type": "string" }, "step_1_name": { "type": "string" }, "step_2_name": { "type": "string" }, "step_3_name": { "type": "string" }, "step_4_name": { "type": "string" }, "step_5_name": { "type": "string" }, "step_6_name": { "type": "string" }, "step_7_name": { "type": "string" }, "step_8_name": { "type": "string" }, "enable_promo_codes": { "type": "boolean" }, "enable_discount_step": { "type": "boolean", "description": "Enable a dedicated discount step in the widget flow" }, "auto_discounts": { "type": "object", "nullable": true }, "contract_template_id": { "type": "string", "nullable": true }, "deal_template_id": { "type": "string", "nullable": true }, "enable_negotiation": { "type": "boolean" }, "negotiation_mode": { "type": "string", "enum": [ "price_only", "item_selection", "terms_only", "full" ] }, "auto_accept_threshold": { "type": "number", "nullable": true }, "locale": { "type": "string", "nullable": true, "description": "Widget UI language code (e.g. en, en-AU, es, de, fr, ja)" }, "locale_overrides": { "type": "object", "nullable": true, "description": "Custom string overrides for widget i18n labels (dot-separated keys)" }, "show_social_proof": { "type": "boolean", "description": "Show social proof indicators (e.g. purchase counts) in the widget (default: true)" }, "show_smart_defaults": { "type": "boolean", "description": "Pre-select smart default options based on popular choices (default: true)" }, "social_proof_threshold": { "type": "integer", "description": "Minimum purchase count before social proof is displayed (1-100, default: 5)" }, "show_stock_quantity": { "type": "boolean", "description": "Display remaining stock quantity next to products" }, "saved_config_ttl_days": { "type": "integer", "description": "Days a buyer's saved configuration is retained (1-365, default: 30)" }, "payment_type": { "type": "string", "enum": [ "full", "deposit", "quote" ], "description": "Payment collection mode" }, "deposit_type": { "type": "string", "enum": [ "fixed", "percentage" ], "nullable": true, "description": "Deposit calculation method" }, "deposit_value": { "type": "number", "nullable": true, "description": "Deposit amount (fixed) or percentage (0-100)" }, "deposit_note": { "type": "string", "nullable": true, "description": "Note about remaining balance shown to buyer" }, "logo_url": { "type": "string", "nullable": true, "description": "Merchant logo URL displayed in widget header" }, "font_family": { "type": "string", "nullable": true, "description": "Font family name (web-safe or Google Font)" }, "custom_css": { "type": "string", "nullable": true, "description": "Custom CSS injected into widget Shadow DOM (sanitised)" }, "dark_mode": { "type": "boolean", "description": "Enable dark colour scheme" }, "border_radius": { "type": "integer", "nullable": true, "description": "Border radius in pixels (0-16)" }, "button_style": { "type": "string", "enum": [ "filled", "outlined", "text" ], "description": "CTA button rendering style" }, "product_selection_mode": { "type": "string", "enum": [ "single", "multiple" ], "description": "Whether buyers can select one or multiple products (default: single)" }, "analytics_mode": { "type": "string", "nullable": true, "description": "Comma-separated analytics targets (gtm, ga4, segment, callback)" }, "analytics_callback": { "type": "string", "nullable": true, "description": "Global JS function name for custom analytics callback" }, "analytics_consent": { "type": "boolean", "description": "Whether analytics requires user consent before firing (GDPR)" }, "booking_config": { "type": "object", "nullable": true, "description": "Widget-level booking step configuration (enable_booking, staff_ids, duration, availability_source, custom_hours, buffer_time, max_advance_days, confirmation)" }, "network_config": { "type": "object", "nullable": true, "description": "Network and cache tuning (retry_attempts, timeout_ms, cache_ttl_seconds)" }, "signature_mode": { "type": "string", "enum": [ "checkbox", "type", "draw", "digital" ], "description": "Contract signature capture method (default: checkbox)" }, "step_order": { "type": "string", "description": "Custom step ordering: comma-separated step names (e.g. products,summary,customer,payment,confirmation)" }, "skip_steps": { "type": "string", "description": "Steps to skip from default flow: comma-separated step names (payment and confirmation cannot be skipped)" }, "step_conditions": { "type": "object", "description": "Conditional step visibility rules: JSON object mapping step names to conditions", "additionalProperties": { "type": "object", "properties": { "minTotal": { "type": "number" }, "maxTotal": { "type": "number" }, "dealType": { "type": "string" } } } } } } } } }, "responses": { "200": { "description": "Widget updated successfully. Returns the full updated widget config fields (excluding site info and api_key, which do not change on update).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/WidgetConfigUpdateResponse" } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "WidgetConfig" ], "summary": "Delete a widget configuration", "description": "Deletes a widget config and revokes its publishable API key.", "operationId": "deleteWidgetConfig", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Widget deleted successfully" }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/widget-config/auto-configure": { "post": { "tags": [ "WidgetConfig" ], "summary": "Auto-configure widget from product IDs", "description": "Analyses selected products' configuration schemas, types, categories, and pricing models to generate optimal widget title, CTA text, and step names. Does NOT save \u2014 returns suggestions for the form to pre-fill. Actual endpoint is POST /widget-config?action=auto-configure.", "operationId": "postAutoConfigureWidget", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_ids" ], "properties": { "product_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of product_id strings to analyse" } } } } } }, "responses": { "200": { "description": "Auto-configuration suggestions returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "title": { "type": "string", "description": "Suggested widget title" }, "cta_text": { "type": "string", "description": "Suggested CTA button text" }, "step_1_name": { "type": "string", "description": "Suggested Products step label" }, "step_2_name": { "type": "string", "description": "Suggested Configure step label" }, "step_3_name": { "type": "string", "description": "Suggested Summary step label" }, "step_4_name": { "type": "string", "description": "Suggested Negotiate step label" }, "step_5_name": { "type": "string", "description": "Suggested Customer/Details step label" }, "step_6_name": { "type": "string", "description": "Suggested Terms step label" }, "step_7_name": { "type": "string", "description": "Suggested Payment step label" }, "step_8_name": { "type": "string", "description": "Suggested Confirmation step label" }, "payment_type": { "type": "string", "enum": [ "full", "deposit", "quote" ], "description": "Suggested payment type based on product pricing" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/widget-config/from-template": { "post": { "tags": [ "WidgetConfig" ], "summary": "Generate pre-filled widget config from a deal template", "description": "Reads a deal template's product list and configuration, runs auto-configure logic, and returns a pre-filled widget config object. Does NOT save \u2014 returns suggestions for the widget form to pre-fill. Actual endpoint is POST /widget-config?action=from-template.", "operationId": "postWidgetConfigFromTemplate", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template_id" ], "properties": { "template_id": { "type": "string", "description": "Deal template ID (dtpl_*) to generate widget config from" } } } } } }, "responses": { "200": { "description": "Pre-filled widget config returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "title": { "type": "string", "description": "Suggested widget title (from template name)" }, "cta_text": { "type": "string", "description": "Suggested CTA button text" }, "products": { "type": "string", "description": "Comma-separated product IDs from template line items" }, "currency": { "type": "string", "description": "Currency from template data" }, "deal_template_id": { "type": "string", "description": "Source template ID for bidirectional linking" }, "template_name": { "type": "string", "description": "Template name for display" }, "step_1_name": { "type": "string" }, "step_2_name": { "type": "string" }, "step_3_name": { "type": "string" }, "step_4_name": { "type": "string" }, "step_5_name": { "type": "string" }, "step_6_name": { "type": "string" }, "step_7_name": { "type": "string" }, "step_8_name": { "type": "string" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/widget-config/embed-code": { "get": { "tags": [ "WidgetConfig" ], "summary": "Get ready-to-paste embed HTML with SRI integrity attributes", "description": "Returns a complete HTML embed snippet for a widget, including the script tag with Subresource Integrity (SRI) hash and crossorigin attributes, plus the salesbooth-deal custom element. Actual endpoint is GET /widget-config?id={id}&action=embed-code.", "operationId": "getWidgetEmbedCode", "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Widget ID to generate embed code for", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Embed code returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "html": { "type": "string", "description": "Complete HTML embed snippet with SRI" }, "integrity": { "type": "string", "description": "SRI hash (sha384-...) for the SDK bundle" }, "sdk_url": { "type": "string", "description": "Full URL to the SDK bundle script" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/intelligence": { "get": { "tags": [ "Intelligence" ], "summary": "Get deal intelligence data", "description": "Returns deal scoring, pricing intelligence, pipeline analytics, outcome analytics, score history, win probability calibration, risk assessment, close-date forecast, pipeline revenue forecast, AI suggestion analytics, pipeline stage deal listings with scores, bulk pricing suggestions for active deals, and AI-generated counter-term suggestions. Use the `type` query parameter to select the data type. API key authentication is supported: most types require the `deals:read` scope; `type=config` requires the `intelligence:read` scope.", "operationId": "getIntelligence", "security": [ { "bearerAuth": [ "deals:read" ] }, { "bearerAuth": [ "intelligence:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "apiKeyHeader": [ "intelligence:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "type", "in": "query", "description": "Type of intelligence data: pricing, pipeline, score, pricing_suggestion, outcome_analytics, score_accuracy, loss_patterns, score_history, win_probability_curve, risk, close_forecast, pipeline_forecast, config, suggestion_analytics, pipeline_deals, pricing_suggestions_bulk, or counter_terms", "required": true, "schema": { "type": "string", "enum": [ "pricing", "pipeline", "score", "pricing_suggestion", "outcome_analytics", "score_accuracy", "loss_patterns", "score_history", "win_probability_curve", "risk", "close_forecast", "pipeline_forecast", "config", "suggestion_analytics", "pipeline_deals", "pricing_suggestions_bulk", "counter_terms" ] } }, { "name": "deal_id", "in": "query", "description": "Deal ID (required for type=score, score_history, pricing_suggestion, risk, close_forecast, counter_terms)", "required": false, "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Forecast period filter (for type=pipeline_forecast). Values: 30, 60, 90, or all", "required": false, "schema": { "type": "string", "default": "all" } }, { "name": "days", "in": "query", "description": "Lookback window in days for type=suggestion_analytics (default: 90, min: 7, max: 365)", "required": false, "schema": { "type": "integer", "default": 90, "minimum": 7, "maximum": 365 } }, { "name": "stage", "in": "query", "description": "Pipeline stage to filter deals by (required for type=pipeline_deals). One of: draft, in_progress, pending_payment, pending_signature, awaiting_signatures, closed, cancelled, expired", "required": false, "schema": { "type": "string", "enum": [ "draft", "in_progress", "pending_payment", "pending_signature", "awaiting_signatures", "closed", "cancelled", "expired" ] } }, { "name": "current_terms", "in": "query", "description": "JSON-encoded object of current deal terms to factor into counter-term suggestions (optional for type=counter_terms)", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of score history entries to return (for type=score_history). Range: 1-100, default: 20", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Intelligence data returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "description": "Response shape varies by type parameter. For type=score: includes score, factors, win_probability, recommendation, explanation. For type=risk: includes risk_level, risk_score, risk_factors, recommended_actions. For type=close_forecast: includes optimistic, expected, pessimistic dates with confidence. For type=pipeline_forecast: includes windows (30/60/90 day weighted pipeline values), deals, trend. For type=pipeline_deals: includes stage, deals array (deal_id, title, total, status, customer_name, score, win_probability, days_since_update), count. For type=pricing_suggestions_bulk: includes suggestions array (deal_id, title, product_name, current_discount, suggested_discount, win_probability, probability_lift, reason), count. For type=counter_terms: includes AI-suggested counter terms for the specified deal negotiation." } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "patch": { "tags": [ "Intelligence" ], "summary": "Update scoring configuration", "description": "Updates tenant-specific deal scoring weights and thresholds.", "operationId": "updateScoringConfig", "parameters": [ { "name": "type", "in": "query", "description": "Must be 'config'", "required": true, "schema": { "type": "string", "enum": [ "config" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "weights": { "type": "object", "description": "Scoring factor weights (must sum to 100)" }, "thresholds": { "type": "object", "description": "Factor thresholds" } } } } } }, "responses": { "200": { "description": "Configuration updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "bearerAuth": [ "intelligence:write" ] }, { "apiKeyHeader": [ "intelligence:write" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Intelligence" ], "summary": "Backtest scoring configuration", "description": "Tests proposed scoring weights against recent deals, returning per-deal score changes with factor breakdowns and win probability.", "operationId": "backtestScoring", "parameters": [ { "name": "type", "in": "query", "description": "Must be 'backtest'", "required": true, "schema": { "type": "string", "enum": [ "backtest" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "weights": { "type": "object", "description": "Proposed scoring weights to backtest" } }, "required": [ "weights" ] } } } }, "responses": { "200": { "description": "Backtest results with per-deal factor breakdowns", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [ { "bearerAuth": [ "intelligence:write" ] }, { "apiKeyHeader": [ "intelligence:write" ] }, { "sessionAuth": [] } ] } }, "/widget-intelligence": { "get": { "tags": [ "WidgetIntelligence" ], "summary": "Get aggregated intelligence data for widget rendering", "description": "Returns privacy-safe aggregated intelligence metadata for the widget: product popularity badges, most-chosen option defaults, and price context for anchoring. Authenticated via publishable API key (sb_pub_*). Data is cached with 15-minute TTL.", "operationId": "getWidgetIntelligence", "security": [], "parameters": [ { "name": "api_key", "in": "query", "description": "Publishable API key (sb_pub_*) identifying the widget", "required": true, "schema": { "type": "string" } }, { "name": "products", "in": "query", "description": "Comma-separated product IDs to get intelligence for (defaults to widget's configured products)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Intelligence data returned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "products": { "type": "object", "description": "Product popularity data keyed by product_id", "additionalProperties": { "type": "object", "properties": { "closed_deal_count": { "type": "integer" }, "rank": { "type": "integer" }, "badge": { "type": "string", "nullable": true, "enum": [ "most_popular", "best_seller", null ] } } } }, "option_defaults": { "type": "object", "description": "Most-chosen option values per product, keyed by product_id then option key" }, "price_context": { "type": "object", "nullable": true, "description": "Aggregate price data for price anchoring on summary step", "properties": { "avg_deal_value": { "type": "number" }, "min_deal_value": { "type": "number" }, "max_deal_value": { "type": "number" }, "stddev": { "type": "number" }, "deal_count": { "type": "integer" } } }, "score_context": { "type": "object", "nullable": true, "description": "Win probability calibration data for scoring context", "properties": { "win_probability_calibrated": { "type": "boolean" }, "sample_size": { "type": "integer" }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "score_range": { "type": "string" }, "midpoint": { "type": "integer" }, "win_probability": { "type": "number" }, "sample_size": { "type": "integer" } } } } } }, "thresholds": { "type": "object", "properties": { "min_deals_for_badges": { "type": "integer" }, "min_default_selection_rate": { "type": "integer" } } } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/credits": { "get": { "tags": [ "Credits" ], "summary": "Get credit balance, ledger history, or MCP summary", "description": "Returns the current prepaid credit balance for the authenticated tenant. Use `?action=ledger` to get paginated transaction history. Use `?action=summary` to get an MCP-friendly summary including trust level, auto top-up status, and estimated remaining deals.", "operationId": "getCredits", "security": [ { "bearerAuth": [ "billing:read" ] }, { "apiKeyHeader": [ "billing:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "ledger", "summary" ] }, "description": "Use 'ledger' to get paginated transaction history; use 'summary' to get an MCP-friendly summary with trust level, auto top-up status, and estimated capacity" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 }, "description": "Number of ledger entries per page (ledger action only)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Offset for pagination (ledger action only)" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "credit", "debit" ] }, "description": "Filter ledger by entry type (ledger action only)" } ], "responses": { "200": { "description": "Credit balance, ledger, or summary returned. Response shape varies by `?action` parameter.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "description": "Response shape varies by ?action. Default (no action) returns balance fields. action=ledger returns ledger array. action=summary returns MCP-friendly summary.", "properties": { "balance": { "type": "number", "description": "Current credit balance (default and ledger actions)" }, "low_balance_threshold": { "type": "number", "description": "Warning threshold (default action only)" }, "is_low": { "type": "boolean", "description": "Whether balance is at or below threshold (default action only)" }, "can_create_deals": { "type": "boolean", "description": "Whether balance is sufficient for deal creation (default and summary actions)" }, "cost_per_deal": { "type": "number", "description": "Credit cost per deal (default and summary actions)" }, "ledger": { "type": "array", "description": "Paginated ledger entries (ledger action only)", "items": { "type": "object" } }, "credit_balance": { "type": "number", "description": "Current credit balance (summary action)" }, "trust_level": { "type": "string", "description": "Trust level identifier (summary action)" }, "trust_level_label": { "type": "string", "description": "Human-readable trust level label (summary action)" }, "auto_topup_enabled": { "type": "boolean", "description": "Whether automatic top-up is enabled (summary action)" }, "auto_topup_ceiling": { "type": "number", "description": "Maximum balance ceiling for auto top-up (summary action)" }, "estimated_remaining_deals": { "type": "integer", "description": "Estimated number of deals that can be created with current balance (summary action)" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Credits" ], "summary": "Top up credits or estimate deal cost", "description": "Create a Stripe Checkout session for credit top-up (`?action=topup`), estimate deal cost (`?action=estimate`), or set the low-balance warning threshold (`?action=set-threshold`).", "operationId": "postCredits", "security": [ { "bearerAuth": [ "billing:write" ] }, { "apiKeyHeader": [ "billing:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "topup", "estimate", "set-threshold" ] }, "description": "Action to perform" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "minimum": 5, "maximum": 10000, "description": "Top-up amount in USD (topup action, required)" }, "success_url": { "type": "string", "format": "uri", "description": "Redirect URL after successful payment (topup action)" }, "cancel_url": { "type": "string", "format": "uri", "description": "Redirect URL if payment is cancelled (topup action)" }, "threshold": { "type": "number", "minimum": 0, "description": "Low-balance warning threshold (set-threshold action)" } } } } } }, "responses": { "200": { "description": "Action completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "checkout_url": { "type": "string", "format": "uri", "description": "Stripe Checkout URL (topup)" }, "session_id": { "type": "string", "description": "Stripe session ID (topup)" }, "amount": { "type": "number", "description": "Top-up amount (topup)" }, "cost": { "type": "number", "description": "Estimated deal cost (estimate)" }, "current_balance": { "type": "number", "description": "Current balance (estimate)" }, "sufficient": { "type": "boolean", "description": "Whether balance covers cost (estimate)" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Insufficient credit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": true }, "code": { "type": "string", "example": "billing.insufficient_credit" }, "category": { "type": "string", "example": "billing" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "current_balance": { "type": "number" }, "required_amount": { "type": "number" }, "shortfall": { "type": "number" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/billing": { "get": { "tags": [ "Billing" ], "summary": "Get billing dashboard data, ledger, or usage", "description": "Returns aggregated billing dashboard data including credit balance, trust level, auto top-up config, recent transactions, usage summary, and alert settings. Use `?action=ledger` for paginated ledger, `?action=usage-daily` for chart data, `?action=export-ledger` for CSV export, `?action=invoices` for paginated invoice list, `?action=invoice-pdf&id={id}` to download an invoice, or `?action=auto-topup-log` for auto top-up audit log.", "operationId": "getBilling", "security": [ { "bearerAuth": [ "billing:read" ] }, { "apiKeyHeader": [ "billing:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "ledger", "usage-daily", "export-ledger", "invoices", "invoice-pdf", "auto-topup-log" ] }, "description": "Sub-action: ledger, usage-daily, export-ledger, invoices, or invoice-pdf" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 }, "description": "Number of ledger entries to return (ledger action only)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Offset for pagination (ledger action only)" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "credit", "debit" ] }, "description": "Filter by transaction type (ledger/export action)" }, { "name": "days", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 365 }, "description": "Number of days for daily usage chart (usage-daily action)" }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Invoice ID for invoice-pdf action" } ], "responses": { "200": { "description": "Billing dashboard data, ledger, invoices, or invoice PDF", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "description": "Response shape varies by ?action parameter. Default (no action) returns the full billing dashboard with 6 top-level keys. Other actions return ledger entries, usage data, CSV export, invoice list, or auto top-up log.", "properties": { "balance": { "type": "object", "description": "Credit balance information (default dashboard only). Note: the ?action=ledger response also appends a top-level `balance` number field with the current balance.", "properties": { "current": { "type": "number", "description": "Current credit balance in dollars" }, "status": { "type": "string", "enum": [ "healthy", "low", "critical" ], "description": "Balance health status colour code" }, "low_balance_threshold": { "type": "number", "description": "Dollar threshold below which balance is considered low" }, "is_low": { "type": "boolean", "description": "Whether the current balance is at or below the low threshold" }, "can_create_deals": { "type": "boolean", "description": "Whether the balance covers the cost of creating a new deal" }, "cost_per_deal": { "type": "number", "description": "Credit cost deducted per deal created", "example": 1 }, "estimated_runway_days": { "type": [ "integer", "null" ], "description": "Estimated days of credits remaining based on 30-day usage rate; null if no recent usage" } } }, "trust": { "type": "object", "description": "Tenant trust level status (default dashboard only)", "properties": { "trust_level": { "type": "integer", "minimum": 0, "maximum": 5, "description": "Trust level: 0=New, 1=Verified, 2=Established, 3=Trusted, 4=Premium, 5=Enterprise" }, "trust_label": { "type": "string", "description": "Human-readable trust level label" }, "trust_score": { "type": "integer", "description": "Numeric trust score accumulator" }, "trust_level_changed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last trust level change" }, "ceiling": { "type": [ "number", "null" ], "description": "Monthly auto top-up ceiling in dollars for the current trust level; null for Enterprise unlimited" }, "auto_topup": { "type": "object", "description": "Auto top-up state derived from trust level", "properties": { "enabled": { "type": "boolean" }, "amount": { "type": [ "number", "null" ], "description": "Configured top-up amount per trigger" }, "ceiling": { "type": [ "number", "null" ], "description": "Monthly spending ceiling" }, "monthly_used": { "type": "number", "description": "Total auto top-ups charged this calendar month" }, "monthly_remaining": { "type": [ "number", "null" ], "description": "Remaining monthly allowance; null if unlimited" } } }, "progress": { "type": "object", "description": "Progress toward the next trust level", "properties": { "next_level": { "type": [ "integer", "null" ], "description": "Next trust level number; null at maximum level (5)" }, "next_label": { "type": "string", "description": "Label for the next trust level" }, "next_ceiling": { "type": [ "number", "null" ], "description": "Auto top-up ceiling at the next trust level" }, "requirements": { "type": "object", "description": "Promotion requirements and current progress toward each", "properties": { "score": { "type": "object", "properties": { "current": { "type": "integer" }, "required": { "type": "integer" }, "met": { "type": "boolean" } } }, "days_active": { "type": "object", "properties": { "current": { "type": "integer" }, "required": { "type": "integer" }, "met": { "type": "boolean" } } }, "deals_closed": { "type": "object", "properties": { "current": { "type": "integer" }, "required": { "type": "integer" }, "met": { "type": "boolean" } } }, "max_disputes": { "type": "object", "properties": { "required": { "type": "integer" } } } } }, "tips": { "type": "array", "description": "Actionable tips for advancing to the next trust level", "items": { "type": "string" } }, "message": { "type": "string", "description": "Present when at maximum level or manual approval is required" } } } } }, "auto_topup": { "type": "object", "description": "Auto top-up configuration for the tenant (default dashboard only)", "properties": { "enabled": { "type": "boolean", "description": "Whether auto top-up is currently active" }, "amount": { "type": [ "number", "null" ], "description": "Dollar amount to charge each time the balance falls below threshold" }, "has_payment_method": { "type": "boolean", "description": "Whether a saved payment method is on file" }, "payment_method_last4": { "type": [ "string", "null" ], "description": "Last 4 characters of the saved payment method ID" }, "last_charged_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last automatic top-up charge" }, "monthly_used": { "type": "number", "description": "Total auto top-up charges made this calendar month in dollars" } } }, "recent_transactions": { "type": "array", "description": "10 most recent credit ledger entries (default dashboard only)", "items": { "type": "object", "properties": { "credit_id": { "type": "string", "description": "Unique ledger entry ID" }, "type": { "type": "string", "enum": [ "credit", "debit" ], "description": "Whether this entry added or deducted credits" }, "amount": { "type": "number", "description": "Transaction amount in dollars" }, "balance_after": { "type": "number", "description": "Credit balance immediately after this transaction" }, "description": { "type": "string", "description": "Human-readable description of the transaction" }, "reference_type": { "type": [ "string", "null" ], "description": "Entity type linked to this transaction (e.g. deal, stripe_checkout)" }, "reference_id": { "type": [ "string", "null" ], "description": "Entity ID linked to this transaction" }, "created_at": { "type": "string", "format": "date-time" } } } }, "usage_summary": { "type": "object", "description": "Monthly usage summary aggregated by service (default dashboard only)", "properties": { "period": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer" } } }, "by_service": { "type": "object", "description": "Per-service breakdown keyed by service name (sms, voice, email, ai_chat, ai_voice, ai_realtime, api, ui)", "additionalProperties": { "type": "object", "properties": { "requests": { "type": "integer" }, "inbound": { "type": "integer" }, "outbound": { "type": "integer" }, "tokens_input": { "type": "integer" }, "tokens_output": { "type": "integer" }, "tokens_total": { "type": "integer" }, "messages": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "cost_cents": { "type": "integer" } } } }, "totals": { "type": "object", "description": "Aggregate totals across all services", "properties": { "requests": { "type": "integer" }, "tokens_input": { "type": "integer" }, "tokens_output": { "type": "integer" }, "tokens_total": { "type": "integer" }, "messages": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "cost_cents": { "type": "integer" } } } } }, "alert_settings": { "type": "object", "description": "Low-balance alert notification settings (default dashboard only)", "properties": { "email_enabled": { "type": "boolean", "description": "Send email notification when balance falls below threshold" }, "webhook_enabled": { "type": "boolean", "description": "Send webhook event when balance falls below threshold" }, "threshold": { "type": "number", "description": "Dollar threshold that triggers low-balance alert notifications" } } }, "entries": { "type": "array", "description": "Paginated ledger entries (?action=ledger) or auto top-up log entries (?action=auto-topup-log)", "items": { "type": "object" } }, "total": { "type": "integer", "description": "Total record count for paginated responses (?action=ledger, export-ledger, invoices, auto-topup-log)" }, "has_more": { "type": "boolean", "description": "Whether additional records exist beyond the current page (?action=ledger, auto-topup-log)" }, "daily": { "type": "array", "description": "Daily usage data rows for charting (?action=usage-daily)", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "service": { "type": "string" }, "requests": { "type": "integer" }, "tokens_input": { "type": "integer" }, "tokens_output": { "type": "integer" }, "messages": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "cost_cents": { "type": "integer" } } } }, "days": { "type": "integer", "description": "Number of days in the usage-daily response window (?action=usage-daily)" }, "service": { "type": [ "string", "null" ], "description": "Service filter applied to usage-daily response (?action=usage-daily)" }, "csv": { "type": "string", "description": "CSV-formatted ledger data (?action=export-ledger)" }, "filename": { "type": "string", "description": "Suggested download filename for CSV export (?action=export-ledger)" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Billing" ], "summary": "Update auto top-up, alert settings, or create top-up", "description": "Use `?action=topup` to create a Stripe Checkout session, `?action=auto-topup` to configure auto top-up (requires payment_method_id when enabling), `?action=setup-intent` to create a Stripe Setup Intent for saving a payment method, or `?action=alert-settings` to update low-balance alert preferences.", "operationId": "postBilling", "security": [ { "bearerAuth": [ "billing:write" ] }, { "apiKeyHeader": [ "billing:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "topup", "auto-topup", "setup-intent", "alert-settings" ] }, "description": "Action to perform" } ], "requestBody": { "description": "Request body varies by action. Each action requires different fields \u2014 see the per-action schemas.", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BillingTopupRequest" }, { "$ref": "#/components/schemas/BillingAutoTopupRequest" }, { "$ref": "#/components/schemas/BillingSetupIntentRequest" }, { "$ref": "#/components/schemas/BillingAlertSettingsRequest" } ] } } } }, "responses": { "200": { "description": "Action result", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object" } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/team": { "get": { "tags": [ "Team" ], "summary": "List team members", "description": "Returns all team members and pending invitations for the current tenant.", "operationId": "getTeamMembers", "responses": { "200": { "description": "Team members retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } }, "total": { "type": "integer" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "team:read" ] }, { "apiKeyHeader": [ "team:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Team" ], "summary": "Invite a team member or resend an invitation", "description": "Without an `action` query parameter, invites a new user to the current tenant by email and role. With `?action=resend`, re-sends a pending invitation identified by `membership_id`.", "operationId": "inviteTeamMember", "parameters": [ { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "resend" ] }, "description": "Optional action modifier. Omit to invite a new member; use `resend` to re-send a pending invitation." } ], "requestBody": { "required": true, "description": "Request body varies by action.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "InviteTeamMember", "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email", "description": "Email address of the user to invite" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "Role to assign to the invited member" } } }, { "title": "ResendTeamInvite", "type": "object", "required": [ "membership_id" ], "properties": { "membership_id": { "type": "integer", "minimum": 1, "description": "ID of the pending team membership to resend the invitation for" } } } ] } } } }, "responses": { "200": { "description": "Invitation resent successfully (?action=resend)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string" } } } }, "required": [ "error", "success", "data" ] } } } }, "201": { "description": "Invitation sent successfully (default invite action)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "membership_id": { "type": "integer" }, "user_id": { "type": "integer" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "status": { "type": "string", "enum": [ "invited" ] } }, "required": [ "message", "membership_id", "email", "role", "status" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "team:write" ] }, { "apiKeyHeader": [ "team:write" ] }, { "sessionAuth": [] } ] }, "patch": { "tags": [ "Team" ], "summary": "Update a team member's role", "description": "Change the role of an existing team member. Cannot change the owner's role.", "operationId": "updateTeamMember", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "membership_id", "role" ], "properties": { "membership_id": { "type": "integer" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] } } } } } }, "responses": { "200": { "description": "Role updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "membership_id": { "type": "integer" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] } }, "required": [ "message", "membership_id", "role" ] } }, "required": [ "error", "success", "data" ] } } } }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [ "team:write" ] }, { "apiKeyHeader": [ "team:write" ] }, { "sessionAuth": [] } ] }, "delete": { "tags": [ "Team" ], "summary": "Remove a team member", "description": "Remove a team member from the current tenant. Cannot remove the owner.", "operationId": "removeTeamMember", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "The membership ID to remove", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Team member removed successfully" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "security": [ { "bearerAuth": [ "team:write" ] }, { "apiKeyHeader": [ "team:write" ] }, { "sessionAuth": [] } ] } }, "/trust": { "get": { "tags": [ "Trust" ], "summary": "Get trust level status, level change history, or score event history", "description": "Returns the current trust level, score, auto top-up ceiling, progress toward next level, and tips for increasing trust. Use `?action=history` to get paginated trust level change history. Use `?action=score_history` to get granular per-event score history showing every reward, penalty, and decay event with score_before/score_after.", "operationId": "getTrust", "security": [ { "bearerAuth": [ "trust:read" ] }, { "apiKeyHeader": [ "trust:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "history", "score_history" ] }, "description": "Use 'history' to get trust level change history. Use 'score_history' to get granular trust score event history." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 }, "description": "Number of history entries to return (history action only)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Offset for pagination (history action only)" } ], "responses": { "200": { "description": "Trust status or history", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "trust_level": { "type": "integer", "description": "Current trust level (0-5)" }, "trust_label": { "type": "string", "description": "Human-readable trust level label" }, "trust_score": { "type": "integer", "description": "Numeric trust score accumulator" }, "ceiling": { "type": "number", "nullable": true, "description": "Monthly auto top-up ceiling for current level" }, "auto_topup": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "amount": { "type": "number", "nullable": true }, "ceiling": { "type": "number", "nullable": true }, "monthly_used": { "type": "number" }, "monthly_remaining": { "type": "number", "nullable": true } } }, "trust_level_changed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last trust level change" }, "progress": { "type": "object", "description": "Progress toward next trust level" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/fraud-signals": { "get": { "tags": [ "Trust" ], "summary": "List fraud signals or demotion history", "description": "Returns fraud detection signals for the current tenant. Use `?action=demotions` for automated demotion history, `?action=severity` for current cumulative severity score.", "operationId": "listFraudSignals", "security": [ { "bearerAuth": [ "trust:read" ] }, { "apiKeyHeader": [ "trust:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "demotions", "severity" ] }, "description": "Use 'demotions' for demotion history, 'severity' for current cumulative severity" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25, "maximum": 100 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } }, { "name": "unresolved", "in": "query", "schema": { "type": "string", "enum": [ "0", "1" ] }, "description": "Set to '1' to return only unresolved signals" } ], "responses": { "200": { "description": "Fraud signals, demotion history, or severity", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "oneOf": [ { "title": "FraudSignalList", "description": "Default response \u2014 paginated list of fraud signals (no action parameter)", "type": "object", "properties": { "signals": { "type": "array", "items": { "type": "object", "properties": { "signal_id": { "type": "string" }, "signal_type": { "type": "string", "example": "velocity_anomaly" }, "severity": { "type": "integer" }, "details": { "type": [ "object", "null" ] }, "resolved": { "type": "boolean" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "signal_id", "signal_type", "severity", "details", "resolved", "created_at" ] } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "signals", "total", "limit", "offset", "has_more" ] }, { "title": "FraudSeveritySummary", "description": "Returned when action=severity \u2014 current time-weighted cumulative severity and demotion thresholds", "type": "object", "properties": { "tenant_id": { "type": "string" }, "cumulative_severity_24h": { "type": "integer" }, "demotion_threshold_one_level": { "type": "integer" }, "demotion_threshold_level_zero": { "type": "integer" } }, "required": [ "tenant_id", "cumulative_severity_24h", "demotion_threshold_one_level", "demotion_threshold_level_zero" ] }, { "title": "FraudDemotionList", "description": "Returned when action=demotions \u2014 paginated automated demotion history", "type": "object", "properties": { "demotions": { "type": "array", "items": { "type": "object", "properties": { "demotion_id": { "type": "string" }, "previous_level": { "type": "integer" }, "new_level": { "type": "integer" }, "trigger_signals": { "type": "array", "items": { "type": "string" } }, "cumulative_severity": { "type": "integer" }, "auto_topup_disabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "demotion_id", "previous_level", "new_level", "trigger_signals", "cumulative_severity", "auto_topup_disabled", "created_at" ] } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "demotions", "total", "limit", "offset", "has_more" ] } ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Trust" ], "summary": "Resolve a fraud signal or run evaluation", "description": "Use `?action=resolve` with `signal_id` in body to dismiss a signal. Use `?action=evaluate` to run all fraud checks on the current tenant.", "operationId": "manageFraudSignals", "security": [ { "bearerAuth": [ "trust:write" ] }, { "apiKeyHeader": [ "trust:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "resolve", "evaluate" ] } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "signal_id": { "type": "string", "description": "Signal ID to resolve (required for resolve action)" } } } } } }, "responses": { "200": { "description": "Action result", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object" } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/agent-registry": { "get": { "tags": [ "Agent Tools" ], "summary": "Discover active agents, query activity, or check product contention", "description": "Same-tenant agent discovery for multi-agent coordination. Supports three actions: list_agents (list active delegations with workflow counts), agent_activity (summary for a specific agent), and check_contention (detect overlapping product interest across agents).", "operationId": "getAgentRegistry", "security": [ { "bearerAuth": [ "agent:discover" ] }, { "apiKeyHeader": [ "agent:discover" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "description": "Action: list_agents | agent_activity | check_contention", "schema": { "type": "string", "enum": [ "list_agents", "agent_activity", "check_contention" ] } }, { "name": "status", "in": "query", "description": "Delegation status filter for list_agents (default: active)", "schema": { "type": "string", "enum": [ "active", "expired", "revoked", "all" ] } }, { "name": "capability_scope", "in": "query", "description": "Filter list_agents to delegations holding this action scope", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "description": "ISO 8601 datetime \u2014 only return delegations created after this time", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "delegation_id", "in": "query", "description": "Target delegation ID for agent_activity", "schema": { "type": "string" } }, { "name": "agent_identifier", "in": "query", "description": "Target agent key ID for agent_activity (alternative to delegation_id)", "schema": { "type": "string" } }, { "name": "product_ids", "in": "query", "description": "Comma-separated product IDs for check_contention (max 50)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "description": "Response payload (agents list, agent activity, or contention results)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/agent-workflow": { "get": { "tags": [ "AgentWorkflows" ], "summary": "List or retrieve agent workflows, spending summaries, anomalies, and agent stats", "description": "Returns agent workflow data. Use `action=spending_summary` for per-agent spending analytics, `action=anomalies` or `action=detect_anomalies` (SDK alias) for anomaly detection, `action=agent_stats&agent_id=X` for detailed agent analytics, `action=pending_approvals` to list workflows awaiting approval, `action=approval_status&id=X` to check approval token status, or no action for workflow listing.", "operationId": "getAgentWorkflows", "parameters": [ { "name": "action", "in": "query", "description": "Action to perform: spending_summary, anomalies, detect_anomalies, agent_stats, pending_approvals, or approval_status", "schema": { "type": "string", "enum": [ "spending_summary", "anomalies", "detect_anomalies", "agent_stats", "pending_approvals", "approval_status" ] } }, { "name": "id", "in": "query", "description": "Specific workflow ID to retrieve (wf_xxx)", "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "description": "Agent key ID for agent_stats action", "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Time period for spending_summary: day, week, or month", "schema": { "type": "string", "enum": [ "day", "week", "month" ], "default": "month" } }, { "name": "granularity", "in": "query", "description": "Granularity for agent_stats trend data: daily or weekly", "schema": { "type": "string", "enum": [ "daily", "weekly" ], "default": "daily" } }, { "name": "status", "in": "query", "description": "Filter by workflow status", "schema": { "type": "string", "enum": [ "planned", "executing", "negotiating", "awaiting_approval", "completed", "failed", "cancelled" ] } }, { "name": "delegation_id", "in": "query", "description": "Filter by delegation ID for concurrent workflow tracking", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Workflow(s) retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/AgentWorkflow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "agent:execute" ] }, { "apiKeyHeader": [ "agent:execute" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "AgentWorkflows" ], "summary": "Plan, execute, modify, approve, or reject a workflow", "description": "Plan a new autonomous deal workflow, execute a planned workflow asynchronously, modify an in-progress deal, or cancel a workflow. Use `action=execute` with `id` to execute, `action=modify` with `id` to modify, `action=cancel` with `id` to cancel, or omit action to plan a new workflow.\n\nApproval gate actions: POST with action=approve or action=reject to resume or cancel a workflow in awaiting_approval state. Supports both admin session auth and one-time approval_token for webhook deep-links.", "operationId": "createAgentWorkflow", "parameters": [ { "name": "id", "in": "query", "description": "Workflow ID for execute/modify/cancel actions", "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Action to perform. Omit to plan a new workflow. Use execute/modify/cancel to manage workflow execution. Use approve/reject to handle approval gates. Use resend_approval to resend the notification, escalate_approval to escalate to the grantor, or delegate_approve for agent-scoped approval.", "schema": { "type": "string", "enum": [ "execute", "modify", "cancel", "approve", "reject", "resend_approval", "escalate_approval", "delegate_approve" ] } }, { "name": "token", "in": "query", "description": "One-time approval token for token-based approve/reject (webhook deep-links). Supersedes session auth for approval gate actions.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "delegation_id": { "type": "string", "description": "Delegation ID to operate under (required for planning)" }, "intent": { "type": "string", "enum": [ "purchase" ], "description": "Workflow intent" }, "constraints": { "type": "object", "properties": { "max_budget": { "type": "number", "description": "Maximum budget for the deal" }, "product_categories": { "type": "array", "items": { "type": "string" }, "description": "Product categories to search" }, "required_options": { "type": "object", "description": "Required product options" }, "auto_negotiate": { "type": "boolean", "description": "Whether to auto-negotiate if counter-offered" }, "max_negotiation_rounds": { "type": "integer", "description": "Maximum negotiation rounds" }, "max_discount_percent": { "type": "number", "description": "Maximum discount percent to accept" }, "customer_id": { "type": "string", "description": "Existing customer ID to use for the deal" }, "customer_email": { "type": "string", "description": "Customer email \u2014 looks up existing or creates new" } } }, "discount": { "type": "object", "description": "Discount to apply (for modify action)", "properties": { "type": { "type": "string", "enum": [ "fixed", "percentage" ] }, "value": { "type": "number" }, "code": { "type": "string" }, "description": { "type": "string" } } }, "metadata": { "type": "object", "description": "Metadata to merge into deal (for modify action)" }, "notes": { "type": "string", "description": "Notes to add to deal (for modify action)" }, "approved_by": { "type": "string", "maxLength": 255, "description": "Identifier of the approver (for approve action; defaults to authenticated user)" }, "note": { "type": "string", "maxLength": 2000, "description": "Optional note to attach when approving a workflow" }, "rejected_by": { "type": "string", "maxLength": 255, "description": "Identifier of the reviewer rejecting the workflow (for reject action; defaults to authenticated user)" }, "reason": { "type": "string", "maxLength": 2000, "description": "Rejection reason (for reject action)" }, "token": { "type": "string", "maxLength": 255, "description": "One-time approval token (for approve/reject via body instead of query param)" }, "escalation_reason": { "type": "string", "maxLength": 2000, "description": "Required reason when escalating an approval to the delegation grantor (for escalate_approval action)" }, "approval_note": { "type": "string", "maxLength": 2000, "description": "Optional note when approving via delegation scope (for delegate_approve action)" } } } } } }, "responses": { "200": { "description": "Workflow action completed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/AgentWorkflow" } }, "required": [ "error", "success", "data" ] } } } }, "201": { "description": "Workflow planned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/AgentWorkflow" } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "agent:execute" ] }, { "apiKeyHeader": [ "agent:execute" ] }, { "sessionAuth": [] } ] } }, "/agent-trust": { "get": { "tags": [ "AgentTrust" ], "summary": "Get agent trust level, capabilities, and progress", "description": "Returns the agent trust level, score, unlocked capabilities, trust lock statuses, and progress toward the next level for the authenticated API key. Use `?action=history` for trust level change history, or `?action=locks` for all trust lock statuses.", "operationId": "getAgentTrust", "parameters": [ { "name": "action", "in": "query", "description": "Action to perform: omit for full status, 'history' for change log, 'locks' for capability gates", "schema": { "type": "string", "enum": [ "history", "locks" ] } }, { "name": "limit", "in": "query", "description": "Max results for history action (1-100, default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "description": "Pagination offset for history action", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Agent trust status, history, or lock information", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "key_id": { "type": "string" }, "trust_level": { "type": "integer", "minimum": 0, "maximum": 4 }, "trust_label": { "type": "string" }, "trust_score": { "type": "integer" }, "transaction_cap": { "type": "number", "nullable": true }, "capabilities": { "type": "object" }, "progress": { "type": "object", "nullable": true } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [ "agent:discover" ] }, { "apiKeyHeader": [ "agent:discover" ] }, { "sessionAuth": [] } ] } }, "/agent-trust-credentials": { "get": { "tags": [ "AgentTrust" ], "summary": "Export the current agent's trust credential", "description": "Export the current agent's W3C Verifiable Credential for trust portability. The credential contains the agent's trust level, score, and deal history, signed by the tenant's Ed25519 key. Requires trust level 2+.", "operationId": "getAgentTrustCredential", "responses": { "200": { "description": "Agent trust credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "credential_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ] }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" }, "credential": { "type": "object", "description": "Full W3C Verifiable Credential JSON" } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "agent:discover" ] }, { "apiKeyHeader": [ "agent:discover" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "AgentTrust" ], "summary": "Issue, present, verify, or revoke trust credentials", "description": "Manage W3C Verifiable Credentials for agent trust portability. Use `?action=issue` to issue a new credential, `?action=present` to present a credential for trust bootstrapping, `?action=verify` to verify a credential, or `?action=revoke` to revoke a credential.", "operationId": "handleAgentTrustCredential", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "issue", "present", "verify", "revoke" ] }, "description": "Action to perform" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "credential": { "type": "object", "description": "W3C VC JSON (for present/verify actions)" }, "credential_id": { "type": "string", "description": "Credential ID (for revoke action)" }, "reason": { "type": "string", "description": "Revocation reason (for revoke action)" } } } } } }, "responses": { "200": { "description": "Operation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "201": { "description": "Credential issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "security": [ { "bearerAuth": [ "agent:discover" ] }, { "apiKeyHeader": [ "agent:discover" ] }, { "sessionAuth": [] } ] } }, "/trust/revocations": { "get": { "tags": [ "Trust" ], "summary": "Get revoked agent trust credentials list", "description": "Public endpoint returning the list of revoked agent trust credentials for a tenant. Used by receiving Salesbooth instances to verify credential revocation status.", "operationId": "getTrustRevocations", "parameters": [ { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Tenant ID to get revocations for" } ], "responses": { "200": { "description": "Revocation list", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "issuer": { "type": "string", "description": "Issuer DID" }, "type": { "type": "string" }, "revoked_credentials": { "type": "array" }, "count": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [] } }, "/did-document": { "get": { "tags": [ "Trust" ], "summary": "Get the tenant's DID document for credential verification", "description": "Serves the W3C did:web DID document containing the tenant's Ed25519 public key. Used for verifying agent trust credential signatures. Also accessible at /.well-known/did.json.", "operationId": "getDidDocument", "parameters": [ { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Tenant ID to get DID document for" } ], "responses": { "200": { "description": "DID document", "content": { "application/json": { "schema": { "type": "object", "properties": { "@context": { "type": "array" }, "id": { "type": "string" }, "verificationMethod": { "type": "array" }, "authentication": { "type": "array" }, "assertionMethod": { "type": "array" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [] } }, "/agent-discovery-admin": { "get": { "tags": [ "AgentDiscovery" ], "summary": "Get agent discovery dashboard, products, preview, or analytics", "description": "Provides dashboard stats, paginated product list with discovery status, agent preview, agent vs human analytics, and agent pricing rules. Use the `action` parameter to select the view.", "operationId": "getAgentDiscoveryAdmin", "parameters": [ { "name": "action", "in": "query", "description": "Action to perform: dashboard, products, preview, analytics, agent-deals, pricing-rules", "schema": { "type": "string", "enum": [ "dashboard", "products", "preview", "analytics", "agent-deals", "pricing-rules" ], "default": "dashboard" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Agent discovery data", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Dashboard overview (action=dashboard, default)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "total_products": { "type": "integer" }, "discoverable_products": { "type": "integer" }, "discoverable_deals": { "type": "integer" }, "agent_deals_30d": { "type": "integer" }, "human_deals_30d": { "type": "integer" }, "agent_conversion_rate": { "type": "number" }, "human_conversion_rate": { "type": "number" }, "api_queries_30d": { "type": "integer" }, "products_missing_fields": { "type": "integer" } }, "required": [ "total_products", "discoverable_products", "discoverable_deals", "agent_deals_30d", "human_deals_30d", "agent_conversion_rate", "human_conversion_rate", "api_queries_30d", "products_missing_fields" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Product list (action=products)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "price": { "type": "number" }, "type": { "type": "string" }, "category": { "type": "string" }, "pricing_model": { "type": "string" }, "agent_discoverable": { "type": "boolean" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer" } } } }, "required": [ "products", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Agent vs human analytics (action=analytics)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "period_days": { "type": "integer" }, "agent": { "type": "object", "properties": { "total_deals": { "type": "integer" }, "closed_deals": { "type": "integer" }, "conversion_rate": { "type": "number" }, "total_value": { "type": "number" }, "avg_value": { "type": "number" }, "avg_days_to_close": { "type": "number" } } }, "human": { "type": "object", "properties": { "total_deals": { "type": "integer" }, "closed_deals": { "type": "integer" }, "conversion_rate": { "type": "number" }, "total_value": { "type": "number" }, "avg_value": { "type": "number" }, "avg_days_to_close": { "type": "number" } } }, "daily_trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "source": { "type": "string", "enum": [ "agent", "human" ] }, "deal_count": { "type": "integer" }, "total_value": { "type": "number" } } } } }, "required": [ "period_days", "agent", "human", "daily_trend" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Agent-initiated deals (action=agent-deals) or pricing rules (action=pricing-rules) or preview (action=preview)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ] }, "post": { "tags": [ "AgentDiscovery" ], "summary": "Toggle product discoverability or bulk update", "description": "Toggle agent_discoverable for a single product, bulk enable/disable for multiple products, or create/update/delete agent pricing rules.", "operationId": "postAgentDiscoveryAdmin", "parameters": [ { "name": "action", "in": "query", "description": "Action to perform: toggle, bulk-toggle, save-pricing-rule, delete-pricing-rule", "required": true, "schema": { "type": "string", "enum": [ "toggle", "bulk-toggle", "save-pricing-rule", "delete-pricing-rule" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product ID (for toggle action)" }, "product_ids": { "type": "array", "items": { "type": "string" }, "description": "Product IDs (for bulk-toggle action)" }, "enabled": { "type": "boolean", "description": "Enable or disable (for bulk-toggle action)" } } } } } }, "responses": { "200": { "description": "Toggle result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ] } }, "/csp-report": { "post": { "tags": [ "Security" ], "summary": "Receive CSP violation report", "description": "Accepts Content-Security-Policy violation reports sent automatically by browsers. Reports are rate-limited (100/hour/IP), logged, and stored for security monitoring. Returns 204 No Content per the CSP spec.", "operationId": "postCspReport", "security": [], "requestBody": { "required": true, "content": { "application/csp-report": { "schema": { "type": "object", "properties": { "csp-report": { "type": "object", "properties": { "document-uri": { "type": "string" }, "violated-directive": { "type": "string" }, "blocked-uri": { "type": "string" }, "source-file": { "type": "string" }, "line-number": { "type": "integer" }, "column-number": { "type": "integer" }, "disposition": { "type": "string" } } } } } }, "application/json": { "schema": { "type": "object", "properties": { "csp-report": { "type": "object" } } } } } }, "responses": { "204": { "description": "Report accepted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "405": { "description": "Method not allowed \u2014 only POST accepted" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/gdpr/erase": { "delete": { "tags": [ "GDPR" ], "operationId": "gdprErase", "summary": "Right to erasure \u2014 single-system (Art. 17)", "description": "Erases all customer PII within the local system. Unlike full_erase, does not propagate to external systems.", "parameters": [ { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Customer ID to erase" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for erasure", "default": "GDPR erasure request" } } } } } }, "responses": { "200": { "description": "Erasure completed successfully" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ] } }, "/gdpr/full_erase": { "delete": { "tags": [ "GDPR" ], "operationId": "gdprFullErase", "summary": "Full cross-system GDPR erasure (Art. 17)", "description": "Atomically erases all customer PII across all systems: customer record, deals, contracts, communication logs, audit trail, consent records, webhook payloads, and search indexes.", "parameters": [ { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Customer ID to erase" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason for erasure", "default": "GDPR full erasure request" } } } } } }, "responses": { "200": { "description": "Erasure completed successfully" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ] } }, "/gdpr/verify": { "get": { "tags": [ "GDPR" ], "operationId": "gdprVerifyErasure", "summary": "Verify erasure completeness", "description": "Scans all tables for remaining PII and returns a verification report.", "parameters": [ { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Customer ID to verify" } ], "responses": { "200": { "description": "Verification report", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "verification": { "type": "object", "description": "Erasure verification report indicating remaining PII across all tables" } }, "required": [ "verification" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/export": { "get": { "tags": [ "GDPR" ], "operationId": "gdprExport", "summary": "Data export / portability (Art. 15/20)", "description": "Exports all stored data for a customer in a portable JSON format, covering profile, deals, contracts, consents, communications, and audit trail.", "parameters": [ { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Customer ID to export data for" } ], "responses": { "200": { "description": "Customer data export", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "export": { "type": "object", "description": "Full portable data export covering profile, deals, contracts, consents, communications, and audit trail" } }, "required": [ "export" ] } }, "required": [ "error", "success", "data" ] } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/consent": { "post": { "tags": [ "GDPR" ], "operationId": "gdprConsentRecord", "summary": "Record consent for a purpose", "description": "Records a new consent grant for a customer and purpose. Supports optional channel and consent version metadata.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id", "purpose" ], "properties": { "customer_id": { "type": "string", "description": "Customer ID" }, "purpose": { "type": "string", "description": "Consent purpose (e.g. marketing, analytics, necessary)" }, "channel": { "type": "string", "default": "api", "description": "Channel through which consent was obtained" }, "metadata": { "type": "object", "description": "Optional metadata about the consent" }, "consent_version": { "type": "string", "description": "Optional consent policy version" } } } } } }, "responses": { "201": { "description": "Consent recorded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "consent": { "type": "object", "description": "Recorded consent record" } }, "required": [ "consent" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ] }, "delete": { "tags": [ "GDPR" ], "operationId": "gdprConsentWithdraw", "summary": "Withdraw consent for a purpose", "description": "Withdraws an existing consent record for a customer and purpose.", "parameters": [ { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Customer ID to withdraw consent for" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "purpose" ], "properties": { "purpose": { "type": "string", "description": "Consent purpose to withdraw" } } } } } }, "responses": { "200": { "description": "Consent withdrawn successfully" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ] }, "get": { "tags": [ "GDPR" ], "operationId": "gdprConsentList", "summary": "List consent records for a customer", "description": "Returns all consent records for a customer, optionally filtered to active-only.", "parameters": [ { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Customer ID to list consents for" }, { "name": "active_only", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Filter to active consents only" } ], "responses": { "200": { "description": "Consent records with valid purposes", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Customer ID" }, "consents": { "type": "array", "items": { "type": "object" }, "description": "Consent records for the customer" }, "valid_purposes": { "type": "array", "items": { "type": "string" }, "description": "All valid consent purpose identifiers" } }, "required": [ "customer_id", "consents", "valid_purposes" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/consent_withdraw_all": { "post": { "tags": [ "GDPR" ], "operationId": "gdprConsentWithdrawAll", "summary": "Batch withdraw all consent", "description": "Withdraws all active consent records for a customer in a single operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string", "description": "Customer ID" }, "reason": { "type": "string", "description": "Reason for batch withdrawal", "default": "Batch consent withdrawal" } } } } } }, "responses": { "200": { "description": "Consent withdrawal summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "consent_withdrawal": { "type": "object", "description": "Batch consent withdrawal result" } }, "required": [ "consent_withdrawal" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ] } }, "/gdpr/retention": { "get": { "tags": [ "GDPR" ], "operationId": "gdprRetentionGet", "summary": "Get retention policies", "description": "Returns all data retention policies for the current tenant, along with valid data types.", "responses": { "200": { "description": "Retention policies and valid data types", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "policies": { "type": "array", "items": { "type": "object" }, "description": "Data retention policies for the tenant" }, "valid_data_types": { "type": "array", "items": { "type": "string" }, "description": "All valid data type identifiers" } }, "required": [ "policies", "valid_data_types" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] }, "patch": { "tags": [ "GDPR" ], "operationId": "gdprRetentionUpdate", "summary": "Update a retention policy", "description": "Creates or updates a data retention policy for a specific data type.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "data_type", "retention_days" ], "properties": { "data_type": { "type": "string", "description": "Data type to set retention for" }, "retention_days": { "type": "integer", "description": "Number of days to retain data" }, "is_active": { "type": "boolean", "default": true, "description": "Whether the policy is active" } } } } } }, "responses": { "200": { "description": "Retention policy updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "policy": { "type": "object", "description": "Updated retention policy" } }, "required": [ "policy" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ] } }, "/gdpr/register": { "get": { "tags": [ "GDPR" ], "operationId": "gdprRegister", "summary": "Get data processing register (Art. 30)", "description": "Returns all active entries from the data processing register, including data categories, processing purposes, legal bases, retention periods, and data recipients.", "responses": { "200": { "description": "Data processing register entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "register": { "type": "array", "items": { "type": "object", "properties": { "data_category": { "type": "string" }, "data_fields": { "type": "array", "items": { "type": "string" } }, "processing_purpose": { "type": "string" }, "legal_basis": { "type": "string" }, "retention_period_days": { "type": "integer" }, "data_recipients": { "type": "array", "items": { "type": "string" } }, "transfer_safeguards": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "description": "Active data processing register entries (Art. 30)" } }, "required": [ "register" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/erasure_log": { "get": { "tags": [ "GDPR" ], "operationId": "gdprErasureLog", "summary": "Get paginated erasure/export audit log", "description": "Returns paginated list of erasure and export audit log entries for the current tenant.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of entries to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Maximum entries to return" } ], "responses": { "200": { "description": "Paginated erasure log entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": { "log_id": { "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "type": "string" }, "action": { "type": "string", "enum": [ "erased", "data_exported" ] }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "changes": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "Erasure and export log entries" }, "offset": { "type": "integer", "description": "Current page offset" }, "limit": { "type": "integer", "description": "Page size limit" }, "has_more": { "type": "boolean", "description": "Whether more entries exist" } }, "required": [ "entries", "offset", "limit", "has_more" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/consent_renew": { "post": { "tags": [ "GDPR" ], "operationId": "gdprConsentRenew", "summary": "Renew consent for a purpose", "description": "Extends the expiration of an existing consent record for a customer and purpose. Creates a new audit entry distinct from initial grant.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id", "purpose" ], "properties": { "customer_id": { "type": "string" }, "purpose": { "type": "string" }, "channel": { "type": "string", "default": "api" }, "expiration_months": { "type": "integer", "description": "Custom expiration in months (optional)" } } } } } }, "responses": { "200": { "description": "Consent renewed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "consent": { "type": "object", "description": "Renewed consent record" } }, "required": [ "consent" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ] } }, "/gdpr/consent_renew_all": { "post": { "tags": [ "GDPR" ], "operationId": "gdprConsentRenewAll", "summary": "Renew all consents for a customer", "description": "Renews all active or expired (non-withdrawn) consents for a customer in a single operation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id" ], "properties": { "customer_id": { "type": "string" }, "channel": { "type": "string", "default": "api" } } } } } }, "responses": { "200": { "description": "All consents renewed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "consent_renewal": { "type": "object", "description": "Batch consent renewal result" } }, "required": [ "consent_renewal" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ] } }, "/gdpr/consent_expiring": { "get": { "tags": [ "GDPR" ], "operationId": "gdprConsentExpiring", "summary": "Get consents expiring within N days", "description": "Returns consent records that will expire within the specified number of days.", "parameters": [ { "name": "days_ahead", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 365 }, "description": "Number of days to look ahead" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 }, "description": "Maximum records to return" } ], "responses": { "200": { "description": "List of expiring consent records", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "expiring_consents": { "type": "array", "items": { "type": "object" }, "description": "Consent records expiring within the requested window" }, "count": { "type": "integer", "description": "Number of expiring consent records returned" }, "days_ahead": { "type": "integer", "description": "Lookahead window in days used for the query" } }, "required": [ "expiring_consents", "count", "days_ahead" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/consent_health": { "get": { "tags": [ "GDPR" ], "operationId": "gdprConsentHealth", "summary": "Get consent health metrics", "description": "Returns aggregate consent health metrics including active, expiring, expired, and withdrawn counts with a health percentage score.", "responses": { "200": { "description": "Consent health metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "consent_health": { "type": "object", "properties": { "active_valid": { "type": "integer" }, "expiring_soon": { "type": "integer" }, "expired": { "type": "integer" }, "withdrawn": { "type": "integer" }, "health_percent": { "type": "number", "format": "float" }, "total_consents": { "type": "integer" } }, "description": "Aggregate consent health metrics" } }, "required": [ "consent_health" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/consent_expiration_config": { "get": { "tags": [ "GDPR" ], "operationId": "gdprConsentExpirationConfigGet", "summary": "Get consent expiration config", "description": "Returns the per-purpose consent expiration configuration for the current tenant, merged with global defaults.", "responses": { "200": { "description": "Expiration configuration per purpose", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "expiration_config": { "type": "object", "description": "Per-purpose expiration overrides configured for this tenant" }, "defaults": { "type": "object", "description": "Global default expiration months per purpose" }, "valid_purposes": { "type": "array", "items": { "type": "string" }, "description": "All valid consent purpose identifiers" } }, "required": [ "expiration_config", "defaults", "valid_purposes" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "GDPR" ], "operationId": "gdprConsentExpirationConfigSet", "summary": "Set consent expiration config", "description": "Sets the default expiration period (in months) for a specific consent purpose for the current tenant.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "purpose", "expiration_months" ], "properties": { "purpose": { "type": "string" }, "expiration_months": { "type": "integer", "minimum": 1, "maximum": 120 } } } } } }, "responses": { "200": { "description": "Expiration config updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "config": { "type": "object", "description": "Updated expiration configuration" } }, "required": [ "config" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:write" ] }, { "apiKeyHeader": [ "customers:write" ] }, { "sessionAuth": [] } ] } }, "/gdpr/consent_purposes": { "get": { "tags": [ "GDPR" ], "operationId": "gdprConsentPurposes", "summary": "List available consent purposes with default expiration periods", "description": "Returns all valid consent purposes with human-readable labels and default expiration periods in months.", "responses": { "200": { "description": "List of consent purposes", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "purposes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Purpose identifier" }, "label": { "type": "string", "description": "Human-readable label" }, "expiration_months": { "type": "integer", "description": "Default expiration in months" } }, "required": [ "id", "label", "expiration_months" ] }, "description": "All valid consent purposes with labels and expiration defaults" } }, "required": [ "purposes" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/dashboard": { "get": { "tags": [ "GDPR" ], "operationId": "gdprDashboard", "summary": "Compliance dashboard \u2014 consent health, recent DSARs, erasure stats", "description": "Returns aggregate compliance data: consent health metrics, recent DSARs (last 30 days), and erasure statistics. Suitable for the compliance overview panel.", "responses": { "200": { "description": "Compliance dashboard data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "consent_health": { "type": "object", "properties": { "active_valid": { "type": "integer" }, "expiring_soon": { "type": "integer" }, "expired": { "type": "integer" }, "withdrawn": { "type": "integer" }, "health_percent": { "type": "number", "format": "float" }, "total_consents": { "type": "integer" } } }, "recent_dsars": { "type": "array", "items": { "type": "object", "properties": { "log_id": { "type": "string" }, "entity_id": { "type": "string" }, "action": { "type": "string" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "Up to 10 most recent DSARs in the last 30 days" }, "dsar_count_30_days": { "type": "integer", "description": "Total DSARs in the last 30 days" }, "erasure_stats": { "type": "object", "properties": { "total": { "type": "integer" }, "last_30_days": { "type": "integer" }, "exports_total": { "type": "integer" }, "exports_last_30_days": { "type": "integer" } } } }, "required": [ "consent_health", "recent_dsars", "dsar_count_30_days", "erasure_stats" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/search": { "get": { "tags": [ "GDPR" ], "operationId": "gdprSearch", "summary": "Search customers with compliance context overlay", "description": "Searches customers by name, email, or ID using blind indexes, and overlays compliance context per result: active consent count and consent purposes held.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query (name, email, or customer ID)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "maximum": 20 } } ], "responses": { "200": { "description": "List of matching customers with compliance context", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "customers": { "type": "array", "items": { "type": "object", "properties": { "customer_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "company": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "active_consents": { "type": "integer" }, "consent_purposes": { "type": "array", "items": { "type": "string" } } } }, "description": "Matching customers with compliance context overlay" }, "query": { "type": "string", "description": "The search query used" }, "count": { "type": "integer", "description": "Number of results returned" } }, "required": [ "customers", "query", "count" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/compliance_evidence": { "get": { "tags": [ "GDPR" ], "operationId": "gdprComplianceEvidence", "summary": "Structured compliance evidence package for auditors (retention, consent stats, erasure log, audit integrity)", "description": "Returns a structured compliance package suitable for enterprise procurement reviews and regulator submission. Includes live retention policies with compliance status, consent statistics per purpose, recent erasure log with verification hashes, audit trail integrity check, and data processing register summary (Art. 30).", "parameters": [], "responses": { "200": { "description": "Compliance evidence package", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "evidence": { "type": "object", "properties": { "report_type": { "type": "string", "example": "compliance_evidence" }, "generated_at": { "type": "string", "format": "date-time" }, "tenant_id": { "type": "string" }, "retention_policies": { "type": "object" }, "consent_statistics": { "type": "object" }, "erasure_log": { "type": "object" }, "audit_integrity": { "type": "object" }, "data_processing_register": { "type": "object" } } } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/gdpr/audit_evidence": { "get": { "tags": [ "GDPR" ], "operationId": "gdprAuditEvidence", "summary": "Downloadable compliance evidence report with date range filter", "description": "Returns a structured compliance evidence report for a given date range, including DSAR log, erasure summary, consent health snapshot, and retention policies. Suitable for regulator submission.", "parameters": [ { "name": "date_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of date range (YYYY-MM-DD, defaults to 30 days ago)" }, { "name": "date_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of date range (YYYY-MM-DD, defaults to today)" } ], "responses": { "200": { "description": "Compliance evidence report", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "report": { "type": "object", "properties": { "report_type": { "type": "string", "example": "gdpr_compliance_evidence" }, "generated_at": { "type": "string", "format": "date-time" }, "report_period": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } } }, "tenant_id": { "type": "string" }, "consent_health": { "type": "object", "properties": { "active_valid": { "type": "integer" }, "expiring_soon": { "type": "integer" }, "expired": { "type": "integer" }, "withdrawn": { "type": "integer" }, "total_consents": { "type": "integer" }, "health_percent": { "type": "number", "format": "float" } } }, "dsar_summary": { "type": "object", "properties": { "total_in_period": { "type": "integer" }, "exports": { "type": "integer" }, "erasures": { "type": "integer" } } }, "dsar_log": { "type": "array", "items": { "type": "object" }, "description": "DSAR log entries within the date range (max 1000)" }, "retention_policies": { "type": "array", "items": { "type": "object" } }, "audit_entries_count": { "type": "integer" } } } }, "required": [ "report" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ] } }, "/federation-peers": { "get": { "tags": [ "Federation" ], "operationId": "listFederationPeers", "summary": "List trusted federation peers for tenant", "description": "Returns the list of approved peer hostnames for cross-instance federation. When at least one peer is configured, the tenant is in closed-federation mode and only listed peers may send inbound envelopes.", "security": [ { "bearerAuth": [ "agent:discover" ] }, { "apiKeyHeader": [ "agent:discover" ] }, { "sessionAuth": [] } ], "responses": { "200": { "description": "List of federation peers", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "peers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "hostname": { "type": "string" }, "remote_tenant_id": { "type": "string", "nullable": true }, "trust_level": { "type": "integer" }, "status": { "type": "string", "enum": [ "active", "suspended" ] }, "last_seen_at": { "type": "string", "nullable": true }, "created_at": { "type": "string" } } } }, "count": { "type": "integer" }, "open_mode": { "type": "boolean" } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Federation" ], "operationId": "addFederationPeer", "summary": "Add a trusted federation peer", "description": "Adds a remote Salesbooth instance hostname to the peer whitelist. Once any peer is added, all unlisted hostnames are blocked from sending inbound envelopes.", "security": [ { "bearerAuth": [ "agent:execute" ] }, { "apiKeyHeader": [ "agent:execute" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hostname" ], "properties": { "hostname": { "type": "string", "maxLength": 255, "description": "Remote instance FQDN (no scheme)" }, "remote_tenant_id": { "type": "string", "maxLength": 128 }, "trust_level": { "type": "integer", "minimum": 0, "maximum": 5, "default": 1 }, "status": { "type": "string", "enum": [ "active", "suspended" ], "default": "active" } } } } } }, "responses": { "201": { "description": "Peer added", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "hostname": { "type": "string" }, "remote_tenant_id": { "type": "string" }, "trust_level": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "hostname" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } }, "patch": { "tags": [ "Federation" ], "operationId": "updateFederationPeer", "summary": "Update federation peer status or trust level", "description": "Updates the status (active/suspended) or trust_level of an existing federation peer.", "security": [ { "bearerAuth": [ "agent:execute" ] }, { "apiKeyHeader": [ "agent:execute" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Peer ID to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "suspended" ] }, "trust_level": { "type": "integer", "minimum": 0, "maximum": 5 } } } } } }, "responses": { "200": { "description": "Peer updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "updated": { "type": "boolean" }, "id": { "type": "integer" } }, "required": [ "updated", "id" ] } }, "required": [ "error", "success", "data" ] } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Federation" ], "operationId": "removeFederationPeer", "summary": "Remove a federation peer from the whitelist", "description": "Permanently removes a peer from the tenant's federation whitelist.", "security": [ { "bearerAuth": [ "agent:execute" ] }, { "apiKeyHeader": [ "agent:execute" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Peer ID to delete" } ], "responses": { "200": { "description": "Peer deleted" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/federation/discovery": { "get": { "tags": [ "Federation" ], "operationId": "getFederationDiscovery", "summary": "Get federation discovery manifest", "description": "Returns the discovery manifest for a Salesbooth instance. Includes available products, deal capabilities, supported currencies, and the tenant's Ed25519 public key for signature verification. Public endpoint \u2014 no authentication required.", "security": [], "parameters": [ { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Tenant ID to get discovery manifest for" } ], "responses": { "200": { "description": "Discovery manifest", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "protocol": { "type": "string", "example": "salesbooth-negotiate/1.0" }, "instance": { "type": "object", "properties": { "tenant_id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "capabilities": { "type": "object", "properties": { "discovery": { "type": "boolean" }, "negotiation": { "type": "boolean" }, "escrow": { "type": "boolean" }, "signatures": { "type": "boolean" } } }, "catalog": { "type": "object", "properties": { "product_count": { "type": "integer" }, "deal_count": { "type": "integer" }, "currencies": { "type": "array", "items": { "type": "string" } } } }, "signing": { "type": "object", "nullable": true, "properties": { "algorithm": { "type": "string", "example": "ed25519" }, "key_id": { "type": "string" }, "public_key": { "type": "string" } } } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/federation/negotiate": { "get": { "tags": [ "Federation" ], "operationId": "getFederationStatus", "summary": "Get federation negotiation status", "description": "Returns federation capabilities for the authenticated tenant, or fetches the federated audit trail for a specific cross-reference ID.", "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "status", "audit" ] }, "description": "Action: 'status' (default) or 'audit'" }, { "name": "xref_id", "in": "query", "schema": { "type": "string" }, "description": "Cross-reference ID (required when action=audit)" } ], "responses": { "200": { "description": "Federation status or audit trail entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "oneOf": [ { "description": "Federation capabilities manifest (default action=status)", "type": "object", "properties": { "federation": { "type": "object", "properties": { "protocol": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "signing": { "type": "object", "nullable": true, "additionalProperties": true } }, "required": [ "protocol", "capabilities" ] } }, "required": [ "federation" ] }, { "description": "Audit trail entries for a cross-reference ID (action=audit)", "type": "object", "properties": { "xref_id": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": { "entry_id": { "type": "string" }, "xref_id": { "type": "string" }, "action": { "type": "string" }, "actor_tenant_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" } }, "required": [ "xref_id", "entries", "count" ] } ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "agent:discover" ] }, { "apiKeyHeader": [ "agent:discover" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Federation" ], "operationId": "handleFederationNegotiation", "summary": "Process cross-instance negotiation envelope", "description": "Handles cross-instance federation operations: discover remote instances, send signed negotiation envelopes, receive incoming envelopes, and coordinate escrow. Requires appropriate trust level and scopes.", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "discover", "send", "negotiate", "escrow", "settle", "dispute" ] }, "description": "Federation action type" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "instance": { "type": "string", "description": "Remote instance hostname (for discover)" }, "target_instance": { "type": "string", "description": "Remote instance hostname (for send)" }, "target_agent_id": { "type": "string", "description": "Remote agent ID" }, "type": { "type": "string", "enum": [ "discover", "propose", "counter", "accept", "reject", "escrow_coordinate" ], "description": "Envelope type" }, "payload": { "type": "object", "description": "Action-specific payload" }, "protocol": { "type": "string", "description": "Protocol version (for incoming envelopes)" }, "remote_tenant_id": { "type": "string", "description": "Remote tenant ID (for escrow)" }, "local_deal_id": { "type": "string", "description": "Local deal ID (for escrow)" }, "remote_deal_id": { "type": "string", "description": "Remote deal ID (for escrow)" }, "amount": { "type": "number", "description": "Escrow amount (for escrow)" }, "currency": { "type": "string", "description": "Currency code (for escrow)" }, "xref_id": { "type": "string", "description": "Cross-reference ID (for settle/dispute)" }, "local_escrow_id": { "type": "string", "description": "Local escrow ID to release (for settle)" }, "remote_escrow_id": { "type": "string", "description": "Remote escrow ID (for settle)" }, "timeout_seconds": { "type": "integer", "description": "Settlement timeout override in seconds (for settle)" }, "reason": { "type": "string", "description": "Dispute reason (for dispute)" } } } } } }, "responses": { "200": { "description": "Federation operation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "201": { "description": "Federation envelope sent or escrow coordinated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "envelope_id": { "type": "string" }, "xref_id": { "type": "string" }, "sent_to": { "type": "string" }, "type": { "type": "string" }, "remote_response": { "type": "object", "nullable": true }, "delivery_status": { "type": "string", "enum": [ "delivered", "failed" ] } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "agent:negotiate" ] }, { "bearerAuth": [ "agent:execute" ] }, { "apiKeyHeader": [ "agent:negotiate" ] }, { "apiKeyHeader": [ "agent:execute" ] }, { "sessionAuth": [] } ] } }, "/events/stream": { "get": { "tags": [ "Events" ], "operationId": "streamEvents", "summary": "Stream real-time events via SSE", "description": "Opens a Server-Sent Events stream for real-time deal, negotiation, payment, and other domain events. Supports event type filtering, entity-scoped streams, heartbeat keep-alive, and automatic reconnection with Last-Event-ID for missed-event recovery. Max 5 concurrent connections per API key. Stream auto-closes after 5 minutes; client should reconnect.", "parameters": [ { "name": "events", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated event types to filter (e.g. 'deal.updated,negotiation.countered'). Supports wildcards like 'deal.*'. Omit to receive all events.", "example": "deal.updated,deal.negotiation_accepted,payment.received" }, { "name": "deal_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter events for a specific deal" }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter events for a specific customer" }, { "name": "last_event_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Resume from this event ID (format: seq:). Also supported via Last-Event-ID header for automatic reconnection." } ], "responses": { "200": { "description": "SSE event stream. Content-Type: text/event-stream. Each event includes id (seq:), event type, and JSON data with _signature and _timestamp fields for integrity verification.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE formatted stream with events matching webhook event types" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [ "webhooks:read" ] }, { "apiKeyHeader": [ "webhooks:read" ] }, { "sessionAuth": [] } ] } }, "/staff": { "get": { "tags": [ "Staff" ], "summary": "List or retrieve staff members", "operationId": "getStaff", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Staff member ID" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "product_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by assigned product" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Staff member(s) data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffGetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "staff:read" ] }, { "apiKeyHeader": [ "staff:read" ] }, { "sessionAuth": [] } ], "description": "Returns staff members for the tenant. Staff are service providers who can be assigned to bookable products and appear in availability calendars." }, "post": { "tags": [ "Staff" ], "summary": "Create staff member or perform staff actions", "operationId": "postStaff", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Staff member ID (for actions)" }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "schedule", "override", "assign_product" ] }, "description": "Staff sub-action" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffCreateRequest" } } } }, "responses": { "201": { "description": "Staff member created or action performed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffWriteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "staff:write" ] }, { "apiKeyHeader": [ "staff:write" ] }, { "sessionAuth": [] } ], "description": "Creates a new staff member. Specify name, contact details, working hours, and bookable product assignments." }, "patch": { "tags": [ "Staff" ], "summary": "Update a staff member", "operationId": "patchStaff", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Staff member ID" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffUpdateRequest" } } } }, "responses": { "200": { "description": "Staff member updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StaffWriteResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "staff:write" ] }, { "apiKeyHeader": [ "staff:write" ] }, { "sessionAuth": [] } ], "description": "Updates a staff member record by ID. Modify working hours, contact details, or product assignments." }, "delete": { "tags": [ "Staff" ], "summary": "Deactivate staff member or remove assignment", "operationId": "deleteStaff", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Staff member ID" }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "override", "assign_product" ] } }, { "name": "override_id", "in": "query", "schema": { "type": "integer" } }, { "name": "product_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "responses": { "200": { "description": "Staff member deactivated or assignment removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "staff:write" ] }, { "apiKeyHeader": [ "staff:write" ] }, { "sessionAuth": [] } ], "description": "Removes a staff member by ID. Existing bookings for this staff member are not automatically cancelled." } }, "/availability": { "get": { "tags": [ "Availability" ], "summary": "Check available booking time slots", "description": "Returns available time slots for a product on a given date, or dates with availability for a given month. Used by the booking widget to display a calendar date picker and time slot grid.", "operationId": "getAvailability", "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^prod_[a-zA-Z0-9]+$" }, "description": "Product ID to check availability for" }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Specific date (YYYY-MM-DD) to get time slots" }, { "name": "month", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "description": "Month (YYYY-MM) to get dates with availability" }, { "name": "staff_id", "in": "query", "schema": { "type": "string", "pattern": "^stf_[a-zA-Z0-9]+$" }, "description": "Optional staff member ID for specific staff availability" } ], "responses": { "200": { "description": "Availability data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [] } }, "/bookings": { "get": { "tags": [ "Bookings" ], "summary": "List or retrieve bookings", "description": "List bookings with filters, retrieve a single booking by ID, or get booking analytics with action=analytics.", "operationId": "getBookings", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string", "pattern": "^bkng_[a-zA-Z0-9]+$" }, "description": "Booking ID" }, { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "analytics" ] }, "description": "Set to 'analytics' to return booking analytics (utilisation, no-show rate, staff metrics, peak hours, funnel)" }, { "name": "period", "in": "query", "schema": { "type": "string", "pattern": "^\\d+d$", "default": "30d" }, "description": "Analytics period (e.g. 7d, 30d, 90d). Only used with action=analytics" }, { "name": "staff_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by staff member" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "held", "confirmed", "completed", "cancelled", "no_show" ] } }, { "name": "deal_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by deal" }, { "name": "product_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by product" }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Booking(s) data or analytics", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "List response", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "bookings": { "type": "array", "items": { "$ref": "#/components/schemas/Booking" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "bookings", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Single booking response", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "booking": { "$ref": "#/components/schemas/Booking" } }, "required": [ "booking" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Analytics response (returned when action=analytics)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "analytics": { "type": "object", "description": "Booking analytics for the requested period", "properties": { "period": { "type": "object", "description": "Date range covered by this analytics snapshot", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "days": { "type": "integer", "description": "Number of days in the period" } }, "required": [ "from", "to", "days" ] }, "overview": { "type": "object", "description": "High-level booking metrics for the period", "properties": { "total_bookings": { "type": "integer" }, "no_show_rate": { "type": "number", "description": "No-show rate as a percentage (0\u2013100)" }, "no_show_trend": { "type": "number", "description": "Change in no-show rate compared to the previous period (percentage points)" }, "cancellation_rate": { "type": "number", "description": "Cancellation rate as a percentage (0\u2013100)" }, "cancellation_trend": { "type": "number", "description": "Change in cancellation rate compared to the previous period (percentage points)" }, "avg_lead_time_days": { "type": "number", "description": "Average days between booking creation and appointment date" } }, "required": [ "total_bookings", "no_show_rate", "no_show_trend", "cancellation_rate", "cancellation_trend", "avg_lead_time_days" ] }, "utilisation": { "type": "object", "description": "Slot utilisation rates across different time windows", "properties": { "today": { "type": "object", "properties": { "booked": { "type": "integer" }, "available": { "type": "integer" }, "rate": { "type": "number", "description": "Utilisation rate as a percentage (0\u2013100)" } }, "required": [ "booked", "available", "rate" ] }, "this_week": { "type": "object", "properties": { "booked": { "type": "integer" }, "available": { "type": "integer" }, "rate": { "type": "number", "description": "Utilisation rate as a percentage (0\u2013100)" } }, "required": [ "booked", "available", "rate" ] }, "period": { "type": "object", "properties": { "booked": { "type": "integer" }, "available": { "type": "integer" }, "rate": { "type": "number", "description": "Utilisation rate as a percentage (0\u2013100)" } }, "required": [ "booked", "available", "rate" ] } }, "required": [ "today", "this_week", "period" ] }, "staff": { "type": "array", "description": "Per-staff utilisation and performance metrics", "items": { "type": "object", "properties": { "staff_id": { "type": "string" }, "display_name": { "type": "string" }, "sessions_today": { "type": "integer" }, "max_daily_sessions": { "type": "integer" }, "sessions_week": { "type": "integer" }, "available_week": { "type": "integer", "description": "Available slots in the current week" }, "sessions_period": { "type": "integer", "description": "Confirmed/completed sessions in the analytics period" }, "no_show_rate": { "type": "number", "description": "Staff-level no-show rate as a percentage" }, "revenue": { "type": "number", "description": "Total revenue from completed bookings in the period" }, "status": { "type": "string", "enum": [ "overbooked", "optimal", "underutilised" ], "description": "Today's utilisation status relative to max_daily_sessions" } }, "required": [ "staff_id", "display_name", "sessions_today", "max_daily_sessions", "sessions_week", "available_week", "sessions_period", "no_show_rate", "revenue", "status" ] } }, "heatmap": { "type": "object", "description": "Peak hours heatmap: confirmed/completed bookings grouped by day-of-week and hour", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer", "description": "Day of week (1=Sunday \u2026 7=Saturday, MySQL DAYOFWEEK convention)" }, "hour": { "type": "integer", "description": "Hour of day (0\u201323)" }, "count": { "type": "integer" } }, "required": [ "day", "hour", "count" ] } }, "max": { "type": "integer", "description": "Maximum count across all heatmap cells, useful for normalising colour intensity" } }, "required": [ "data", "max" ] }, "funnel": { "type": "object", "description": "Booking conversion funnel from hold through to completion", "properties": { "held": { "type": "integer", "description": "Total bookings created (all start as held)" }, "confirmed": { "type": "integer", "description": "Bookings that reached confirmed, completed, or no_show status" }, "completed": { "type": "integer" }, "expired_holds": { "type": "integer", "description": "Holds that expired or were cancelled before confirmation" }, "no_shows": { "type": "integer" }, "hold_to_confirm_rate": { "type": "number", "description": "Percentage of holds that were confirmed (0\u2013100)" }, "confirm_to_complete_rate": { "type": "number", "description": "Percentage of confirmed bookings that were completed (0\u2013100)" }, "avg_hold_to_confirm_minutes": { "type": "number", "description": "Average minutes between slot hold and confirmation" } }, "required": [ "held", "confirmed", "completed", "expired_holds", "no_shows", "hold_to_confirm_rate", "confirm_to_complete_rate", "avg_hold_to_confirm_minutes" ] } }, "required": [ "period", "overview", "utilisation", "staff", "heatmap", "funnel" ] } }, "required": [ "analytics" ] } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "bookings:read" ] }, { "apiKeyHeader": [ "bookings:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Bookings" ], "summary": "Create or hold a booking slot", "description": "Temporarily holds a time slot for a service product during checkout. The hold expires after 10 minutes if not confirmed.", "operationId": "postBookings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id", "staff_id", "date", "start_time" ], "properties": { "product_id": { "type": "string" }, "staff_id": { "type": "string" }, "date": { "type": "string", "format": "date" }, "start_time": { "type": "string", "format": "time" }, "duration": { "type": "integer", "default": 60 }, "customer_name": { "type": "string", "maxLength": 255, "description": "Customer full name" }, "customer_email": { "type": "string", "format": "email", "description": "Customer email address" }, "customer_phone": { "type": "string", "maxLength": 50, "description": "Customer phone number" }, "notes": { "type": "string", "description": "Optional notes about the booking" } } } } } }, "responses": { "201": { "description": "Booking slot held", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "booking": { "$ref": "#/components/schemas/Booking" } }, "required": [ "booking" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "bookings:write" ] }, { "apiKeyHeader": [ "bookings:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ] }, "patch": { "tags": [ "Bookings" ], "summary": "Update booking status", "description": "Transition a booking through its lifecycle: confirm, cancel, complete, mark as no-show, or reschedule to a new date/time.", "operationId": "patchBookings", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^bkng_[a-zA-Z0-9]+$" } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "BookingConfirmRequest", "type": "object", "required": [ "action", "deal_id" ], "properties": { "action": { "type": "string", "enum": [ "confirm" ] }, "deal_id": { "type": "string", "description": "Deal to associate with this booking confirmation" }, "line_item_id": { "type": "string", "description": "Specific line item within the deal" }, "customer_id": { "type": "string", "description": "Customer to associate with this booking" } } }, { "title": "BookingCancelRequest", "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "cancel" ] }, "reason": { "type": "string", "description": "Optional cancellation reason" } } }, { "title": "BookingCompleteRequest", "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "complete" ] } } }, { "title": "BookingNoShowRequest", "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "no_show" ] } } }, { "title": "BookingRescheduleRequest", "type": "object", "required": [ "action", "product_id", "staff_id", "date", "start_time" ], "properties": { "action": { "type": "string", "enum": [ "reschedule" ] }, "product_id": { "type": "string", "maxLength": 50, "description": "Product (service) to book for the new slot" }, "staff_id": { "type": "string", "maxLength": 50, "description": "Staff member to assign the rescheduled slot to" }, "date": { "type": "string", "format": "date", "description": "New appointment date (YYYY-MM-DD)" }, "start_time": { "type": "string", "format": "time", "description": "New appointment start time (HH:MM)" }, "duration": { "type": "integer", "minimum": 5, "maximum": 480, "default": 60, "description": "Duration in minutes" }, "customer_name": { "type": "string", "maxLength": 255 }, "customer_email": { "type": "string", "format": "email" }, "customer_phone": { "type": "string", "maxLength": 50 }, "notes": { "type": "string", "maxLength": 65535 } } } ] } } } }, "responses": { "200": { "description": "Booking updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "booking": { "$ref": "#/components/schemas/Booking" } }, "required": [ "booking" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "bookings:write" ] }, { "apiKeyHeader": [ "bookings:write" ] }, { "sessionAuth": [] } ] }, "delete": { "tags": [ "Bookings" ], "summary": "Cancel a booking", "operationId": "deleteBookings", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^bkng_[a-zA-Z0-9]+$" } }, { "name": "reason", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/idempotencyKey" } ], "responses": { "200": { "description": "Booking cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "booking": { "$ref": "#/components/schemas/Booking" } }, "required": [ "booking" ] } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "bookings:write" ] }, { "apiKeyHeader": [ "bookings:write" ] }, { "sessionAuth": [] } ], "description": "Cancels an existing booking by ID. Sends cancellation notifications to the customer and staff member. Optionally accepts a cancellation reason." } }, "/playground/session": { "post": { "tags": [ "Playground" ], "summary": "Create an ephemeral playground session with sandbox API key", "description": "Provisions an ephemeral sandbox API key (sb_test_*) for the interactive SDK playground. Keys expire after 2 hours and have limited scopes. Rate limited to 10 sessions per hour per IP.", "operationId": "playgroundCreateSession", "security": [], "responses": { "200": { "description": "Session created with ephemeral API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body required. An ephemeral sandbox API key is automatically generated.", "properties": {} } } } } }, "get": { "tags": [ "Playground" ], "summary": "Check if a playground session key is still valid", "description": "Validates whether a playground session key is still active and not expired.", "operationId": "playgroundGetSession", "security": [], "parameters": [ { "name": "key_prefix", "in": "query", "required": true, "schema": { "type": "string", "minLength": 8 }, "description": "First 12 characters of the playground API key" } ], "responses": { "200": { "description": "Session validity status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/site-suggestions": { "get": { "tags": [ "SiteSuggestions" ], "summary": "List or retrieve site optimization suggestions, learning insights, impact dashboard, optimizer settings, health score, digest data, impact report, or cumulative impact", "description": "Returns AI-generated optimization suggestions for tenant sites. Filter by site_id, status, category, or priority. Use insights=1 for learning analytics, impact_dashboard=1 for conversion trends and ROI, settings=1&site_id=x for optimizer settings, health_score=1&site_id=x for optimization health score, digest=1&site_id=x for weekly digest data, impact_report=1&site_id=x for per-suggestion impact analysis, or cumulative_impact=1 for cross-site cumulative lift.", "operationId": "getSiteSuggestions", "security": [ { "bearerAuth": [ "sites:read" ] }, { "apiKeyHeader": [ "sites:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "description": "Suggestion ID for single retrieval", "required": false, "schema": { "type": "string" } }, { "name": "insights", "in": "query", "description": "Set to 1 to get learning insights (acceptance rates, impact summary, top performers)", "required": false, "schema": { "type": "string" } }, { "name": "impact_dashboard", "in": "query", "description": "Set to 1 to get impact dashboard data (conversion timeline, category impact, velocity, auto-accept stats)", "required": false, "schema": { "type": "string" } }, { "name": "settings", "in": "query", "description": "Set to 1 to get optimizer settings for a site (requires site_id)", "required": false, "schema": { "type": "string" } }, { "name": "site_id", "in": "query", "description": "Filter by site ID", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status", "required": false, "schema": { "type": "string", "enum": [ "pending", "accepted", "rejected", "applied", "rolled_back" ] } }, { "name": "category", "in": "query", "description": "Filter by category", "required": false, "schema": { "type": "string", "enum": [ "cta", "widget", "content", "layout", "mobile", "seo", "form", "trust" ] } }, { "name": "priority", "in": "query", "description": "Filter by priority", "required": false, "schema": { "type": "string", "enum": [ "high", "medium", "low" ] } }, { "name": "health_score", "in": "query", "description": "Set to 1 to get optimization health score for a site (requires site_id)", "required": false, "schema": { "type": "string" } }, { "name": "digest", "in": "query", "description": "Set to 1 to get weekly digest data for a site (requires site_id)", "required": false, "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "description": "Set to 1 to include archived suggestions in the list", "required": false, "schema": { "type": "string" } }, { "name": "days", "in": "query", "description": "Number of days for impact dashboard/report period (7-180, default 30 for dashboard, 90 for report)", "required": false, "schema": { "type": "integer" } }, { "name": "impact_report", "in": "query", "description": "Set to 1 to get detailed per-suggestion impact report with effectiveness ratings (requires site_id recommended)", "required": false, "schema": { "type": "string" } }, { "name": "cumulative_impact", "in": "query", "description": "Set to 1 to get cumulative impact across all sites (total lift, per-site breakdown, monthly timeline)", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max results (1-100, default 20)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination offset (0-based)", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Suggestions returned successfully. Response shape varies by query parameter: default list, single suggestion (?id), insights, impact_dashboard, settings, health_score, digest, impact_report, or cumulative_impact.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Default suggestion list", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "suggestion_id": { "type": "string" }, "site_id": { "type": "string" }, "category": { "type": "string", "enum": [ "cta", "widget", "content", "layout", "mobile", "seo", "form", "trust" ] }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected", "applied", "rolled_back" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "change_type": { "type": "string" }, "target_selector": { "type": "string", "nullable": true }, "original_value": { "type": "string", "nullable": true }, "suggested_value": { "type": "string", "nullable": true }, "baseline_conversion": { "type": "number", "nullable": true }, "post_conversion": { "type": "number", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_by": { "type": "string", "nullable": true }, "applied_at": { "type": "string", "format": "date-time", "nullable": true }, "rolled_back_at": { "type": "string", "format": "date-time", "nullable": true }, "archived_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "suggestions", "total", "limit", "offset" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Single suggestion (?id=...), insights (?insights=1), impact dashboard (?impact_dashboard=1), settings (?settings=1), health score (?health_score=1), digest (?digest=1), impact report (?impact_report=1), or cumulative impact (?cumulative_impact=1)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "error", "success", "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "patch": { "tags": [ "SiteSuggestions" ], "summary": "Accept, reject, or rollback a suggestion", "description": "Update the status of a site optimization suggestion. Accepted suggestions are automatically applied to dev_source (pages) or config tables (widgets).", "operationId": "patchSiteSuggestion", "security": [ { "bearerAuth": [ "sites:write" ] }, { "apiKeyHeader": [ "sites:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The suggestion_id to update" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "accept", "reject", "rollback" ], "description": "The action to perform on the suggestion" } } } } } }, "responses": { "200": { "description": "Suggestion updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "SiteSuggestions" ], "summary": "Batch accept/reject, update settings, trigger analysis, create A/B test, export, archive, dismiss rollback, or mark published", "description": "Perform batch operations on suggestions, update per-site optimizer settings (including auto-accept and auto-rollback), queue a manual analysis run, create an A/B test from a widget suggestion, export suggestions as CSV, archive old suggestions, dismiss a rollback recommendation, or mark applied suggestions as published.", "operationId": "postSiteSuggestionAction", "security": [ { "bearerAuth": [ "sites:write" ] }, { "apiKeyHeader": [ "sites:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "batch", "settings", "analyze", "ab_test", "export", "archive", "dismiss_rollback", "mark_published" ], "description": "The type of action to perform" }, "batch_action": { "type": "string", "enum": [ "accept", "reject" ], "description": "Required for action=batch. Accept or reject all matching pending suggestions" }, "site_id": { "type": "string", "description": "Site ID to filter batch action, or target site for settings/analyze" }, "batch_id": { "type": "string", "description": "Analysis batch ID to filter batch action" }, "category": { "type": "string", "description": "Category to filter batch action" }, "settings": { "type": "object", "description": "Optimizer settings object for action=settings (includes auto_accept, auto_rollback settings)", "properties": { "enabled": { "type": "boolean" }, "email_notifications": { "type": "boolean" }, "frequency_days": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "string" } }, "auto_accept_enabled": { "type": "boolean" }, "auto_accept_min_confidence": { "type": "integer" }, "auto_accept_categories": { "type": "array", "items": { "type": "string" } }, "auto_accept_exclude_html": { "type": "boolean" }, "auto_rollback_enabled": { "type": "boolean" }, "auto_rollback_threshold": { "type": "number" } } }, "page_id": { "type": "string", "description": "Page ID for action=mark_published (marks all applied page suggestions as published)" }, "suggestion_id": { "type": "string", "description": "Suggestion ID for action=ab_test" }, "traffic_weight_b": { "type": "integer", "description": "Traffic weight for variant B in A/B test (10-90, default 50)" }, "auto_promote": { "type": "boolean", "description": "Auto-promote winner when significance reached (for A/B test)" }, "older_than_days": { "type": "integer", "description": "Archive suggestions older than N days (for action=archive, default 30)" }, "statuses": { "type": "array", "items": { "type": "string" }, "description": "Statuses to archive (for action=archive)" }, "date_from": { "type": "string", "description": "Start date for export (YYYY-MM-DD format)" }, "date_to": { "type": "string", "description": "End date for export (YYYY-MM-DD format)" } } } } } }, "responses": { "200": { "description": "Action completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/customer-auth": { "post": { "tags": [ "CustomerPortal" ], "summary": "Customer portal authentication actions", "description": "Magic-link authentication for the customer portal. Public endpoint \u2014 no seller API key required. Use `action` query parameter: `request-access` sends a magic-link email, `verify` validates the link and issues a JWT, `refresh` renews an expired JWT, `logout` revokes the session.", "operationId": "postCustomerAuth", "security": [], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "request-access", "verify", "refresh", "logout" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Customer email (for request-access)" }, "token": { "type": "string", "description": "Magic-link token (for verify)" }, "refresh_token": { "type": "string", "description": "Refresh token (for refresh)" }, "session_id": { "type": "string", "description": "Session ID (for logout fallback)" } } } } } }, "responses": { "200": { "description": "Authentication action completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customer-portal": { "get": { "tags": [ "CustomerPortal" ], "summary": "Customer portal data retrieval", "description": "Authenticated customer endpoints for self-service portal data. Requires Bearer JWT from customer-auth. Use `action` query parameter to select endpoint.", "operationId": "getCustomerPortal", "security": [ { "customerBearerAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "my-deals", "deal", "contract", "my-subscriptions", "profile", "portal-config", "consents" ] } }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Deal ID (for action=deal)" }, { "name": "deal_id", "in": "query", "schema": { "type": "string" }, "description": "Deal ID (for action=contract, portal-config)" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Filter by status (for action=my-deals)" }, { "name": "limit", "in": "query", "schema": { "type": "integer" }, "description": "Page size (for action=my-deals)" }, { "name": "offset", "in": "query", "schema": { "type": "integer" }, "description": "Page offset (for action=my-deals)" } ], "responses": { "200": { "description": "Data returned successfully. Response shape varies by action parameter.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "My deals list (action=my-deals, default)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deals": { "type": "array", "items": { "type": "object", "properties": { "deal_id": { "type": "string" }, "status": { "type": "string" }, "deal_type": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "string" }, "total_formatted": { "type": "string" }, "payment_status": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "billing_cycle": { "type": "string", "description": "Billing frequency (only present for recurring deals)" }, "subscription_status": { "type": "string", "description": "Subscription state (only present for recurring deals)" }, "next_billing_date": { "type": "string", "format": "date", "description": "Next billing date (only present for recurring deals)" } } } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "limit", "offset", "count", "total" ] } }, "required": [ "deals", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Deal detail (action=deal), contract (action=contract), profile (action=profile), subscriptions (action=my-subscriptions), portal config (action=portal-config), or consents (action=consents)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "error", "success", "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "CustomerPortal" ], "summary": "Customer portal actions", "description": "Authenticated customer actions \u2014 create payment intents, confirm payments, sign contracts, request changes, and manage consents.", "operationId": "postCustomerPortal", "security": [ { "customerBearerAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "create-payment-intent", "confirm-payment", "sign", "request-changes", "consent-renew", "consent-renew-all" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "Deal ID for payment/signing actions" }, "payment_intent_id": { "type": "string", "description": "Stripe PaymentIntent ID (for confirm-payment)" }, "signature_name": { "type": "string", "description": "Typed full name (for sign)" }, "agreed": { "type": "boolean", "description": "Terms agreement (for sign)" }, "message": { "type": "string", "description": "Change request message (for request-changes)" }, "purpose": { "type": "string", "description": "Consent purpose (for consent-renew)" } } } } } }, "responses": { "200": { "description": "Action completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "tags": [ "CustomerPortal" ], "summary": "Update customer profile", "description": "Update the authenticated customer's profile information (name, email, phone, company, address fields).", "operationId": "patchCustomerProfile", "security": [ { "customerBearerAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "profile" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "company": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" } } } } } }, "responses": { "200": { "description": "Profile updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "customer_id": { "type": "string" }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "company": { "type": "string", "nullable": true }, "message": { "type": "string" } }, "required": [ "customer_id" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/activity": { "get": { "tags": [ "Activity" ], "summary": "List activity feed events, notifications, or notification rules", "operationId": "getActivity", "parameters": [ { "name": "action", "in": "query", "description": "Sub-resource to retrieve. Omit for the activity feed. `notifications` returns notifications for the current user. `unread_count` returns the unread notification count. `rules` lists notification rules. `preferences` returns notification preferences.", "required": false, "schema": { "type": "string", "enum": [ "notifications", "unread_count", "rules", "preferences" ] } }, { "name": "event_type", "in": "query", "description": "Filter feed by event type (e.g. `deal.created`, `payment.received`). Only applies when `action` is omitted.", "required": false, "schema": { "type": "string" } }, { "name": "actor_type", "in": "query", "description": "Filter feed by actor type. Only applies when `action` is omitted.", "required": false, "schema": { "type": "string", "enum": [ "user", "agent", "system" ] } }, { "name": "entity_type", "in": "query", "description": "Filter feed by entity type. Only applies when `action` is omitted.", "required": false, "schema": { "type": "string", "enum": [ "deal", "contract", "customer" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return (default 50, max 100).", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Pagination offset.", "required": false, "schema": { "type": "integer", "default": 0 } }, { "name": "unread_only", "in": "query", "description": "When present, filters notifications to unread only. Only applies when `action=notifications`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns the activity feed for the tenant \u2014 a chronological log of deal events, customer actions, payment notifications, and system alerts. Supports filtering by entity, date range, and event type." }, "post": { "tags": [ "Activity" ], "summary": "Create notification rule, mark notifications read, or send test notification", "operationId": "manageActivity", "parameters": [ { "name": "action", "in": "query", "description": "Action to perform. `mark_read` marks specific notifications as read (requires `notification_ids` in body). `mark_all_read` marks all notifications as read. `create_rule` creates a new notification rule. `test_notification` sends a test notification.", "required": false, "schema": { "type": "string", "enum": [ "mark_read", "mark_all_read", "create_rule", "test_notification" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "201": { "description": "Activity notification rule created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Creates a new activity entry or notification rule. Use `action=create_rule` to configure automated notifications for specific event types.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "mark_read", "mark_all_read", "create_rule", "test_notification" ], "description": "Action to perform. `mark_read`: mark notification IDs read. `mark_all_read`: mark all read. `create_rule`: create a notification rule. `test_notification`: send a test notification." }, "notification_ids": { "type": "array", "items": { "type": "string" }, "description": "Notification IDs to mark as read (required for action=mark_read)" }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Event types to trigger the rule on (for action=create_rule)" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "in_app", "email", "sms", "webhook" ] }, "description": "Delivery channels for the rule (for action=create_rule)" }, "webhook_url": { "type": "string", "description": "Webhook URL (required when channels includes webhook)" } } } } } } }, "patch": { "tags": [ "Activity" ], "summary": "Update a notification rule", "operationId": "updateActivityRule", "parameters": [ { "name": "action", "in": "query", "description": "Must be `update_rule`.", "required": true, "schema": { "type": "string", "enum": [ "update_rule" ] } }, { "name": "rule_id", "in": "query", "description": "ID of the notification rule to update.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityRuleUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Updates an activity entry or notification rule partially. Modify specific fields without replacing the entire record." }, "delete": { "tags": [ "Activity" ], "summary": "Delete a notification rule", "operationId": "deleteActivityRule", "parameters": [ { "name": "action", "in": "query", "description": "Must be `delete_rule`.", "required": true, "schema": { "type": "string", "enum": [ "delete_rule" ] } }, { "name": "rule_id", "in": "query", "description": "ID of the notification rule to delete.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Deletes an activity notification rule by ID." }, "put": { "tags": [ "Activity" ], "summary": "Save notification preferences", "operationId": "saveActivityPreferences", "parameters": [ { "name": "action", "in": "query", "description": "Must be `preferences`.", "required": true, "schema": { "type": "string", "enum": [ "preferences" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Save user notification preferences. Set boolean toggles for each event type to control which notifications are received.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_created": { "type": "object", "description": "Notification preferences for deal.created events", "properties": { "in_app": { "type": "boolean" }, "email": { "type": "boolean" }, "sms": { "type": "boolean" } } }, "deal_status_changed": { "type": "object", "description": "Notification preferences for deal.status_changed events", "properties": { "in_app": { "type": "boolean" }, "email": { "type": "boolean" }, "sms": { "type": "boolean" } } }, "payment_received": { "type": "object", "description": "Notification preferences for payment.received events", "properties": { "in_app": { "type": "boolean" }, "email": { "type": "boolean" }, "sms": { "type": "boolean" } } }, "contract_signed": { "type": "object", "description": "Notification preferences for contract.signed events", "properties": { "in_app": { "type": "boolean" }, "email": { "type": "boolean" }, "sms": { "type": "boolean" } } } } } } } } } }, "/activity-stream": { "get": { "tags": [ "Activity" ], "summary": "Real-time SSE activity stream", "operationId": "streamActivity", "responses": { "200": { "description": "SSE event stream. Content-Type: text/event-stream. Each event includes an event type and JSON data payload.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "SSE formatted stream of tenant activity events" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns a paginated stream of tenant activity events for the merchant dashboard activity feed. Includes deals, payments, customer actions, and system events sorted by recency." } }, "/ai-website": { "post": { "tags": [ "Websites" ], "summary": "Generate website, site template, or page using AI", "operationId": "generateAiWebsite", "description": "Triggers AI-powered website generation using the tenant's business profile and design bibles. Three modes are available via the `action` parameter: `generate` builds all site pages (default), `template` regenerates the shared CSS, header, and footer, and `page` generates or regenerates a single page. Rate limits differ by action: `generate` and `template` allow 3 requests/hour per tenant; `page` allows 10 requests/hour.", "parameters": [ { "name": "action", "in": "query", "required": false, "description": "Generation mode. `generate` builds all pages (default). `template` regenerates the shared CSS, header, and footer. `page` generates or regenerates a single page.", "schema": { "type": "string", "enum": [ "generate", "page", "template" ], "default": "generate" } } ], "requestBody": { "required": true, "description": "Request body varies by action. All actions require `site_id`. The `page` action additionally requires `slug` or `title`.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "GenerateWebsite", "type": "object", "description": "Generate a full website with multiple pages (`action=generate`).", "required": [ "site_id" ], "properties": { "site_id": { "type": "string", "description": "ID of the site to generate pages for" }, "theme_mode": { "type": "string", "enum": [ "light", "dark" ], "default": "light", "description": "Colour theme for the generated site" }, "primary_color": { "type": "string", "description": "Brand primary colour (hex, e.g. #4F46E5)" }, "pages": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "home", "services", "about", "reviews", "contact", "pricing", "team", "portfolio", "faq" ] }, "description": "Page slugs to generate. Defaults to home, services, about, reviews, contact." }, "single_page": { "type": "boolean", "description": "Generate as a single-page site with hash navigation instead of separate pages" } } }, { "title": "GenerateTemplate", "type": "object", "description": "Regenerate the shared site template \u2014 CSS variables, header, and footer (`action=template`).", "required": [ "site_id" ], "properties": { "site_id": { "type": "string", "description": "ID of the site to regenerate the template for" }, "theme_mode": { "type": "string", "enum": [ "light", "dark" ], "default": "light", "description": "Colour theme" }, "primary_color": { "type": "string", "description": "Brand primary colour (hex)" }, "single_page": { "type": "boolean", "description": "Generate navigation as hash links for single-page mode" }, "pages": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "home", "services", "about", "reviews", "contact", "pricing", "team", "portfolio", "faq" ] }, "description": "Page slugs to include in the navigation. Defaults to home, services, about, reviews, contact." } } }, { "title": "GeneratePage", "type": "object", "description": "Generate or regenerate a single page (`action=page`).", "required": [ "site_id" ], "properties": { "site_id": { "type": "string", "description": "ID of the site that owns the page" }, "slug": { "type": "string", "maxLength": 100, "description": "Page slug (e.g. `services`). Required if `title` is not provided." }, "title": { "type": "string", "maxLength": 255, "description": "Page title. Used as a fallback when `slug` is absent." }, "prompt": { "type": "string", "maxLength": 2000, "description": "Custom generation prompt to override the default page prompt" }, "single_page": { "type": "boolean", "description": "Generate content using hash navigation (for single-page sites)" }, "pages": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "home", "services", "about", "reviews", "contact", "pricing", "team", "portfolio", "faq" ] }, "description": "All page slugs in the site (used to generate accurate internal links)" }, "is_homepage": { "type": "boolean", "description": "Whether this page is the site homepage" } } } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ] } }, "/auth": { "get": { "tags": [ "Auth" ], "summary": "Check current session authentication status", "operationId": "getAuthStatus", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [], "description": "Returns the current session state \u2014 authenticated user details, active tenant context, and session metadata. Use this to verify authentication status and retrieve the current user profile." }, "post": { "tags": [ "Auth" ], "summary": "Login with email and password", "operationId": "login", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "description": "User email address" }, "password": { "type": "string", "description": "User password" }, "remember": { "type": "boolean", "default": true, "description": "Keep session alive after browser close" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [], "description": "Authenticates a user and creates a new session. Accepts email and password credentials. Returns session token and user profile on success." }, "delete": { "tags": [ "Auth" ], "summary": "Logout and destroy current session", "operationId": "logout", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Terminates the current session and invalidates the session token. Use this to implement logout." } }, "/batch": { "post": { "tags": [ "Batch" ], "summary": "Execute multiple API operations in a single request (max 25)", "operationId": "executeBatch", "responses": { "200": { "description": "Batch operations completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "description": "Executes up to 25 API operations in a single HTTP request. Each operation is an independent API call (method + path + body). Operations execute sequentially; use `atomic=true` to roll back all on any failure.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "description": "Array of batch operations to execute (max 25)", "maxItems": 25, "items": { "type": "object", "required": [ "method", "resource" ], "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PATCH", "DELETE" ], "description": "HTTP method for the operation" }, "resource": { "type": "string", "enum": [ "deals", "customers", "products", "contracts" ], "description": "Resource type to operate on" }, "id": { "type": "string", "description": "Resource ID (required for PATCH and DELETE)" }, "body": { "type": "object", "description": "Request body for POST and PATCH operations" }, "version": { "type": "integer", "description": "Expected resource version for optimistic locking" }, "action": { "type": "string", "description": "Optional action modifier (e.g. `transition` for deal status changes)" } } } } } } } } } } }, "/budget": { "get": { "tags": [ "Budget" ], "summary": "Get current budget settings and spend tracking", "operationId": "getBudget", "responses": { "200": { "description": "Budget settings and current spend tracking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns the current monthly budget configuration and spend tracking for the tenant \u2014 budget limit, current spend, alert thresholds, and remaining balance." }, "post": { "tags": [ "Budget" ], "summary": "Save budget settings (monthly limit and alert thresholds)", "operationId": "saveBudget", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Sets or updates the monthly budget limit and alert thresholds for the tenant. Budget alerts are delivered via activity notifications when spend reaches configured thresholds.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "monthly_limit": { "type": "number", "description": "Monthly spending limit in dollars. Pass null or omit to clear the budget.", "minimum": 0 }, "alert_at_percent": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 200 }, "description": "Percentage thresholds at which to send budget alert notifications (e.g. [80, 100])" } } } } } } } }, "/business-profile": { "get": { "tags": [ "BusinessProfile" ], "summary": "Get tenant business profile", "operationId": "getBusinessProfile", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:read" ] }, { "apiKeyHeader": [ "admin:read" ] }, { "sessionAuth": [] } ], "description": "Returns the tenant's business profile including business description, industry, and AI website generation context. The description is used as source material for AI-powered website generation." }, "post": { "tags": [ "BusinessProfile" ], "summary": "Save tenant business profile", "operationId": "saveBusinessProfile", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:write" ] }, { "apiKeyHeader": [ "admin:write" ] }, { "sessionAuth": [] } ], "description": "Creates or updates the tenant's business profile. The business description is used as input for AI website generation and for training the chat assistant on merchant-specific context.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "business_name" ], "properties": { "business_name": { "type": "string", "description": "Name of the business" }, "industry": { "type": "string", "description": "Industry or sector" }, "description": { "type": "string", "description": "Business description used for AI website generation" }, "target_audience": { "type": "string", "description": "Target audience or customer segment" }, "tone": { "type": "string", "description": "Brand tone (e.g. professional, friendly, technical)", "default": "professional" } } } } } } } }, "/cache": { "get": { "tags": [ "Cache" ], "summary": "Get cache statistics", "operationId": "getCacheStats", "responses": { "200": { "description": "Cache statistics across all tiers (APCu and Redis)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CacheStatsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin" ] }, { "apiKeyHeader": [ "admin" ] }, { "sessionAuth": [] } ], "description": "Returns cache statistics for the tenant \u2014 hit/miss ratios, memory usage, and key counts by cache tier. Useful for monitoring cache performance and identifying bottlenecks." }, "delete": { "tags": [ "Cache" ], "summary": "Flush all caches or invalidate by prefix", "operationId": "flushCache", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin" ] }, { "apiKeyHeader": [ "admin" ] }, { "sessionAuth": [] } ], "description": "Flushes cache entries for the tenant. Use `scope` to target specific cache namespaces (e.g. products, deals, widget-config) without clearing unrelated entries." } }, "/channels": { "get": { "tags": [ "Channels" ], "summary": "Get communication channel settings", "operationId": "getChannels", "responses": { "200": { "description": "Tenant communication channel settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChannelsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns the communication channel configuration for the tenant \u2014 registered phone numbers and email addresses used for outbound customer communications." }, "post": { "tags": [ "Channels" ], "summary": "Save communication channel settings", "operationId": "saveChannels", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Configures a communication channel (phone number or email address) for the tenant. Used to set the sender address for SMS and email notifications.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "voice_number": { "type": "string", "description": "E.164 phone number for outbound voice calls (e.g. +61412345678)" }, "sms_number": { "type": "string", "description": "E.164 phone number for outbound SMS messages" }, "from_email": { "type": "string", "format": "email", "description": "From email address for outbound emails" }, "from_name": { "type": "string", "description": "Display name for outbound emails" }, "reply_to_email": { "type": "string", "format": "email", "description": "Reply-to / inbound email address" } } } } } } } }, "/chat": { "post": { "tags": [ "Chat" ], "summary": "Send AI assistant chat message with streaming support", "operationId": "sendChat", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "maxItems": 100, "description": "Conversation history in Anthropic message format", "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object" } } ] } } } }, "model": { "type": "string", "maxLength": 100, "default": "claude-sonnet-4-6", "description": "Anthropic model ID to use" }, "stream": { "type": "boolean", "default": false, "description": "Enable Server-Sent Events streaming" }, "thinking": { "type": "boolean", "default": false, "description": "Enable extended thinking mode" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Sends a message to the Salesbooth AI business assistant and returns a streaming response. The assistant has access to the tenant's deals, customers, products, and business context to answer merchant-specific questions." } }, "/dashboard-stats": { "get": { "tags": [ "Dashboard" ], "summary": "Get consolidated dashboard statistics", "operationId": "getDashboardStats", "parameters": [ { "name": "range", "in": "query", "description": "Time range for revenue time-series: '7d' (last 7 days) or '30d' (last 30 days, default)", "required": false, "schema": { "type": "string", "enum": ["7d", "30d"], "default": "30d" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardStatsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "description": "Returns consolidated dashboard statistics for the merchant \u2014 deal pipeline counts, revenue metrics, conversion rates, attention items, and time-series charts." } }, "/display-mode": { "get": { "tags": [ "Preferences" ], "summary": "Get current display mode setting", "operationId": "getDisplayMode", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:read" ] }, { "apiKeyHeader": [ "admin:read" ] }, { "sessionAuth": [] } ], "description": "Returns the current display mode preference for the authenticated user (light, dark, or system)." }, "post": { "tags": [ "Preferences" ], "summary": "Set display mode (standalone, browser, or auto)", "operationId": "setDisplayMode", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:write" ] }, { "apiKeyHeader": [ "admin:write" ] }, { "sessionAuth": [] } ], "description": "Sets the display mode preference for the authenticated user.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "browser", "standalone", "auto" ], "description": "`browser`: switch to browser mode; `standalone`: switch to PWA/app mode; `auto`: clear forced mode and return to auto-detection" } } } } } } } }, "/domain-check": { "get": { "tags": [ "Websites" ], "summary": "Get server IP for DNS A-record setup", "operationId": "getServerIp", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "const": "server_ip" }, "description": "Must be 'server_ip'" } ], "responses": { "200": { "description": "Server IP address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns the server IP address to use as the DNS A-record when pointing a custom domain to Salesbooth." }, "post": { "tags": [ "Websites" ], "summary": "Check domain availability for registration", "operationId": "checkDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain name to check (e.g. example.com)" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Checks whether a domain name is available for registration via the GoDaddy registrar integration. Returns availability status and suggested alternatives if unavailable." } }, "/import": { "post": { "tags": [ "Import" ], "summary": "Parse, validate, or execute CSV import for customers or products", "operationId": "importData", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "parse", "validate", "import" ] }, "description": "Import operation: parse CSV, validate mapped data, or execute import" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "201": { "description": "Import completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Processes a bulk CSV import for customers or products. Accepts a parsed CSV payload from the import wizard, validates rows, and inserts valid records. Returns import results with error details for failed rows.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_type", "csv_content" ], "properties": { "entity_type": { "type": "string", "enum": [ "customers", "products" ], "description": "Entity type to import" }, "csv_content": { "type": "string", "description": "CSV file contents as a string" }, "mapping": { "type": "object", "description": "Column mapping from CSV header to entity field (required for validate and import actions)", "additionalProperties": { "type": "string" } }, "defaults": { "type": "object", "description": "Default values to apply to all imported rows", "additionalProperties": true }, "sample_rows": { "type": "integer", "description": "Number of sample rows to return in parse response (default 5)", "default": 5 }, "skip_errors": { "type": "boolean", "description": "Skip rows that fail validation rather than aborting the import (default true)", "default": true } } } } } } } }, "/negotiations-dashboard": { "get": { "tags": [ "NegotiationsDashboard" ], "summary": "Get negotiations dashboard stats and active negotiations list", "operationId": "getNegotiationsDashboard", "parameters": [ { "name": "view", "in": "query", "required": false, "description": "View mode. `dashboard` (default) returns stats and active negotiations list; `detail` returns full negotiation history for a single deal (requires `deal_id`); `batch_status` returns negotiation statuses for multiple deals (requires `deal_ids`).", "schema": { "type": "string", "enum": [ "dashboard", "detail", "batch_status" ], "default": "dashboard" } }, { "name": "deal_id", "in": "query", "required": false, "description": "Deal ID to retrieve negotiation history for. Required when `view=detail`.", "schema": { "type": "string" } }, { "name": "deal_ids", "in": "query", "required": false, "description": "Comma-separated list of deal IDs (max 100). Required when `view=batch_status`.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter negotiations by status. Applicable when `view=dashboard`.", "schema": { "type": "string", "enum": [ "pending", "accepted", "rejected", "expired", "countered" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "description": "Returns merchant negotiation management data \u2014 active negotiations count, pending proposals, auto-accept threshold, and a paginated list of negotiations requiring attention." }, "post": { "tags": [ "NegotiationsDashboard" ], "summary": "Accept, counter-propose, reject, get AI suggestions, record suggestion outcome, or update auto-accept threshold", "operationId": "manageNegotiation", "parameters": [ { "name": "action", "in": "query", "required": true, "description": "The negotiation management action to perform.", "schema": { "type": "string", "enum": [ "accept", "counter", "reject", "suggest", "record_outcome", "update_threshold" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "AcceptRequest", "description": "Accept a negotiation proposal (action=accept).", "type": "object", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "ID of the deal whose latest proposal to accept." } } }, { "title": "CounterRequest", "description": "Submit a counter-proposal (action=counter).", "type": "object", "required": [ "deal_id", "proposed_terms" ], "properties": { "deal_id": { "type": "string", "description": "ID of the deal to counter." }, "proposed_terms": { "type": "object", "description": "New proposed terms (e.g. price, discount_pct, duration).", "additionalProperties": true }, "message": { "type": "string", "description": "Optional message to the buyer explaining the counter-offer." }, "expires_at": { "type": "string", "format": "date-time", "description": "Optional ISO 8601 expiry datetime for the counter-offer." } } }, { "title": "RejectRequest", "description": "Reject a negotiation proposal (action=reject).", "type": "object", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "ID of the deal to reject." }, "reason": { "type": "string", "description": "Optional reason for rejection communicated to the buyer." } } }, { "title": "SuggestRequest", "description": "Get AI-generated counter-proposal suggestions for a deal (action=suggest).", "type": "object", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "ID of the deal to generate suggestions for." }, "current_terms": { "type": "object", "description": "Current terms to base suggestions on. Defaults to the latest negotiation round if omitted.", "additionalProperties": true } } }, { "title": "RecordOutcomeRequest", "description": "Record the outcome of an AI-generated suggestion (action=record_outcome).", "type": "object", "required": [ "suggestion_id", "outcome" ], "properties": { "suggestion_id": { "type": "string", "description": "ID of the AI suggestion whose outcome is being recorded." }, "outcome": { "type": "string", "enum": [ "applied", "ignored", "dismissed", "accepted_deal", "rejected_deal" ], "description": "What happened with the suggestion." }, "actual_terms": { "type": "object", "description": "The actual terms used when outcome is `applied`.", "additionalProperties": true }, "dismiss_reason": { "type": "string", "maxLength": 500, "description": "Reason for dismissal when outcome is `dismissed`." } } }, { "title": "UpdateThresholdRequest", "description": "Update the auto-accept threshold for a widget (action=update_threshold).", "type": "object", "required": [ "widget_id" ], "properties": { "widget_id": { "type": "string", "description": "ID of the widget config to update." }, "auto_accept_threshold": { "type": "number", "minimum": 0, "maximum": 100, "nullable": true, "description": "Auto-accept threshold as a percentage (0\u2013100). Set to null to disable auto-accept." } } } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "description": "Performs a negotiation management action. Use `action=accept` to accept a proposal, `action=counter` to submit a counter-offer, `action=reject` to decline, `action=suggest` to get AI counter-proposal suggestions, `action=record_outcome` to track AI suggestion effectiveness, or `action=update_threshold` to configure the auto-accept threshold." } }, "/onboarding": { "post": { "tags": [ "Onboarding" ], "summary": "Complete onboarding wizard or create new workspace", "operationId": "completeOnboarding", "parameters": [ { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "new-workspace" ] }, "description": "Pass mode=new-workspace to create an additional workspace for an already-authenticated user instead of a new account signup" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "first_name", "last_name", "email", "password" ], "properties": { "first_name": { "type": "string", "description": "User first name" }, "last_name": { "type": "string", "description": "User last name" }, "email": { "type": "string", "format": "email", "description": "User email address" }, "password": { "type": "string", "minLength": 8, "description": "User password (minimum 8 characters)" }, "business_name": { "type": "string", "description": "Business or workspace name (required for human accounts)" }, "industry": { "type": "string", "description": "Business industry (required for human accounts)" }, "services": { "type": "array", "description": "List of services offered (required for human accounts)", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "price_min": { "type": "number" }, "price_max": { "type": "number" } } } }, "deposit_percentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "Default deposit percentage (0-100)" }, "phone": { "type": "string", "description": "Business phone number" }, "website": { "type": "string", "description": "Business website URL" }, "country": { "type": "string", "default": "US", "description": "Two-letter country code" }, "region": { "type": "string", "enum": [ "au", "eu", "us" ], "description": "Data residency region" }, "account_type": { "type": "string", "enum": [ "human", "agent" ], "default": "human", "description": "Account type; agent accounts skip business field validation" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "201": { "description": "Onboarding completed successfully \u2014 tenant and user created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [], "description": "Processes an onboarding step in the new user or workspace creation wizard. Each call advances the wizard by one step. Returns the next step's fields and validation requirements." } }, "/payment-intent": { "post": { "tags": [ "Payments" ], "summary": "Create Stripe PaymentIntent for a deal's deposit or full amount", "operationId": "createPaymentIntent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "ID of the deal to create a payment intent for" }, "amount": { "type": "number", "description": "Explicit payment amount in the deal currency; defaults to deposit_required or full total" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntentResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "description": "Creates a Stripe PaymentIntent for a deal and returns the client secret for completing payment in the browser. The intent amount is derived from the deal total. Use `action=confirm` to confirm server-side, or `action=refund` to issue a refund." } }, "/plugins": { "get": { "tags": [ "Plugins" ], "summary": "List available or installed plugins", "operationId": "getPlugins", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns the list of available plugins from the Salesbooth marketplace and the installation status for the current tenant." }, "post": { "tags": [ "Plugins" ], "summary": "Install a plugin for the tenant", "operationId": "installPlugin", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Installs a plugin for the tenant. Provisions the plugin's database tables and registers it with the tenant's configuration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "plugin_id" ], "properties": { "plugin_id": { "type": "string", "description": "Identifier of the plugin to install (e.g. `analytics`, `channels`)" } } } } } } }, "delete": { "tags": [ "Plugins" ], "summary": "Uninstall a plugin for the tenant", "operationId": "uninstallPlugin", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Uninstalls a plugin for the tenant. Removes the plugin's data and deregisters it from the tenant's configuration." } }, "/preferences": { "get": { "tags": [ "Preferences" ], "summary": "Get user or tenant-user preferences", "operationId": "getPreferences", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:read" ] }, { "apiKeyHeader": [ "admin:read" ] }, { "sessionAuth": [] } ], "description": "Returns user and tenant preferences \u2014 display mode, language, and per-scope metadata preferences." }, "patch": { "tags": [ "Preferences" ], "summary": "Update user or tenant-user preferences", "operationId": "updatePreferences", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferencesUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:write" ] }, { "apiKeyHeader": [ "admin:write" ] }, { "sessionAuth": [] } ], "description": "Updates user or tenant preferences. Modify display mode, language preference, or per-scope metadata settings." } }, "/profile": { "get": { "tags": [ "Profile" ], "summary": "Get current user profile", "operationId": "getProfile", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns the current user's profile \u2014 name, email address, and phone number." }, "patch": { "tags": [ "Profile" ], "summary": "Update current user profile", "operationId": "updateProfile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Updates the current user's profile. Modify display name and phone number." }, "post": { "tags": [ "Profile" ], "summary": "Change current user password", "operationId": "changePassword", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "change-password" ] }, "description": "Must be `change-password`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "old_password", "new_password" ], "properties": { "old_password": { "type": "string", "description": "The user's current password" }, "new_password": { "type": "string", "minLength": 8, "description": "The new password (minimum 8 characters)" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Changes the current user's password. Requires the current password for verification. Use `action=change-password` query parameter." } }, "/queue": { "get": { "tags": [ "Queue" ], "summary": "Get queue stats, job status, or dead-letter list", "description": "Returns queue statistics by default. Use `action=status&job_id=X` to poll a specific job's state, attempts, timestamps, and error. Use `action=dead-letter` to list dead-lettered jobs with error details (max 100 per page).", "operationId": "getQueue", "parameters": [ { "name": "action", "in": "query", "description": "Operation: `status` (job status by job_id), `dead-letter` (list failed jobs), or omit for queue statistics", "schema": { "type": "string", "enum": [ "status", "dead-letter", "dead" ] } }, { "name": "job_id", "in": "query", "description": "Job ID to look up (required when action=status)", "schema": { "type": "string" } }, { "name": "tenant_id", "in": "query", "description": "Filter by tenant ID", "schema": { "type": "string" } }, { "name": "job_type", "in": "query", "description": "Filter dead-letter list by job type", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Page size for dead-letter list (max 100)", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Pagination offset for dead-letter list", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Successful response", "headers": { "X-Job-Id": { "description": "Job ID of any background job enqueued during this request", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueStatsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "queue:read" ] }, { "apiKeyHeader": [ "queue:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Queue" ], "summary": "Retry a dead-lettered job, purge completed jobs, or purge dead-letter jobs", "description": "Use `action=retry&job_id=X` to re-enqueue a dead-lettered job. Use `action=purge` to purge old completed jobs. Use `action=purge-dead-letter` to purge old dead-lettered jobs.", "operationId": "manageQueue", "parameters": [ { "name": "action", "in": "query", "required": true, "description": "Operation: `retry` (re-enqueue a dead-lettered job), `purge` (delete old completed jobs), or `purge-dead-letter` (delete old dead-lettered jobs)", "schema": { "type": "string", "enum": [ "retry", "purge", "purge-dead-letter" ] } }, { "name": "job_id", "in": "query", "description": "Job ID to retry (required when action=retry)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "queue:write" ] }, { "apiKeyHeader": [ "queue:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "Job ID to retry (for action=retry when not supplied as a query parameter)" }, "days": { "type": "integer", "minimum": 1, "description": "Retention period in days for purge operations (default 7)" }, "batch_size": { "type": "integer", "minimum": 1, "maximum": 50000, "description": "Maximum number of records to purge in a single call (default 10000)" } } } } } } } }, "/realtime-function": { "post": { "tags": [ "Realtime" ], "summary": "Execute function calls from OpenAI Realtime API voice assistant", "operationId": "executeRealtimeFunction", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Executes a function call within an active Realtime session. Used by the voice assistant to invoke server-side tools during a live conversation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "function" ], "properties": { "function": { "type": "string", "description": "Name of the function to execute (e.g. `list_customers`, `create_deal`)" }, "arguments": { "type": "object", "description": "Named arguments to pass to the function", "additionalProperties": true } } } } } } } }, "/realtime-session": { "post": { "tags": [ "Realtime" ], "summary": "Create ephemeral token for OpenAI Realtime API WebSocket connection", "operationId": "createRealtimeSession", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Creates a new OpenAI Realtime API session for the voice assistant. Returns session credentials and configuration for establishing a WebRTC or WebSocket connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "voice": { "type": "string", "enum": [ "alloy", "echo", "shimmer" ], "description": "OpenAI Realtime API voice to use", "default": "alloy" }, "instructions": { "type": "string", "description": "System instructions for the voice assistant session" }, "model": { "type": "string", "description": "OpenAI Realtime model identifier", "default": "gpt-4o-realtime-preview" } } } } } } } }, "/realtime-usage": { "post": { "tags": [ "Realtime" ], "summary": "Report token usage from realtime voice sessions", "operationId": "reportRealtimeUsage", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Records usage metrics for a completed Realtime session \u2014 token counts, audio duration, and latency data for billing and analytics.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "description": "Realtime session identifier to report usage for" }, "input_tokens": { "type": "integer", "minimum": 0, "description": "Number of input tokens consumed" }, "output_tokens": { "type": "integer", "minimum": 0, "description": "Number of output tokens generated" }, "duration_seconds": { "type": "integer", "minimum": 0, "description": "Session duration in seconds" }, "model": { "type": "string", "description": "Model identifier used for the session", "default": "gpt-4o-realtime-preview" }, "customer_id": { "type": "string", "description": "Customer ID associated with the session (optional)" }, "metadata": { "type": "object", "description": "Additional metadata to record with the usage entry", "additionalProperties": true } } } } } } } }, "/sandbox-toggle": { "get": { "tags": [ "Sandbox" ], "summary": "Get current sandbox/live mode status", "operationId": "getSandboxMode", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns the current sandbox mode status for the tenant \u2014 whether the tenant is operating in sandbox or live mode." }, "post": { "tags": [ "Sandbox" ], "summary": "Toggle between sandbox (test) and live mode", "operationId": "setSandboxMode", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Toggles the tenant between sandbox and live mode. In sandbox mode, payments are processed with test Stripe keys and no real charges occur.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "live", "test" ], "description": "`live`: switch to live/production mode; `test`: switch to sandbox/test mode" } } } } } } } }, "/search": { "get": { "tags": [ "Search" ], "summary": "Global search across customers, products, deals, and contracts", "operationId": "globalSearch", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Performs a cross-entity search across deals, customers, products, and contracts. Returns ranked results with entity type, ID, title, and match context. Supports field-level filtering and pagination." } }, "/site-blocks": { "get": { "tags": [ "SiteBlocks" ], "summary": "List or retrieve site blocks", "operationId": "getSiteBlocks", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns content blocks for a site page. Blocks are the atomic units of website content \u2014 hero sections, feature lists, testimonials, CTAs, etc." }, "post": { "tags": [ "SiteBlocks" ], "summary": "Create a new site block or update block status", "operationId": "createSiteBlock", "responses": { "200": { "description": "Block status updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "201": { "description": "Block created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Creates a new content block on a site, or updates the publish status of an existing block (`action=update_status`). Use the `action` field in the request body to select the operation (default: `create`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "create", "type": "object", "required": [ "site_id", "name" ], "properties": { "action": { "type": "string", "enum": [ "create" ], "default": "create", "description": "Action selector. Omit or set to `create` to create a new block." }, "site_id": { "type": "string", "maxLength": 50, "description": "ID of the site this block belongs to" }, "name": { "type": "string", "maxLength": 255, "description": "Display name for the block" }, "slug": { "type": "string", "maxLength": 255, "description": "URL-safe identifier for the block (auto-generated from name if omitted)" }, "category": { "type": "string", "maxLength": 100, "description": "Category label used for organising blocks" }, "content": { "type": "string", "maxLength": 65535, "description": "HTML or structured content for the block" }, "status": { "type": "string", "enum": [ "active", "draft", "disabled" ], "default": "draft", "description": "Publication status of the block" }, "description": { "type": "string", "maxLength": 500, "description": "Optional description of the block's purpose" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Display order relative to other blocks in the same category" } } }, { "title": "update_status", "type": "object", "required": [ "action", "block_id", "status" ], "properties": { "action": { "type": "string", "enum": [ "update_status" ], "description": "Action selector. Set to `update_status` to change a block's publish status." }, "block_id": { "type": "string", "maxLength": 50, "description": "ID of the block to update" }, "status": { "type": "string", "enum": [ "active", "draft", "disabled" ], "description": "New publish status for the block" } } } ] } } } } }, "patch": { "tags": [ "SiteBlocks" ], "summary": "Update a site block", "operationId": "updateSiteBlock", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteBlockUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Updates a content block by ID. Modify block content, layout, visibility, or display order." }, "delete": { "tags": [ "SiteBlocks" ], "summary": "Delete a site block", "operationId": "deleteSiteBlock", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Deletes a content block by ID." } }, "/site-pages": { "get": { "tags": [ "SitePages" ], "summary": "List or retrieve site pages", "operationId": "getSitePages", "parameters": [ { "name": "site_id", "in": "query", "description": "Filter pages by site ID", "schema": { "type": "string" } }, { "name": "page", "in": "query", "description": "Page number for pagination (default: 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "description": "Number of pages per result page (default: 30, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns pages for a tenant site. Each page has a URL slug, SEO metadata, and associated content blocks." }, "post": { "tags": [ "SitePages" ], "summary": "Create a new site page", "operationId": "createSitePage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "title": "create", "type": "object", "required": [ "site_id", "title" ], "properties": { "action": { "type": "string", "enum": [ "create" ], "default": "create", "description": "Action selector. Omit or set to `create` to create a new page." }, "site_id": { "type": "string", "maxLength": 50, "description": "ID of the site this page belongs to" }, "title": { "type": "string", "maxLength": 255, "description": "Page title" }, "slug": { "type": "string", "maxLength": 255, "description": "URL slug for the page. Auto-generated from title if omitted." }, "status": { "type": "string", "enum": [ "published", "draft", "disabled" ], "default": "draft", "description": "Publication status of the page" }, "is_homepage": { "type": "boolean", "description": "Whether this page is the site homepage" }, "source": { "type": "string", "maxLength": 65535, "description": "Published HTML source of the page" }, "dev_source": { "type": "string", "maxLength": 65535, "description": "Draft/development HTML source of the page" }, "meta_title": { "type": "string", "maxLength": 255, "description": "SEO meta title. Defaults to page title if omitted." }, "meta_description": { "type": "string", "maxLength": 500, "description": "SEO meta description" } } }, { "title": "update_status", "type": "object", "required": [ "action", "page_id", "status" ], "properties": { "action": { "type": "string", "enum": [ "update_status" ], "description": "Action selector. Set to `update_status` to change a page's publication status." }, "page_id": { "type": "string", "maxLength": 50, "description": "ID of the page to update" }, "status": { "type": "string", "enum": [ "published", "draft", "disabled" ], "description": "New publication status for the page" } } } ] } } } }, "responses": { "201": { "description": "Page created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "sessionAuth": [] } ], "description": "Creates a new page on the tenant site, or updates the status of an existing page. Use the `action` field to select the operation (default: `create`)." }, "patch": { "tags": [ "SitePages" ], "summary": "Update a site page", "operationId": "updateSitePage", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Page ID to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Page title" }, "slug": { "type": "string", "maxLength": 255, "description": "URL slug for the page" }, "status": { "type": "string", "enum": [ "published", "draft", "disabled" ], "description": "Publication status of the page" }, "is_homepage": { "type": "boolean", "description": "Whether this page is the site homepage" }, "source": { "type": "string", "maxLength": 65535, "description": "Published HTML source of the page" }, "dev_source": { "type": "string", "maxLength": 65535, "description": "Draft/development HTML source of the page" }, "meta_title": { "type": "string", "maxLength": 255, "description": "SEO meta title" }, "meta_description": { "type": "string", "maxLength": 500, "description": "SEO meta description" } } } } } }, "responses": { "200": { "description": "Page updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Updates a site page by ID. Modify the slug, SEO metadata, or publish status." }, "delete": { "tags": [ "SitePages" ], "summary": "Delete a site page", "operationId": "deleteSitePage", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Deletes a site page by ID." } }, "/sites": { "get": { "tags": [ "Sites" ], "summary": "List or retrieve sites", "operationId": "getSites", "responses": { "200": { "description": "List of sites", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } }, "required": [ "error", "success", "data" ] }, { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Site" } }, "required": [ "error", "success", "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Site ID for single-site retrieval" } ], "description": "Returns hosted website configurations for the tenant. Each site has a domain, theme, and associated pages." }, "post": { "tags": [ "Sites" ], "summary": "Create a new site", "operationId": "createSite", "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "201": { "description": "Site created", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "site_id": { "type": "string" }, "provision_warning": { "type": "string", "description": "Non-fatal provisioning warning, if any" } }, "required": [ "site_id" ] } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "maxLength": 253, "description": "Domain name for the site (e.g. mystore.com)", "example": "mystore.com" }, "name": { "type": "string", "maxLength": 255, "description": "Display name for the site", "example": "My Store" }, "status": { "type": "string", "enum": [ "coming_soon", "active", "inactive" ], "default": "coming_soon" }, "settings": { "type": "object", "description": "Optional site settings (max depth 3, max 8192 bytes)" } } } } } }, "description": "Creates a new hosted website configuration for the tenant. Specify the site domain, theme, and initial settings." }, "patch": { "tags": [ "Sites" ], "summary": "Update a site", "operationId": "updateSite", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "New domain name" }, "name": { "type": "string", "description": "Display name" }, "status": { "type": "string", "enum": [ "active", "inactive", "coming_soon" ] }, "analytics_enabled": { "type": "boolean" }, "settings": { "type": "object" } } } } } }, "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Site ID" } ], "description": "Updates a site configuration by ID. Modify domain, theme settings, or publish status." }, "delete": { "tags": [ "Sites" ], "summary": "Delete a site", "operationId": "deleteSite", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Site ID" } ], "description": "Deletes a hosted website configuration and all its pages and blocks." } }, "/switch-tenant": { "post": { "tags": [ "Tenants" ], "summary": "Switch to a different accessible tenant", "operationId": "switchTenant", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "tenant_id" ], "properties": { "tenant_id": { "type": "string", "description": "ID of the tenant to switch to" }, "tab_id": { "type": "string", "description": "Browser tab ID for per-tab tenant context tracking" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Switches the active tenant context for the current session. Used when a user belongs to multiple tenant accounts to change the active workspace." } }, "/system-admin": { "get": { "tags": [ "SystemAdmin" ], "summary": "Get system stats, tenant list, or system settings (system admin only)", "operationId": "getSystemAdmin", "parameters": [ { "name": "action", "in": "query", "required": true, "description": "Operation to retrieve: `stats` (system-wide statistics), `tenants` (list all tenants), `tenant` (single tenant detail, requires `id`), `settings` (all system settings), `tenant-settings` (tenant-scoped settings, requires `id`), `key-rotation-status` (key rotation state for a tenant, requires `id`), or `credit-ledger` (credit history for a tenant, requires `id`)", "schema": { "type": "string", "enum": [ "stats", "tenants", "tenant", "settings", "tenant-settings", "key-rotation-status", "credit-ledger" ] } }, { "name": "id", "in": "query", "required": false, "description": "Tenant ID \u2014 required when action is `tenant`, `tenant-settings`, `key-rotation-status`, or `credit-ledger`", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns system administration data for superadmin accounts \u2014 tenant list, usage metrics, and system health summary." }, "post": { "tags": [ "SystemAdmin" ], "summary": "Impersonate tenant, manage settings, rotate keys, or grant credits (system admin only)", "operationId": "manageSystemAdmin", "parameters": [ { "name": "action", "in": "query", "required": true, "description": "Operation to perform: `impersonate` (switch to tenant context), `stop-impersonate` (end impersonation), `settings` (save a system setting), `tenant-settings` (save a tenant-scoped setting), `rotate-keys` (start key rotation for a tenant), `resume-key-rotation` (continue a paused rotation), or `grant-credits` (credit a tenant account)", "schema": { "type": "string", "enum": [ "impersonate", "stop-impersonate", "settings", "tenant-settings", "rotate-keys", "resume-key-rotation", "grant-credits" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "tenant_id": { "type": "string", "description": "Target tenant ID (required for: impersonate, tenant-settings, rotate-keys, grant-credits)" }, "key": { "type": "string", "description": "Setting key (required for: settings, tenant-settings)" }, "value": { "description": "Setting value \u2014 any scalar or object (required for: settings, tenant-settings)" }, "rotation_id": { "type": "integer", "description": "Key rotation ID to resume (required for: resume-key-rotation)" }, "amount": { "type": "number", "description": "Credit amount in USD, max $10,000 (required for: grant-credits)" }, "reason": { "type": "string", "description": "Reason for granting credits (required for: grant-credits)" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Performs a system administration action. Requires superadmin privileges." } }, "/tenant-context": { "get": { "tags": [ "Tenants" ], "summary": "Get per-tab tenant context", "operationId": "getTenantContext", "parameters": [ { "name": "action", "in": "query", "required": true, "description": "Must be `get` \u2014 returns the tenant context (tenant ID, name, slug) for the specified browser tab.", "schema": { "type": "string", "enum": [ "get" ] } }, { "name": "tab_id", "in": "query", "required": true, "description": "Browser tab identifier. The server resolves the active tenant for this tab, falling back to the user's default tenant.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tenant context for the specified tab", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "tab_id": { "type": "string", "description": "The browser tab identifier" }, "tenant_id": { "type": "string", "nullable": true, "description": "Active tenant ID for this tab, or null if none" }, "tenant_name": { "type": "string", "nullable": true, "description": "Display name of the active tenant" }, "tenant_slug": { "type": "string", "nullable": true, "description": "URL slug of the active tenant" } }, "required": [ "tab_id" ] } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns the active tenant context for a specific browser tab \u2014 tenant ID, display name, and slug. The tab-to-tenant mapping is stored server-side in session; if no mapping exists the user's default tenant is used and the mapping is created." }, "post": { "tags": [ "Tenants" ], "summary": "Set or clear per-tab tenant context", "operationId": "setTenantContext", "parameters": [ { "name": "action", "in": "query", "required": true, "description": "Operation to perform: `set` binds a tenant to the given tab (requires `tab_id` and `tenant_id` in the request body); `clear` removes the tenant binding for the tab (requires `tab_id` in the request body).", "schema": { "type": "string", "enum": [ "set", "clear" ] } } ], "requestBody": { "required": true, "description": "Tab identifier and (for action=set) the tenant to bind.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "SetTenantContext", "description": "Used when action=set. Binds tenant_id to tab_id in the session. The user must be an active member of the target tenant.", "type": "object", "required": [ "tab_id", "tenant_id" ], "properties": { "tab_id": { "type": "string", "description": "Browser tab identifier" }, "tenant_id": { "type": "string", "description": "Tenant ID to bind to this tab" } } }, { "title": "ClearTenantContext", "description": "Used when action=clear. Removes the tenant binding for the specified tab from the session.", "type": "object", "required": [ "tab_id" ], "properties": { "tab_id": { "type": "string", "description": "Browser tab identifier to unbind" } } } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Modifies the per-tab tenant binding stored in the server session. Use action=set to associate a tenant with a browser tab (the user must have an active membership in that tenant). Use action=clear to remove the binding so the tab falls back to the user's default tenant on the next request." } }, "/analytics-settings": { "get": { "tags": [ "AnalyticsSettings" ], "summary": "Get analytics tracking settings for this tenant", "operationId": "getAnalyticsSettings", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:read" ] }, { "apiKeyHeader": [ "admin:read" ] }, { "sessionAuth": [] } ], "description": "Returns the current analytics tracking settings for the tenant, including which tracking features are enabled and privacy configuration options." }, "patch": { "tags": [ "AnalyticsSettings" ], "summary": "Update analytics tracking settings for this tenant", "operationId": "updateAnalyticsSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsSettingsUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:write" ] }, { "apiKeyHeader": [ "admin:write" ] }, { "sessionAuth": [] } ], "description": "Updates analytics tracking settings for the tenant. Toggle session replay, heatmaps, conversion funnel tracking, and configure data retention periods." } }, "/tenant-settings": { "get": { "tags": [ "TenantSettings" ], "summary": "Get tenant-level settings", "operationId": "getTenantSettings", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:read" ] }, { "apiKeyHeader": [ "admin:read" ] }, { "sessionAuth": [] } ], "description": "Returns the current tenant settings \u2014 business name, logo, currency, locale, and feature configuration." }, "patch": { "tags": [ "TenantSettings" ], "summary": "Update tenant-level settings", "operationId": "updateTenantSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantSettingsUpdateRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "admin:write" ] }, { "apiKeyHeader": [ "admin:write" ] }, { "sessionAuth": [] } ], "description": "Updates tenant-level settings. Modify business name, branding, default currency, notification preferences, and feature flags." } }, "/tenants": { "get": { "tags": [ "Tenants" ], "summary": "List all tenants accessible by the current user", "operationId": "getTenants", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantsListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns a list of tenants accessible to the authenticated user. For multi-tenant users, shows all workspaces they belong to along with their roles." } }, "/tts": { "post": { "tags": [ "TTS" ], "summary": "Convert text to speech using OpenAI TTS", "operationId": "textToSpeech", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 4096, "description": "Text to convert to speech" }, "voice": { "type": "string", "enum": [ "nova", "alloy", "echo", "fable", "onyx", "shimmer" ], "default": "nova", "description": "OpenAI TTS voice to use" }, "stream": { "type": "boolean", "default": false, "description": "Stream raw MP3 audio directly instead of returning base64 JSON" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Converts text to speech audio using the configured TTS provider. Returns a base64-encoded audio payload or a streaming audio response for voice UI components." } }, "/twilio": { "get": { "tags": [ "Twilio" ], "summary": "Get Twilio configuration status or communication history", "operationId": "getTwilioSettings", "description": "Returns Twilio integration data for the tenant. Use `action=settings` to retrieve configuration status (registered phone numbers, messaging service SID, SMS/voice settings). Use `action=history` to retrieve the communication history log with optional filters.", "parameters": [ { "name": "action", "in": "query", "required": true, "description": "Sub-resource to retrieve. `settings` returns Twilio configuration status. `history` returns the communication history log.", "schema": { "type": "string", "enum": [ "settings", "history" ] } }, { "name": "type", "in": "query", "description": "Filter history by communication type. Only applies when `action=history`.", "required": false, "schema": { "type": "string", "enum": [ "sms", "call", "email" ] } }, { "name": "customer_id", "in": "query", "description": "Filter history by customer ID. Only applies when `action=history`.", "required": false, "schema": { "type": "string" } }, { "name": "deal_id", "in": "query", "description": "Filter history by deal ID. Only applies when `action=history`.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of history records to return (default 20). Only applies when `action=history`.", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Pagination offset for history records. Only applies when `action=history`.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ] }, "post": { "tags": [ "Twilio" ], "summary": "Save Twilio settings or send SMS, voice call, or email", "operationId": "manageTwilio", "description": "Perform a Twilio communication action or update configuration. Use `action=settings` to save Twilio credentials. Use `action=sms` to send an SMS message. Use `action=call` to initiate a voice call. Use `action=email` to send an email via SendGrid.", "parameters": [ { "name": "action", "in": "query", "required": true, "description": "Action to perform. `settings` saves Twilio credentials (account SID, auth token, phone number). `sms` sends an SMS to a recipient phone number. `call` initiates an outbound voice call with a spoken message. `email` sends an email via SendGrid.", "schema": { "type": "string", "enum": [ "settings", "sms", "call", "email" ] } } ], "requestBody": { "required": true, "description": "Request body varies by action. For `settings`: Twilio credentials. For `sms`/`call`: recipient phone number and message. For `email`: recipient address, subject, and body.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "SaveSettings", "type": "object", "description": "Save Twilio credentials (`action=settings`).", "properties": { "account_sid": { "type": "string", "description": "Twilio Account SID" }, "auth_token": { "type": "string", "description": "Twilio Auth Token" }, "phone_number": { "type": "string", "description": "Twilio phone number in E.164 format" } } }, { "title": "SendSMS", "type": "object", "description": "Send an SMS message (`action=sms`).", "required": [ "to", "message" ], "properties": { "to": { "type": "string", "description": "Recipient phone number in E.164 format" }, "message": { "type": "string", "description": "SMS message body" }, "customer_id": { "type": "string", "description": "Customer ID to associate with this communication" }, "deal_id": { "type": "string", "description": "Deal ID to associate with this communication" } } }, { "title": "MakeCall", "type": "object", "description": "Initiate a voice call (`action=call`).", "required": [ "to", "message" ], "properties": { "to": { "type": "string", "description": "Phone number to call in E.164 format" }, "message": { "type": "string", "description": "Text to be spoken during the call (TTS)" }, "customer_id": { "type": "string", "description": "Customer ID to associate with this communication" }, "deal_id": { "type": "string", "description": "Deal ID to associate with this communication" } } }, { "title": "SendEmail", "type": "object", "description": "Send an email (`action=email`).", "required": [ "to", "subject", "body" ], "properties": { "to": { "type": "string", "format": "email", "description": "Recipient email address" }, "subject": { "type": "string", "description": "Email subject line" }, "body": { "type": "string", "description": "Email body content" }, "customer_id": { "type": "string", "description": "Customer ID to associate with this communication" }, "deal_id": { "type": "string", "description": "Deal ID to associate with this communication" } } } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ] } }, "/usage": { "get": { "tags": [ "Usage" ], "summary": "Get usage logs, monthly summary, or daily breakdown", "operationId": "getUsage", "parameters": [ { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "logs", "summary", "daily", "history", "quotas" ] }, "description": "Sub-action: `logs` (default) for paginated usage logs, `summary` for a monthly aggregate, `daily` for per-day chart data, `history` for multi-period summaries, `quotas` for budget limits and current spend" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Period filter for `action=history`. Accepts `YYYY` for a full year or `YYYY-MM` for a single month. Omit for the last 12 calendar months." }, { "name": "service", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by service name (e.g. `sms`, `ai_chat`). Applies to `logs` and `daily` actions." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "description": "Number of days for `action=daily`." }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start date filter for `action=logs` (inclusive). Format: `YYYY-MM-DD`." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End date filter for `action=logs` (inclusive). Format: `YYYY-MM-DD`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 }, "description": "Maximum number of log entries to return for `action=logs`. Defaults to 100, capped at 1000." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of log entries to skip for `action=logs` pagination. Defaults to 0." } ], "responses": { "200": { "description": "Successful response. Shape depends on the `action` parameter.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Response for action=logs (default). Returns paginated usage log entries.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object", "properties": { "log_id": { "type": "string" }, "service": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "tokens_input": { "type": "integer", "nullable": true }, "tokens_output": { "type": "integer", "nullable": true }, "tokens_total": { "type": "integer", "nullable": true }, "message_count": { "type": "integer", "nullable": true }, "duration_seconds": { "type": "integer", "nullable": true }, "characters_count": { "type": "integer", "nullable": true }, "cost_cents": { "type": "integer", "nullable": true }, "model": { "type": "string", "nullable": true }, "provider": { "type": "string", "nullable": true }, "customer_id": { "type": "string", "nullable": true }, "session_id": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of matching log entries" }, "limit": { "type": "integer", "description": "Page size used for this request" }, "offset": { "type": "integer", "description": "Number of entries skipped" }, "count": { "type": "integer", "description": "Number of entries returned in this page" } }, "required": [ "total", "limit", "offset", "count" ] } }, "required": [ "logs", "pagination" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Response for action=summary. Returns aggregate usage for a calendar month.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "summary": { "type": "object", "properties": { "period": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer" } }, "required": [ "year", "month" ] }, "by_service": { "type": "object", "description": "Per-service usage breakdown keyed by service name (e.g. `sms`, `ai_chat`).", "additionalProperties": { "type": "object", "properties": { "requests": { "type": "integer" }, "inbound": { "type": "integer" }, "outbound": { "type": "integer" }, "tokens_input": { "type": "integer" }, "tokens_output": { "type": "integer" }, "tokens_total": { "type": "integer" }, "messages": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "cost_cents": { "type": "integer" } } } }, "totals": { "type": "object", "properties": { "requests": { "type": "integer" }, "tokens_input": { "type": "integer" }, "tokens_output": { "type": "integer" }, "tokens_total": { "type": "integer" }, "messages": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "cost_cents": { "type": "integer" } } } } } }, "required": [ "summary" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Response for action=daily. Returns per-day usage data suitable for chart rendering.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "service": { "type": "string" }, "requests": { "type": "integer" }, "tokens_input": { "type": "integer" }, "tokens_output": { "type": "integer" }, "messages": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "cost_cents": { "type": "integer" } } } }, "days": { "type": "integer", "description": "Number of days included in the response" }, "service": { "type": "string", "nullable": true, "description": "Service filter applied, or null for all services" } }, "required": [ "daily", "days", "service" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Response for action=history. Returns monthly summaries for up to 12 periods.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "history": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer" } }, "required": [ "year", "month" ] }, "by_service": { "type": "object", "description": "Per-service totals for this period.", "additionalProperties": { "type": "object", "properties": { "requests": { "type": "integer" }, "tokens_input": { "type": "integer" }, "tokens_output": { "type": "integer" }, "tokens_total": { "type": "integer" }, "messages": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "cost_cents": { "type": "integer" } } } }, "totals": { "type": "object", "properties": { "requests": { "type": "integer" }, "tokens_input": { "type": "integer" }, "tokens_output": { "type": "integer" }, "tokens_total": { "type": "integer" }, "messages": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "cost_cents": { "type": "integer" } } } } } }, "period": { "type": "string", "nullable": true, "description": "Period filter applied (`YYYY` or `YYYY-MM`), or null for the last 12 months" } }, "required": [ "history", "period" ] } }, "required": [ "error", "success", "data" ] }, { "type": "object", "description": "Response for action=quotas. Returns budget limits, current-month spend, and per-service totals.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "monthly_budget": { "type": "object", "properties": { "limit_cents": { "type": "integer", "description": "Monthly spend limit in cents" }, "spent_cents": { "type": "integer", "description": "Amount spent so far this month in cents" }, "remaining_cents": { "type": "integer", "description": "Remaining budget in cents (floored at 0)" }, "percent_used": { "type": "number", "description": "Percentage of the monthly budget consumed" } }, "required": [ "limit_cents", "spent_cents", "remaining_cents", "percent_used" ] }, "alert_thresholds": { "type": "array", "items": { "type": "integer" }, "description": "Percentage thresholds at which budget alerts are sent (e.g. [80, 100])" }, "current_period": { "type": "object", "properties": { "year": { "type": "integer" }, "month": { "type": "integer" } } }, "by_service": { "type": "object", "description": "Current-month usage breakdown keyed by service name.", "additionalProperties": { "type": "object" } }, "totals": { "type": "object", "properties": { "requests": { "type": "integer" }, "tokens_input": { "type": "integer" }, "tokens_output": { "type": "integer" }, "tokens_total": { "type": "integer" }, "messages": { "type": "integer" }, "duration_seconds": { "type": "integer" }, "cost_cents": { "type": "integer" } } } }, "required": [ "monthly_budget", "alert_thresholds", "current_period", "by_service", "totals" ] } }, "required": [ "error", "success", "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Returns API usage statistics for the tenant. Default (`action=logs`) returns paginated usage logs. Use `action=summary` for a monthly aggregate, `action=daily` for per-day chart data, `action=history` for multi-period summaries (last 12 months by default), or `action=quotas` for budget limits and current-month spend." } }, "/verify": { "post": { "tags": [ "Verify" ], "summary": "Verify a credential signature and status (public, no auth required)", "operationId": "verifyCredential", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [], "description": "Verifies an email address or phone number using a one-time code. Used during onboarding and account security flows.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "credential" ], "properties": { "credential": { "type": "object", "description": "W3C Verifiable Credential object to verify", "required": [ "@context", "type", "proof" ], "properties": { "@context": { "type": "array", "items": { "type": "string" }, "description": "JSON-LD context URIs" }, "type": { "type": "array", "items": { "type": "string" }, "description": "Credential type identifiers" }, "proof": { "type": "object", "description": "Cryptographic proof object" } } } } } } } } } }, "/widget-contract": { "post": { "tags": [ "WidgetContract" ], "summary": "Generate contract HTML from template or capture digital signature", "operationId": "generateWidgetContract", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "201": { "description": "Contract generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [], "description": "Returns or generates the contract terms for a widget session. Called by the embedded widget during the terms acceptance step to retrieve the contract text for the buyer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "deal_id" ], "properties": { "api_key": { "type": "string", "description": "Publishable API key (sb_pub_*). Can also be sent in the Authorization: Bearer header." }, "deal_id": { "type": "string", "description": "Deal ID to generate or sign a contract for" }, "customer_name": { "type": "string", "description": "Customer display name (for action=generate)" }, "customer_email": { "type": "string", "format": "email", "description": "Customer email address (for action=generate)" }, "template_id": { "type": "string", "description": "Contract template ID override (for action=generate)" }, "contract_id": { "type": "string", "description": "Contract ID to sign (required for action=sign)" }, "signer_name": { "type": "string", "description": "Signer display name (required for action=sign with signature_mode=type)" }, "signer_email": { "type": "string", "format": "email", "description": "Signer email address (for action=sign)" }, "signature_mode": { "type": "string", "enum": [ "checkbox", "type", "draw" ], "description": "Signature capture mode (for action=sign)", "default": "checkbox" }, "signature_image": { "type": "string", "description": "Base64-encoded PNG of the drawn signature (for action=sign with signature_mode=draw)" } } } } } } } }, "/widget-discount": { "post": { "tags": [ "WidgetDiscount" ], "summary": "Validate a promo code for widget checkout", "operationId": "validateDiscount", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [], "description": "Validates and applies a promotional discount code within a widget session. Returns the discount amount and updated pricing if the code is valid.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Promo code to validate" }, "subtotal": { "type": "number", "minimum": 0, "description": "Cart subtotal in the widget currency (used for percentage discount calculation and minimum order validation)" } } } } } } } }, "/widget-validate": { "post": { "tags": [ "WidgetValidate" ], "summary": "Validate product configuration for a headless widget session", "operationId": "validateWidgetConfiguration", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [], "description": "Validates a product configuration for a headless widget session. Checks compatibility rules (requires, excludes) and returns price adjustments from includes_price rules. Use before advancing to the payment step.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string", "description": "Product ID to validate the configuration for" }, "option_ids": { "type": "array", "items": { "type": "string" }, "description": "Selected option IDs to check against compatibility rules" } } } } } } } }, "/widget-payment-preview": { "post": { "tags": [ "WidgetPaymentPreview" ], "summary": "Preview payment breakdown for a headless widget cart", "operationId": "previewWidgetPayment", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [], "description": "Previews the payment amount for a headless widget cart, including subtotal, tax, discounts, and deposit breakdown. Returns the charge amount the customer will be billed immediately (full total or deposit).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string", "description": "Product ID to calculate payment preview for" }, "option_ids": { "type": "array", "items": { "type": "string" }, "description": "Selected option IDs to include in price calculation" }, "quantity": { "type": "integer", "minimum": 1, "description": "Product quantity (default 1)", "default": 1 }, "promo_code": { "type": "string", "description": "Promo code to apply to the cart" } } } } } } } }, "/audit": { "get": { "tags": [ "Audit" ], "summary": "Retrieve immutable audit trail for a deal, contract, customer, or product", "operationId": "getAuditTrail", "parameters": [ { "name": "entity_type", "in": "query", "required": true, "description": "Type of entity to retrieve audit trail for", "schema": { "type": "string", "enum": [ "deal", "contract", "customer", "product" ] } }, { "name": "entity_id", "in": "query", "required": true, "description": "ID of the entity", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "Set to 'verify' to verify hash chain integrity", "schema": { "type": "string", "enum": [ "verify" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Audit trail entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "description": "Returns the immutable audit trail for the tenant. Each entry records who performed an action, what changed, and when. Supports filtering by entity type, date range, and actor. Use `action=export` to download the full trail as CSV." } }, "/email-webhook": { "post": { "tags": [ "Channels" ], "summary": "Receive inbound email from SendGrid or Mailgun", "operationId": "handleEmailWebhook", "security": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "description": "Inbound email payload from SendGrid or Mailgun" } } } }, "responses": { "200": { "description": "Webhook received and queued for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "405": { "description": "Method not allowed \u2014 only POST is accepted" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "description": "Accepts inbound email from SendGrid or Mailgun. All requests are verified using cryptographic signatures (Mailgun: HMAC-SHA256; SendGrid: ECDSA P-256) before any data is processed." } }, "/twilio-webhook": { "post": { "tags": [ "Twilio" ], "summary": "Receive inbound SMS, voice calls, and status callbacks from Twilio", "description": "All requests must carry a valid X-Twilio-Signature header (HMAC-SHA1). Tenant is resolved from the To/Called field in the POST body \u2014 the tenant_id query parameter is no longer accepted.", "operationId": "handleTwilioWebhook", "security": [], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Webhook type: sms, voice, status, sms_status, or voice_status", "schema": { "type": "string", "enum": [ "sms", "voice", "status", "sms_status", "voice_status" ], "default": "sms" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "description": "Twilio webhook POST payload" } } } }, "responses": { "200": { "description": "Webhook received and processed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "description": "Method not allowed \u2014 only POST is accepted" } } } }, "/delegations/proposals": { "get": { "operationId": "listPendingProposals", "summary": "List pending delegation proposals targeting this agent", "description": "Returns pending proposals where the authenticated agent is the target. Requires agent API key auth and delegations:read scope.", "tags": [ "Delegations" ], "security": [ { "bearerAuth": [ "delegations:read" ] }, { "apiKeyHeader": [ "delegations:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Pending proposals list", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "proposals": { "type": "array", "items": { "$ref": "#/components/schemas/DelegationProposal" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "proposeAgentDelegation", "summary": "Propose agent-to-agent delegation", "description": "Agent A proposes a delegation to Agent B. Requires trust level 2+ and the delegate action in proposer's own delegation scope.", "tags": [ "Delegations" ], "security": [ { "bearerAuth": [ "delegations:write" ] }, { "apiKeyHeader": [ "delegations:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_api_key_id", "proposed_actions" ], "properties": { "target_api_key_id": { "type": "string", "description": "API key ID of target agent" }, "proposed_actions": { "type": "array", "items": { "type": "string" } }, "max_transaction_amount": { "type": "number" }, "max_daily_amount": { "type": "number" }, "max_monthly_amount": { "type": "number" }, "proposed_duration_hours": { "type": "integer" }, "message": { "type": "string" } } } } } }, "responses": { "201": { "description": "Proposal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationProposal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/delegations/proposals/{id}/accept": { "post": { "operationId": "acceptDelegationProposal", "summary": "Accept a pending delegation proposal", "description": "Target agent accepts, creating an actual delegation. Requires agent API key auth.", "tags": [ "Delegations" ], "security": [ { "bearerAuth": [ "delegations:write" ] }, { "apiKeyHeader": [ "delegations:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Proposal accepted and delegation created", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "proposal": { "$ref": "#/components/schemas/DelegationProposal" }, "delegation": { "type": "object" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "description": "No request body required. The proposal ID is specified in the path.", "properties": {} } } } } } }, "/delegations/proposals/{id}/reject": { "post": { "operationId": "rejectDelegationProposal", "summary": "Reject a pending delegation proposal", "tags": [ "Delegations" ], "security": [ { "bearerAuth": [ "delegations:write" ] }, { "apiKeyHeader": [ "delegations:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Proposal rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationProposal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } }, "description": "Rejects a pending delegation proposal by ID. The proposing agent is notified of the rejection and the proposal is archived." } }, "/delegations/proposals/{id}/counter": { "post": { "operationId": "counterDelegationProposal", "summary": "Counter-propose delegation terms", "description": "Target agent proposes modified terms (subset of original). Creates a new proposal round.", "tags": [ "Delegations" ], "security": [ { "bearerAuth": [ "delegations:write" ] }, { "apiKeyHeader": [ "delegations:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "proposed_actions" ], "properties": { "proposed_actions": { "type": "array", "items": { "type": "string" } }, "max_transaction_amount": { "type": "number" }, "max_daily_amount": { "type": "number" }, "max_monthly_amount": { "type": "number" }, "proposed_duration_hours": { "type": "integer" }, "message": { "type": "string" } } } } } }, "responses": { "201": { "description": "Counter-proposal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DelegationProposal" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/usdc": { "get": { "tags": [ "USDC" ], "operationId": "getUsdc", "summary": "Get USDC balance, summary, or transaction history", "description": "Returns the agent's USDC balance and account summary (action=balance, default), or paginated transaction history (action=transactions). Human accounts can call this but the agent-specific fields will be empty.", "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "balance", "transactions" ] }, "description": "balance (default) or transactions" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number for transactions (1-based)" }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 }, "description": "Items per page for transactions" } ], "responses": { "200": { "description": "USDC balance and summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "is_agent": { "type": "boolean" }, "usdc_balance": { "type": "number", "description": "USDC balance with 6 decimal precision" }, "wallet_address": { "type": "string", "nullable": true, "description": "Connected Ethereum wallet address" }, "min_deposit": { "type": "number", "description": "Minimum deposit in USDC" }, "cost_per_request": { "type": "number", "description": "USDC deducted per billable request" }, "chain_id": { "type": "integer", "example": 8453, "description": "Base L2 chain ID" }, "usdc_contract": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "billing:read" ] }, { "apiKeyHeader": [ "billing:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "USDC" ], "operationId": "postUsdc", "summary": "Create a USDC deposit charge, set wallet address", "description": "action=create-charge: creates a Coinbase hosted checkout for crypto deposit (auto-converted to USDC). action=set-wallet: stores a verified Ethereum wallet address. action=coinbase-webhook: called by Coinbase CDP or Commerce (no API auth, verified via webhook signature).", "parameters": [ { "name": "action", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "create-charge", "set-wallet", "coinbase-webhook" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "title": "create-charge", "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "USD-equivalent amount to deposit as USDC (>= USDC_MIN_DEPOSIT, default 5)" } } }, { "title": "set-wallet", "type": "object", "required": [ "wallet_address" ], "properties": { "wallet_address": { "type": "string", "description": "Ethereum wallet address (0x + 40 hex chars)" } } } ] } } } }, "responses": { "201": { "description": "Charge created or wallet saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "charge_id": { "type": "string" }, "charge_code": { "type": "string" }, "hosted_url": { "type": "string", "description": "Coinbase checkout URL (accepts any supported crypto)" }, "amount_usdc": { "type": "number" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Payment Required \u2014 agent has insufficient USDC balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [ "billing:write" ] }, { "apiKeyHeader": [ "billing:write" ] }, { "sessionAuth": [] } ] } }, "/quotes": { "get": { "tags": [ "Documents" ], "summary": "Retrieve or list quotes", "description": "Public endpoint to retrieve a quote by its short code (no auth). Authenticated: retrieve a single quote by ID, list quotes for a deal via deal_id, or list all tenant quotes (no params).", "operationId": "getQuote", "parameters": [ { "name": "short_code", "in": "query", "description": "Short code from the shareable quote URL", "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Quote ID (quote_xxx)", "schema": { "type": "string" } }, { "name": "deal_id", "in": "query", "description": "When authenticated: list all quotes for this deal ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quote retrieved or listed successfully. Response shape depends on query params: public short_code returns a single quote object (7 fields); authenticated id returns a single quote with deal metadata (12 fields); authenticated deal_id or no params returns a quotes array wrapped in { quotes: [] }.", "content": { "application/json": { "schema": { "oneOf": [ { "title": "Single quote \u2014 public (short_code path)", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote_id": { "type": "string" }, "short_code": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "viewed", "accepted", "rejected", "expired" ] }, "validity_days": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "quote_data": { "type": "object", "description": "Full quote snapshot containing line items, customer, and pricing. Internal IDs (deal_id, customer_id) are stripped from the public response." }, "created_at": { "type": "string", "format": "date-time" } } } }, "required": [ "error", "success", "data" ] }, { "title": "Single quote \u2014 authenticated (id path)", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote_id": { "type": "string" }, "short_code": { "type": "string" }, "deal_id": { "type": "string" }, "deal_title": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "viewed", "accepted", "rejected", "expired" ] }, "validity_days": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "total": { "type": "number" }, "currency": { "type": "string" }, "quote_data": { "type": "object", "description": "Full quote snapshot containing line items, customer, and pricing." }, "created_at": { "type": "string", "format": "date-time" }, "share_url": { "type": "string", "format": "uri", "description": "Publicly shareable URL for the customer-facing quote viewer" } } } }, "required": [ "error", "success", "data" ] }, { "title": "Quote list \u2014 authenticated (deal_id or no params)", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quotes": { "type": "array", "description": "List of quotes for the deal or tenant (up to 50 per deal, 100 for tenant-wide)", "items": { "type": "object", "properties": { "quote_id": { "type": "string" }, "short_code": { "type": "string" }, "deal_id": { "type": "string" }, "deal_title": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "viewed", "accepted", "rejected", "expired" ] }, "validity_days": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" }, "total": { "type": "number" }, "currency": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "share_url": { "type": "string", "format": "uri" } } } } } } }, "required": [ "error", "success", "data" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ] }, "post": { "tags": [ "Documents" ], "summary": "Generate a quote or invoice from a deal", "description": "Generates a formal quote or invoice from a deal. Use action=generate_quote to create a shareable quote URL from any deal, or action=generate_invoice to create an invoice for closed/pending_payment deals.", "operationId": "generateQuote", "security": [ { "bearerAuth": [ "deals:read" ] }, { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "generate_quote", "generate_invoice" ], "description": "Action to perform" }, "deal_id": { "type": "string", "description": "Deal ID to generate quote/invoice from" }, "validity_days": { "type": "integer", "description": "Quote validity in days (generate_quote only, default 30)", "minimum": 1, "maximum": 365 } }, "required": [ "deal_id" ] } } } }, "responses": { "201": { "description": "Quote or invoice generated successfully. Response shape depends on action: generate_quote returns a quote object (10 fields); generate_invoice returns an invoice object (8 fields).", "content": { "application/json": { "schema": { "oneOf": [ { "title": "generate_quote response", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "quote_id": { "type": "string" }, "short_code": { "type": "string", "description": "URL-safe alphanumeric short code used in the share_url" }, "share_url": { "type": "string", "format": "uri", "description": "Publicly accessible customer-facing quote URL" }, "deal_id": { "type": "string" }, "status": { "type": "string", "enum": [ "sent" ], "description": "Newly generated quotes always start in 'sent' status" }, "line_items": { "type": "array", "description": "Snapshot of deal line items at time of quote generation", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number" }, "line_total": { "type": "number" } } } }, "total": { "type": "number" }, "currency": { "type": "string" }, "validity_days": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" } } } }, "required": [ "error", "success", "data" ] }, { "title": "generate_invoice response", "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "invoice_id": { "type": "string" }, "invoice_number": { "type": "string", "description": "Human-readable invoice number" }, "invoice_url": { "type": "string", "format": "uri", "description": "PDF download URL for the invoice" }, "deal_id": { "type": "string" }, "total": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string", "description": "Invoice status (e.g. draft, open, paid)" }, "already_existed": { "type": "boolean", "description": "True if an existing invoice was returned rather than a new one created" } } } }, "required": [ "error", "success", "data" ] } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/BadRequest" } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete a quote", "description": "Permanently deletes a quote by ID. The quote must belong to the authenticated tenant.", "operationId": "deleteQuote", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Quote ID (quote_xxx)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quote deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/deal-notifications": { "get": { "tags": [ "Documents" ], "summary": "Get customer contact preferences and recent notification history", "description": "Retrieves a customer's preferred contact channel, email/phone availability, marketing consent status, and their last 5 notifications. Use this before send_deal_notification to verify the customer can be reached.", "operationId": "getContactPreferences", "security": [ { "bearerAuth": [ "customers:read" ] }, { "apiKeyHeader": [ "customers:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "customer_id", "in": "query", "required": true, "description": "Customer ID (cust_xxx)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact preferences retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "customer_id": { "type": "string" }, "preferred_channel": { "type": "string", "enum": [ "email", "sms", "none" ] }, "has_email": { "type": "boolean" }, "has_phone": { "type": "boolean" }, "marketing_consent": { "type": "boolean" }, "recent_notifications": { "type": "array" } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Documents" ], "summary": "Send a notification to the deal's customer", "description": "Sends a notification to the customer of the specified deal via their preferred channel (email or SMS). Supports agent-specific notification types: quote_sent, invoice_sent, payment_reminder, deal_update, terms_updated. Rate limited to 10 notifications per hour per API key.", "operationId": "sendDealNotification", "security": [ { "bearerAuth": [ "deals:write" ] }, { "apiKeyHeader": [ "deals:write" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "Deal ID whose customer receives the notification" }, "type": { "type": "string", "enum": [ "quote_sent", "invoice_sent", "payment_reminder", "deal_update", "terms_updated" ], "description": "Notification type" }, "message": { "type": "string", "description": "Optional custom message (max 2000 chars)", "maxLength": 2000 } }, "required": [ "deal_id", "type" ] } } } }, "responses": { "201": { "description": "Notification sent successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "notification_id": { "type": "string", "nullable": true, "description": "ID of the created notification record, or null when status is no_contact" }, "status": { "type": "string", "enum": [ "sent", "failed", "no_contact" ] }, "channel": { "type": "string", "nullable": true, "enum": [ "email", "sms" ], "description": "Channel used for delivery, or null when status is no_contact" }, "rate_limit_remaining": { "type": "integer" }, "message": { "type": "string", "nullable": true, "description": "Human-readable reason when status is no_contact or failed" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/encryption-rotation": { "get": { "tags": [ "Security" ], "summary": "Get encryption key rotation status", "description": "Returns the current encryption key rotation status for the tenant, including how many records still need re-encryption and whether the previous key can be safely removed. Use ?action=rekey-status to get the status of the background system-wide re-encryption job. Requires admin scope.", "operationId": "getEncryptionRotationStatus", "security": [ { "bearerAuth": [ "admin" ] }, { "apiKeyHeader": [ "admin" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "rekey-status" ] }, "description": "Use 'rekey-status' to get the status of the background re-encryption job" } ], "responses": { "200": { "description": "Rotation status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Security" ], "summary": "Start or resume key rotation", "description": "Starts a key rotation for the tenant (or resumes a pending one). Re-encrypts all records from legacy key versions or from ENCRYPTION_KEY_PREVIOUS to the current master key. Use ?action=resume with a rotation_id body param to resume a specific rotation. Use ?action=start-rekey to start a background system-wide re-encryption job. Requires admin scope.", "operationId": "triggerEncryptionRotation", "security": [ { "bearerAuth": [ "admin" ] }, { "apiKeyHeader": [ "admin" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "start", "resume", "start-rekey" ] }, "description": "Use 'resume' with a rotation_id body param to resume a specific rotation. Use 'start-rekey' to initiate a background re-encryption sweep across all encrypted fields." }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rotation_id": { "type": "integer", "description": "ID of the rotation to resume (required for ?action=resume)" }, "batch_size": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Records per batch for start-rekey action" }, "records_per_second": { "type": "number", "minimum": 0.1, "description": "Rate limit: max records per second for start-rekey (null = unlimited)" } } } } } }, "responses": { "200": { "description": "Rotation started or completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/domain-register": { "post": { "tags": [ "Websites" ], "summary": "Register a new domain via Dreamscape Reseller API", "operationId": "registerDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "example": "example.com" }, "period": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "Registration period in years" } } } } } }, "responses": { "201": { "description": "Domain registered and site created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Domain already exists in account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Domain registration not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "sessionAuth": [] } ], "description": "Registers a domain name via the GoDaddy registrar integration. Provisions DNS records and links the domain to the tenant's hosted website." } }, "/simulate-pricing": { "post": { "tags": [ "PricingSimulation" ], "summary": "Simulate multi-product cart pricing with bundle discounts", "description": "Simulate bundle pricing for a multi-product cart. All operations are read-only \u2014 no deals are created. Bundle rules from the product catalog are applied server-side, mirroring headless SDK _checkBundles() logic. To compare multiple cart scenarios, use POST /simulate-pricing/compare.", "operationId": "simulateBundlePricing", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "description": "Cart items to simulate pricing for", "maxItems": 50, "items": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "option_ids": { "type": "array", "items": { "type": "string" } } } } }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "USD" }, "promo_code": { "type": "string", "description": "Optional promo code to simulate discount" } } } } } }, "responses": { "200": { "description": "Pricing simulation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "tags": [ "PricingSimulation" ], "summary": "Analyze historical negotiation patterns for a product or category", "description": "Returns aggregated negotiation analytics: average discount granted, typical round count, success rate by discount tier, and an optimal opening offer suggestion. Requires either product_id or category parameter.", "operationId": "analyzeNegotiationHistory", "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ], "parameters": [ { "name": "product_id", "in": "query", "description": "Filter by product ID (use this OR category)", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by product category (use this OR product_id)", "schema": { "type": "string" } }, { "name": "period_days", "in": "query", "description": "Lookback period in days (default 90, max 365)", "schema": { "type": "integer", "minimum": 1, "maximum": 365 } } ], "responses": { "200": { "description": "Negotiation history analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/simulate-pricing/compare": { "post": { "tags": [ "PricingSimulation" ], "summary": "Compare 2-4 pricing scenarios side by side", "description": "Compare 2 to 4 pricing scenarios side by side and rank them by total cost. Each scenario has a label and a list of cart items. Scenarios are ranked by total ascending (rank 1 = lowest total, i.e. best deal for buyer). All operations are read-only \u2014 no deals are created.", "operationId": "comparePricingScenarios", "security": [ { "bearerAuth": [ "products:read" ] }, { "apiKeyHeader": [ "products:read" ] }, { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scenarios" ], "properties": { "scenarios": { "type": "array", "description": "Cart scenarios to compare. Between 2 and 4 scenarios required.", "minItems": 2, "maxItems": 4, "items": { "type": "object", "required": [ "label", "items" ], "properties": { "label": { "type": "string", "description": "Human-readable name for this scenario" }, "items": { "type": "array", "description": "Cart items for this scenario", "items": { "type": "object", "required": [ "product_id" ], "properties": { "product_id": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "option_ids": { "type": "array", "items": { "type": "string" } } } } } } } }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "USD" } } } } } }, "responses": { "200": { "description": "Scenario comparison result sorted by savings_rank ascending", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "scenarios": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "savings_rank": { "type": "integer", "description": "Rank by total ascending (1 = lowest total / best deal for buyer)" }, "items": { "type": "array" }, "subtotal": { "type": "number" }, "bundle_discounts": { "type": "array" }, "bundle_discount_total": { "type": "number" }, "promo_discount": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string" }, "savings_vs_individual": { "type": "number" }, "compatibility_errors": { "type": "array" }, "simulation_only": { "type": "boolean", "example": true } } } } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/replays": { "delete": { "tags": [ "Replays" ], "summary": "Delete a session recording", "description": "Permanently removes a session recording row from the database and deletes the associated .jsonl event file from disk. The session must belong to the authenticated tenant.", "operationId": "deleteReplay", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "session_id", "in": "query", "description": "Session ID of the recording to delete", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Session recording deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "deleted": { "type": "boolean", "example": true }, "session_id": { "type": "string" } } } }, "required": [ "error", "success", "data" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "operationId": "listReplays", "summary": "List session recordings", "description": "Returns a paginated list of session recordings for the authenticated tenant, ordered by most recent activity.", "tags": [ "Replays" ], "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 200, "minimum": 1 }, "description": "Maximum number of recordings to return" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "Number of recordings to skip" } ], "responses": { "200": { "description": "List of session recordings", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "success", "data" ], "properties": { "error": { "type": "boolean", "example": false }, "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "replays": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "session_id": { "type": "string" }, "device": { "type": "string" }, "browser": { "type": "string" }, "duration": { "type": "integer" }, "updated": { "type": "string", "format": "date-time" } } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/deals/{id}/settlements": { "get": { "tags": [ "Deals" ], "summary": "Get revenue settlement breakdown for a deal", "description": "Returns all revenue settlement records for a closed deal, showing how the deal total was distributed among participants after platform fee deduction. Agent participants receive USDC; merchant participants receive Stripe Connect transfers.", "operationId": "getDealSettlements", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "string", "pattern": "^deal_[a-zA-Z0-9]+$" } } ], "responses": { "200": { "description": "Settlement records for this deal", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "settlements": { "type": "array", "items": { "$ref": "#/components/schemas/DealSettlement" } } } } }, "required": [ "error", "success", "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "bearerAuth": [ "deals:read" ] }, { "apiKeyHeader": [ "deals:read" ] }, { "sessionAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key passed as Bearer token. Format: `sb_live_*` (production) or `sb_test_*` (testing)." }, "customerBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Customer JWT obtained via /customer-auth magic link flow" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key passed via X-API-Key header. Format: `sb_live_*` or `sb_test_*`." }, "sessionAuth": { "type": "apiKey", "in": "cookie", "name": "PHPSESSID", "description": "Session cookie for browser-based requests. Required for API key management endpoints." } }, "headers": { "X-Salesbooth-Signature": { "description": "HMAC-SHA256 signature of the webhook payload. Format: `v1=`. Computed as `HMAC-SHA256(timestamp + '.' + body, webhook_secret)` where `webhook_secret` is the plaintext secret provided at registration.", "schema": { "type": "string", "pattern": "^v1=[a-f0-9]{64}$", "example": "v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" } }, "X-Salesbooth-Timestamp": { "description": "Unix timestamp (seconds) when the webhook was sent. Included in signature computation to prevent replay attacks. Integrators should reject deliveries where this timestamp is more than 5 minutes old.", "schema": { "type": "string", "pattern": "^[0-9]+$", "example": "1709500000" } }, "X-Salesbooth-Delivery-Id": { "description": "Unique delivery identifier for idempotency and deduplication. Format: `whd_`.", "schema": { "type": "string", "pattern": "^whd_[a-f0-9]+$", "example": "whd_a1b2c3d4e5f6a7b8" } }, "X-Salesbooth-Signature-Version": { "description": "Signature scheme version. Currently `v1`. Allows future algorithm upgrades without breaking existing integrations.", "schema": { "type": "string", "enum": [ "v1" ], "example": "v1" } }, "X-Salesbooth-Event": { "description": "The event type that triggered this webhook delivery.", "schema": { "type": "string", "example": "deal.created" } } }, "parameters": { "limit": { "name": "limit", "in": "query", "description": "Maximum number of results per page", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, "offset": { "name": "offset", "in": "query", "description": "Number of results to skip for pagination. Ignored when cursor parameters (after/before) are provided.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, "after": { "name": "after", "in": "query", "description": "Cursor for forward pagination. Pass the `next_cursor` value from a previous response to fetch the next page. When provided, offset-based pagination is disabled and keyset (cursor) pagination is used instead.", "required": false, "schema": { "type": "string" } }, "before": { "name": "before", "in": "query", "description": "Cursor for backward pagination. Pass the `prev_cursor` value from a previous response to fetch the previous page. When provided, offset-based pagination is disabled and keyset (cursor) pagination is used instead.", "required": false, "schema": { "type": "string" } }, "sort": { "name": "sort", "in": "query", "description": "Sort field for cursor-based pagination. Determines which timestamp column cursors reference. Default: `created_at`. Use `updated_at` for sync/polling workflows (\"give me everything changed since my last check\").", "required": false, "schema": { "type": "string", "enum": [ "created_at", "updated_at" ], "default": "created_at" } }, "ifMatch": { "name": "If-Match", "in": "header", "description": "Optimistic locking header. Must contain the resource's current ETag value (e.g. `W/\"3\"`). Required on PATCH and DELETE requests. Obtain the ETag from the GET response. If the version has changed since you last read the resource, the request will fail with 412 Precondition Failed.", "required": true, "schema": { "type": "string", "pattern": "^(W/)?\"[0-9]+\"$", "examples": [ "W/\"1\"", "W/\"3\"" ] } }, "xDelegationId": { "name": "X-Delegation-ID", "in": "header", "description": "Explicitly specify which delegation the agent is operating under. If omitted, the most recent active delegation for the API key is used.", "required": false, "schema": { "type": "string", "examples": [ "deleg_abc123def456" ] } }, "fields": { "name": "fields", "in": "query", "description": "Comma-separated list of fields to include in the response. Only specified fields (plus `id`) are returned. Unknown field names are silently ignored for forward compatibility. Example: `fields=id,status,total,customer_id`.", "required": false, "schema": { "type": "string", "examples": [ "id,status,total", "id,name,email,status" ] } }, "include": { "name": "include", "in": "query", "description": "Comma-separated list of nested resources to include. For single-resource endpoints, all nested resources are included by default; use this to request only specific ones. For list endpoints, no nested resources are included by default. Available nested resources vary by entity:\n- Deals: `customer`, `line_items`, `pricing`, `terms`, `payment`, `escrow`, `metadata`, `deal_score`\n- Customers: `deals`, `contracts`, `communications`, `activity_log`\n- Products: `deals`, `activity_log`\n- Contracts: `activity_log`", "required": false, "schema": { "type": "string", "examples": [ "line_items,pricing", "deals,activity_log" ] } }, "exclude": { "name": "exclude", "in": "query", "description": "Comma-separated list of nested resources to exclude from the response. Inverse of `include`. Example: `exclude=activity_log,deals` removes those nested resources from the response.", "required": false, "schema": { "type": "string", "examples": [ "activity_log", "deals,activity_log" ] } }, "format": { "name": "format", "in": "query", "description": "Response format shortcut. `minimal` returns only `id`, `status`, and `updated_at` \u2014 ideal for polling use cases.", "required": false, "schema": { "type": "string", "enum": [ "minimal" ] } }, "idempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "Client-generated unique key for safe request retries. If a request with the same key has already been processed, the cached response is returned with `Idempotency-Replayed: true`. Use a UUID v4 value and reuse the same key across retries. Keys expire after 24 hours. Required for AI agent integrations to prevent duplicate mutations on retries due to timeouts, network errors, or 5xx responses.", "required": false, "schema": { "type": "string", "maxLength": 255, "examples": [ "550e8400-e29b-41d4-a716-446655440000" ] } }, "validateOnly": { "name": "validate_only", "in": "query", "description": "When true, validates the request body without creating the resource. Returns `{valid: true, message: \"Validation passed\"}` on success without persisting any data.", "required": false, "schema": { "type": "boolean" } } }, "schemas": { "AgentWorkflow": { "type": "object", "description": "An agent workflow for autonomous deal orchestration with step-based async execution", "properties": { "workflow_id": { "type": "string", "description": "Unique workflow identifier (wf_xxx)" }, "intent": { "type": "string", "description": "Workflow intent (purchase)" }, "status": { "type": "string", "enum": [ "planned", "executing", "negotiating", "completed", "failed", "cancelled" ], "description": "Current workflow status" }, "delegation_id": { "type": "string", "description": "Delegation ID the workflow operates under" }, "constraints": { "type": "object", "description": "Workflow constraints (budget, categories, negotiation settings, customer)" }, "steps": { "type": "array", "description": "Workflow execution steps (discover \u2192 select \u2192 create_deal \u2192 negotiate \u2192 finalize)", "items": { "type": "object", "properties": { "step": { "type": "string", "description": "Step name (discover, select, create_deal, negotiate, finalize)" }, "status": { "type": "string", "description": "Step status (pending, completed)" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "current_step": { "type": "string", "nullable": true, "description": "Step currently being processed" }, "completed_steps": { "type": "array", "items": { "type": "string" }, "description": "List of completed step names" }, "next_step": { "type": "string", "nullable": true, "description": "Next step to be executed" }, "delegation_check": { "type": "object", "description": "Pre-validated delegation spending limits (includes reserved amounts)" }, "reserved_budget": { "type": "number", "nullable": true, "description": "Estimated budget reserved at plan time (released on cancel/fail, converted to spend on completion)" }, "reservation_id": { "type": "string", "nullable": true, "description": "Budget reservation ID for traceability" }, "deal_id": { "type": "string", "nullable": true, "description": "Created deal ID (set after create_deal step)" }, "result": { "type": "object", "nullable": true, "description": "Workflow result data including deal and product details" }, "error_message": { "type": "string", "nullable": true, "description": "Error message if workflow failed" }, "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 } } }, "StateMachineResponse": { "type": "object", "description": "Machine-readable state machine definitions for entity types", "properties": { "schema_version": { "type": "string", "description": "Version of the state machine schema format", "examples": [ "1.0.0" ] }, "entity_types": { "type": "array", "items": { "type": "string" }, "description": "Available entity types", "examples": [ [ "deals", "contracts" ] ] }, "deals": { "$ref": "#/components/schemas/EntityStateMachine" }, "contracts": { "$ref": "#/components/schemas/EntityStateMachine" } }, "required": [ "schema_version", "entity_types" ] }, "EntityStateMachine": { "type": "object", "description": "State machine definition for a single entity type", "properties": { "entity_type": { "type": "string", "description": "The entity type this state machine applies to" }, "initial_state": { "type": "string", "description": "The initial state when an entity is created" }, "states": { "type": "object", "description": "Map of state name to state definition", "additionalProperties": { "$ref": "#/components/schemas/StateDefinition" } } }, "required": [ "entity_type", "initial_state", "states" ] }, "StateDefinition": { "type": "object", "properties": { "terminal": { "type": "boolean", "description": "Whether this is a terminal state (no outgoing transitions)" }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/StateTransition" } } }, "required": [ "terminal", "transitions" ] }, "StateTransition": { "type": "object", "properties": { "target": { "type": "string", "description": "The target state of this transition" }, "conditions": { "type": "array", "description": "Business rule conditions that must be met", "items": { "type": "object", "properties": { "field": { "type": "string" }, "check": { "type": "string" }, "description": { "type": "string" } } } }, "action": { "type": "object", "description": "The API action required to perform this transition", "properties": { "method": { "type": "string", "enum": [ "POST", "PATCH" ] }, "endpoint": { "type": "string" }, "description": { "type": "string" } } }, "required_scope": { "type": "string", "description": "The API scope required to perform this transition" } }, "required": [ "target", "conditions", "action", "required_scope" ] }, "ValidTransitionsResponse": { "type": "object", "description": "Context-aware valid transitions for a specific deal", "properties": { "deal_id": { "type": "string", "description": "The deal ID" }, "current_status": { "type": "string", "description": "The current status of the deal" }, "transitions": { "type": "array", "items": { "type": "object", "properties": { "target": { "type": "string", "description": "The target state" }, "available": { "type": "boolean", "description": "Whether this transition is currently available (all conditions met)" }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "satisfied": { "type": "boolean" } } } }, "action": { "type": "object", "properties": { "method": { "type": "string" }, "endpoint": { "type": "string" }, "description": { "type": "string" } } } } } } }, "required": [ "deal_id", "current_status", "transitions" ] }, "TeamMember": { "type": "object", "properties": { "membership_id": { "type": "integer" }, "user_id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "owner", "admin", "member", "viewer" ] }, "status": { "type": "string", "enum": [ "active", "invited", "suspended" ] }, "invited_at": { "type": "string", "format": "date-time", "nullable": true }, "accepted_at": { "type": "string", "format": "date-time", "nullable": true }, "last_active": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "Booking": { "type": "object", "description": "A booking for a service product time slot", "properties": { "booking_id": { "type": "string", "description": "Unique booking identifier", "examples": [ "bkng_a1b2c3d4e5" ] }, "tenant_id": { "type": "string", "description": "Tenant identifier" }, "deal_id": { "type": [ "string", "null" ], "description": "Associated deal identifier" }, "line_item_id": { "type": [ "string", "null" ], "description": "Associated deal line item identifier" }, "product_id": { "type": "string", "description": "Service product identifier" }, "product_name": { "type": [ "string", "null" ], "description": "Product name (included in list and detail responses)" }, "staff_id": { "type": "string", "description": "Assigned staff member identifier" }, "staff_name": { "type": [ "string", "null" ], "description": "Staff member name (included in list and detail responses)" }, "customer_id": { "type": [ "string", "null" ], "description": "Customer identifier" }, "customer_name": { "type": [ "string", "null" ], "description": "Customer full name" }, "customer_email": { "type": [ "string", "null" ], "description": "Customer email address" }, "customer_phone": { "type": [ "string", "null" ], "description": "Customer phone number" }, "booking_date": { "type": "string", "format": "date", "description": "Date of the booking" }, "start_time": { "type": "string", "description": "Start time (HH:mm:ss)", "examples": [ "09:00:00" ] }, "end_time": { "type": "string", "description": "End time (HH:mm:ss)", "examples": [ "10:00:00" ] }, "status": { "type": "string", "enum": [ "held", "confirmed", "completed", "cancelled", "no_show" ], "description": "Current booking status" }, "hold_expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the hold expires (only set when status is held)" }, "notes": { "type": [ "string", "null" ], "description": "Optional booking notes" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "booking_id", "product_id", "staff_id", "booking_date", "start_time", "end_time", "status" ] }, "Delegation": { "type": "object", "properties": { "delegation_id": { "type": "string", "description": "Unique delegation identifier", "examples": [ "deleg_abc123def456" ] }, "tenant_id": { "type": "string", "description": "Tenant context" }, "grantor_type": { "type": "string", "enum": [ "user", "agent" ], "description": "Whether the grantor is a human user or another agent" }, "grantor_id": { "type": "string", "description": "User ID or API key ID of the grantor" }, "grantee_agent_key_id": { "type": "string", "description": "API key ID receiving the delegation" }, "max_transaction_amount": { "type": [ "number", "null" ], "description": "Maximum per-transaction spend (null = unlimited)" }, "max_daily_amount": { "type": [ "number", "null" ], "description": "Maximum daily spend (null = unlimited)" }, "max_monthly_amount": { "type": [ "number", "null" ], "description": "Maximum monthly spend (null = unlimited)" }, "spent_today": { "type": "string", "description": "Amount spent today under this delegation" }, "spent_this_month": { "type": "string", "description": "Amount spent this month under this delegation" }, "reserved_today": { "type": "string", "description": "Amount reserved today by planned workflows (not yet converted to spend)" }, "reserved_this_month": { "type": "string", "description": "Amount reserved this month by planned workflows (not yet converted to spend)" }, "available_today": { "type": [ "string", "null" ], "description": "Available daily budget (max_daily_amount - spent_today - reserved_today). Null if no daily limit." }, "available_this_month": { "type": [ "string", "null" ], "description": "Available monthly budget (max_monthly_amount - spent_this_month - reserved_this_month). Null if no monthly limit." }, "allowed_actions": { "type": "array", "items": { "type": "string" }, "description": "Action scopes granted by this delegation (e.g. deals:write, agent:negotiate)" }, "delegation_chain": { "type": "array", "items": { "type": "string" }, "description": "Parent delegation IDs for full traceability (e.g. [\"deleg_abc\", \"deleg_def\"])" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the delegation expires (null = no expiry)" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the delegation was revoked (null = active)" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description of the delegation's purpose" }, "approval_threshold": { "type": [ "number", "null" ], "description": "Transaction amount above which approval is required (null = no approval gate)" }, "approval_steps": { "type": [ "array", "null" ], "items": { "type": "object" }, "description": "Ordered list of approval step configurations (null = no multi-step approval)" }, "approval_timeout": { "type": [ "integer", "null" ], "description": "Seconds to wait for approval before timing out (null = no timeout)" }, "auto_approve_policy": { "type": [ "object", "null" ], "description": "Policy rules for automatic approval without human review (null = no auto-approval)" }, "alert_threshold_pct": { "type": [ "integer", "null" ], "description": "Percentage of spending limit at which to send an alert (null = no alert)" } }, "required": [ "delegation_id", "tenant_id", "grantor_type", "grantor_id", "grantee_agent_key_id", "allowed_actions", "delegation_chain" ] }, "CreateDelegationRequest": { "type": "object", "description": "Request body for creating a new agent delegation. When `allowed_actions` includes `sign`, `deals:sign`, or `contracts:sign`, the `signing_authority_acknowledged` field is required. This confirms the principal understands they are authorising an AI agent to execute legally binding agreements on their behalf \u2014 analogous to a commercial power of attorney. A `signing_authority_granted` audit event is recorded for the delegation.", "properties": { "grantee_agent_key_id": { "type": "string", "description": "API key ID to grant the delegation to" }, "allowed_actions": { "type": "array", "items": { "type": "string" }, "description": "Action scopes to grant (e.g. [\"deals:write\", \"agent:negotiate\", \"deals:sign\"])" }, "max_transaction_amount": { "type": "number", "description": "Maximum per-transaction amount" }, "max_daily_amount": { "type": "number", "description": "Maximum daily spend" }, "max_monthly_amount": { "type": "number", "description": "Maximum monthly spend" }, "expires_at": { "type": "string", "format": "date-time", "description": "Delegation expiry (must be in the future)" }, "signing_authority_acknowledged": { "type": "boolean", "description": "Required when `allowed_actions` includes `sign`, `deals:sign`, or `contracts:sign`. Must be `true`. Confirms the principal explicitly authorises the agent to execute legally binding agreements on their behalf. A `signing_authority_granted` audit event is recorded with timestamp and delegation context." }, "description": { "type": "string", "maxLength": 500, "description": "Optional human-readable description for this delegation" }, "approval_threshold": { "type": "number", "minimum": 0, "maximum": 99999999.99, "nullable": true, "description": "Transaction amount above which human approval is required before the agent can proceed" }, "approval_steps": { "type": "object", "nullable": true, "description": "Structured approval workflow definition (e.g. sequential approvers, parallel gates). Maximum nesting depth of 3." }, "approval_timeout": { "type": "integer", "minimum": 0, "maximum": 86400, "nullable": true, "description": "Seconds to wait for approval before timing out (0\u201386400). When elapsed the pending action is auto-rejected." }, "auto_approve_policy": { "type": "object", "nullable": true, "description": "Policy rules that allow automatic approval without human intervention (e.g. trusted-counterparty list, low-risk product categories). Maximum nesting depth of 3." }, "alert_threshold_pct": { "type": "integer", "minimum": 1, "maximum": 100, "nullable": true, "description": "Percentage of spending limit (1\u2013100) at which a budget alert notification is triggered" } }, "required": [ "grantee_agent_key_id", "allowed_actions" ] }, "Deal": { "type": "object", "description": "Full deal object returned by single-deal GET, POST, and PATCH responses. List responses use DealListItem.", "properties": { "deal_id": { "type": "string", "description": "Unique deal identifier", "examples": [ "deal_a1b2c3d4e5" ] }, "version": { "type": "integer", "description": "Optimistic locking version. Incremented atomically on each update. Used as ETag value for concurrency control.", "minimum": 1, "examples": [ 1 ] }, "customer_id": { "type": "string", "description": "Associated customer ID" }, "title": { "type": [ "string", "null" ], "description": "Deal title" }, "description": { "type": [ "string", "null" ], "description": "Deal description" }, "notes": { "type": [ "string", "null" ], "description": "Internal notes visible only to the seller" }, "status": { "type": "string", "enum": [ "draft", "in_progress", "pending_signature", "awaiting_signatures", "pending_payment", "partially_accepted", "closed", "cancelled", "expired" ], "description": "Current deal status" }, "currency": { "type": "string", "description": "ISO 4217 currency code", "examples": [ "AUD" ] }, "presentation_currency": { "type": "string", "description": "Currency displayed to the buyer (ISO 4217)", "examples": [ "JPY" ] }, "settlement_currency": { "type": "string", "description": "Currency the seller receives settlement in (ISO 4217)", "examples": [ "AUD" ] }, "fx_rate": { "type": [ "number", "null" ], "format": "double", "description": "Locked FX rate from presentation to settlement currency at deal creation" }, "fx_rate_locked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the FX rate was locked" }, "fx_rate_provider": { "type": [ "string", "null" ], "description": "Source of the FX rate (e.g. 'stripe', 'identity')" }, "deposit_required": { "type": [ "string", "null" ], "description": "Required deposit amount (raw value from DB; see pricing.deposit_required for formatted object)" }, "customer": { "$ref": "#/components/schemas/CustomerSummary" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" }, "description": "Line items in the deal" }, "pricing": { "type": "object", "description": "All monetary amounts for the deal, each expressed as an {amount, currency, formatted} object", "properties": { "currency": { "type": "string", "description": "Settlement currency (ISO 4217)" }, "presentation_currency": { "type": "string", "description": "Presentation currency (ISO 4217)" }, "settlement_currency": { "type": "string", "description": "Settlement currency (ISO 4217)" }, "fx_rate": { "type": [ "number", "null" ], "format": "double", "description": "FX rate applied to this deal" }, "subtotal": { "$ref": "#/components/schemas/MoneyAmount", "description": "Subtotal before discounts and tax" }, "discounts": { "type": "array", "items": { "$ref": "#/components/schemas/Discount" }, "description": "Applied discounts" }, "discount": { "$ref": "#/components/schemas/MoneyAmount", "description": "Total discount amount" }, "tax_rate": { "type": "number", "format": "double", "description": "Tax rate as decimal (e.g. 0.10 = 10%)" }, "tax_amount": { "$ref": "#/components/schemas/MoneyAmount", "description": "Calculated tax amount" }, "total": { "$ref": "#/components/schemas/MoneyAmount", "description": "Total amount including tax" }, "deposit_required": { "$ref": "#/components/schemas/MoneyAmount", "description": "Required deposit amount" }, "deposit_collected": { "$ref": "#/components/schemas/MoneyAmount", "description": "Deposit amount already collected" }, "balance_due": { "$ref": "#/components/schemas/MoneyAmount", "description": "Remaining balance due" } } }, "terms": { "type": "object", "description": "Contract documents and structured machine-readable terms", "properties": { "document_id": { "type": [ "string", "null" ], "description": "Contract document ID" }, "template_id": { "type": [ "string", "null" ], "description": "Contract template ID" }, "contract_url": { "type": [ "string", "null" ], "description": "URL to contract document" }, "agreed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When terms were agreed" }, "signature": { "type": [ "object", "null" ], "description": "Cryptographic signature data if the deal has been signed" }, "structured": { "type": [ "object", "null" ], "description": "Machine-readable structured deal terms. See GET /api/schemas/deal-terms.json for full schema.", "$ref": "#/components/schemas/DealTerms" }, "terms_schema_version": { "type": [ "string", "null" ], "description": "Version of the deal terms schema", "examples": [ "1.0" ] } } }, "payment": { "type": "object", "description": "Payment details for the deal", "properties": { "processor": { "type": [ "string", "null" ], "description": "Payment processor used (e.g. 'stripe')" }, "payment_intent_id": { "type": [ "string", "null" ], "description": "Stripe PaymentIntent ID or equivalent" }, "charge_id": { "type": [ "string", "null" ], "description": "Charge/transaction ID from the processor" }, "status": { "type": [ "string", "null" ], "description": "Payment status (e.g. 'succeeded', 'pending')" }, "amount": { "type": [ "string", "null" ], "description": "Amount paid" }, "currency": { "type": "string", "description": "Settlement currency (ISO 4217)" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when payment was completed" } } }, "escrow": { "type": [ "object", "null" ], "description": "Escrow details if this deal uses escrow payment" }, "template": { "type": "object", "description": "Deal template this deal was created from, if any", "properties": { "template_id": { "type": [ "string", "null" ], "description": "Template ID" }, "template_version": { "type": [ "integer", "null" ], "description": "Template version used" } } }, "metadata": { "type": "object", "description": "Arbitrary metadata key-value pairs" }, "outcome": { "type": [ "object", "null" ], "description": "Deal outcome data (reason for closure, etc.)" }, "deal_score": { "type": [ "object", "null" ], "description": "AI-generated deal intelligence scoring" }, "is_signed": { "type": "boolean", "description": "Whether the deal has been cryptographically signed" }, "signed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the deal was signed" }, "signature_valid": { "type": "boolean", "description": "Whether the cryptographic signature is valid" }, "deal_hash": { "type": [ "string", "null" ], "description": "Cryptographic hash of the deal for tamper detection" }, "verification_url": { "type": [ "string", "null" ], "format": "uri", "description": "Public URL to verify the deal's authenticity" }, "subscription": { "type": [ "object", "null" ], "description": "Subscription fields for recurring deals. Null for one-time deals.", "properties": { "deal_type": { "type": "string", "enum": [ "recurring" ] }, "billing_cycle": { "type": [ "string", "null" ], "description": "Billing interval (e.g. 'monthly', 'annual')" }, "subscription_status": { "type": [ "string", "null" ], "description": "Current subscription status" }, "next_billing_date": { "type": [ "string", "null" ], "format": "date-time" }, "billing_period_start": { "type": [ "string", "null" ], "format": "date-time" }, "billing_period_end": { "type": [ "string", "null" ], "format": "date-time" }, "retry_count": { "type": "integer", "description": "Number of billing retry attempts" }, "renewal_count": { "type": "integer", "description": "Number of successful renewals" }, "parent_deal_id": { "type": [ "string", "null" ], "description": "Parent deal ID for renewal deals" } } }, "deal_type": { "type": "string", "enum": [ "one_time", "recurring" ], "default": "one_time", "description": "Deal type: one_time for a single purchase, recurring for a subscription" }, "billing_cycle": { "type": [ "string", "null" ], "enum": [ "monthly", "quarterly", "annual", null ], "description": "Billing cycle for recurring deals. Null for one_time deals." }, "tax_rate": { "type": [ "number", "null" ], "description": "Tax rate as a decimal (e.g. 0.10 = 10%). Also available nested under pricing.tax_rate." }, "synced_from_offline": { "type": "boolean", "description": "Whether this deal was created offline and synced later" }, "created_offline_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the deal was created offline on the device" }, "offline_device_id": { "type": [ "string", "null" ], "description": "Unique identifier of the device that created this deal offline" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last update timestamp (ISO 8601)" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the deal was completed or closed" } }, "required": [ "deal_id", "version", "status", "customer_id", "currency", "created_at" ] }, "DealListItem": { "type": "object", "description": "Minimal deal object returned in list (GET /deals without a specific ID) responses. Excludes pricing details, terms, payment, and other nested objects; includes flat customer fields and a formatted total.", "properties": { "deal_id": { "type": "string", "description": "Unique deal identifier", "examples": [ "deal_a1b2c3d4e5" ] }, "version": { "type": "integer", "description": "Optimistic locking version", "minimum": 1 }, "status": { "type": "string", "enum": [ "draft", "in_progress", "pending_signature", "awaiting_signatures", "pending_payment", "partially_accepted", "closed", "cancelled", "expired" ], "description": "Current deal status" }, "customer_id": { "type": "string", "description": "Associated customer ID" }, "customer_name": { "type": [ "string", "null" ], "description": "Customer display name (flat field for list display)" }, "customer_email": { "type": [ "string", "null" ], "format": "email", "description": "Customer email address (flat field for list display)" }, "customer_company": { "type": [ "string", "null" ], "description": "Customer company name (flat field for list display)" }, "customer": { "type": "object", "description": "Embedded customer summary (name, email, phone, company)", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] } } }, "total": { "type": [ "string", "null" ], "description": "Total amount (raw decimal string)" }, "total_formatted": { "type": "string", "description": "Total amount formatted in the settlement currency (e.g. 'A$1,234.56')", "examples": [ "A$1,234.56" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code", "examples": [ "AUD" ] }, "presentation_currency": { "type": "string", "description": "Currency displayed to the buyer (ISO 4217)", "examples": [ "JPY" ] }, "settlement_currency": { "type": "string", "description": "Currency the seller receives settlement in (ISO 4217)", "examples": [ "AUD" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp (ISO 8601)" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last modification timestamp (ISO 8601); falls back to created_at if never updated" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the deal was completed or closed" }, "is_signed": { "type": "boolean", "description": "Whether this deal has been signed" }, "signature_status": { "type": "string", "enum": [ "signed", "unsigned" ], "description": "Signature status of the deal" } }, "required": [ "deal_id", "version", "status", "customer_id", "currency", "created_at" ] }, "MoneyAmount": { "type": "object", "description": "A monetary amount expressed as a raw decimal string, its currency, and a locale-formatted string", "properties": { "amount": { "type": "string", "description": "Raw decimal amount string as stored in the database", "examples": [ "1234.56" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code", "examples": [ "AUD" ] }, "formatted": { "type": "string", "description": "Human-readable formatted amount", "examples": [ "A$1,234.56" ] } }, "required": [ "amount", "currency", "formatted" ] }, "CustomerSummary": { "type": "object", "description": "Customer summary embedded in deal responses", "properties": { "customer_id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "LineItem": { "type": "object", "properties": { "item_id": { "type": "string", "description": "Unique line item identifier", "examples": [ "item_a1b2" ] }, "product_id": { "type": [ "string", "null" ], "description": "Product ID if linked to a product" }, "name": { "type": "string", "description": "Item name" }, "unit_price": { "type": "number", "format": "double", "description": "Price per unit" }, "quantity": { "type": "integer", "description": "Quantity" }, "subtotal": { "type": "number", "format": "double", "description": "Line subtotal (unit_price * quantity)" }, "price_type": { "type": "string", "enum": [ "once_off", "recurring", "percentage", "metered" ], "description": "Pricing model for this line item", "default": "once_off" }, "billing_cycle": { "type": [ "string", "null" ], "enum": [ "monthly", "quarterly", "annual", null ], "description": "Billing cycle when price_type is recurring" }, "deal_id": { "type": "string", "description": "Deal this line item belongs to" }, "description": { "type": [ "string", "null" ], "description": "Item description" }, "configuration": { "type": [ "object", "null" ], "description": "Product configuration selections" }, "sort_order": { "type": "integer", "description": "Display order" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Discount": { "type": "object", "properties": { "deal_id": { "type": "string", "description": "Parent deal ID" }, "type": { "type": "string", "enum": [ "percentage", "fixed" ], "description": "Discount type" }, "code": { "type": "string", "nullable": true, "description": "Promo or discount code" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description" }, "value": { "type": "number", "format": "double", "description": "Raw discount input value (e.g. 10 for 10%)" }, "amount": { "type": "number", "format": "double", "description": "Calculated discount amount in deal currency" }, "created_at": { "type": "string", "format": "date-time", "description": "When the discount was applied" } } }, "Customer": { "type": "object", "properties": { "id": { "type": "integer", "description": "Database ID" }, "customer_id": { "type": "string", "description": "Unique customer identifier", "examples": [ "cust_a1b2c3d4e5" ] }, "version": { "type": "integer", "description": "Optimistic locking version. Incremented atomically on each update.", "minimum": 1 }, "name": { "type": [ "string", "null" ], "description": "Customer name" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email address" }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164 format" }, "address": { "type": [ "string", "null" ], "description": "Street address" }, "company": { "type": [ "string", "null" ], "description": "Company name" }, "city": { "type": [ "string", "null" ], "description": "City" }, "state": { "type": [ "string", "null" ], "description": "State or province" }, "zip": { "type": [ "string", "null" ], "description": "Postal code" }, "country": { "type": [ "string", "null" ], "description": "ISO country code" }, "notes": { "type": [ "string", "null" ], "description": "Free-form notes" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "description": "Customer status" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "deals": { "type": "array", "description": "Deals linked to this customer. Included by default in single-customer responses.", "items": { "type": "object", "properties": { "deal_id": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "contracts": { "type": "array", "description": "Contracts linked to this customer. Included by default in single-customer responses.", "items": { "type": "object", "properties": { "contract_id": { "type": "integer" }, "title": { "type": "string" }, "status": { "type": "string" }, "value": { "type": "number" }, "currency": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "created_at": { "type": "string", "format": "date-time" } } } }, "communications": { "type": "array", "description": "Communication log entries (email, SMS, voice) for this customer. Included by default in single-customer responses.", "items": { "type": "object", "properties": { "log_id": { "type": "string" }, "type": { "type": "string", "enum": [ "sms", "voice", "email" ] }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "status": { "type": "string" }, "subject": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "activity_log": { "type": "array", "items": { "type": "object" }, "description": "Recent activity log entries for this customer. Included by default in single-resource responses, absent in list responses." } }, "required": [ "customer_id", "status", "created_at" ] }, "CustomerListItem": { "type": "object", "description": "Customer object returned in list (GET /customers without a specific ID), POST /customers 201, and PATCH /customers 200 responses. Contains only the 16 flat fields returned by mapCustomerRecord(). Excludes nested sub-resources (deals, contracts, communications, activity_log) which are only present in single-customer GET responses.", "properties": { "id": { "type": "integer", "description": "Database ID" }, "customer_id": { "type": "string", "description": "Unique customer identifier", "examples": [ "cust_a1b2c3d4e5" ] }, "version": { "type": "integer", "description": "Optimistic locking version. Incremented atomically on each update.", "minimum": 1 }, "name": { "type": [ "string", "null" ], "description": "Customer name" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email address" }, "phone": { "type": [ "string", "null" ], "description": "Phone number in E.164 format" }, "address": { "type": [ "string", "null" ], "description": "Street address" }, "company": { "type": [ "string", "null" ], "description": "Company name" }, "city": { "type": [ "string", "null" ], "description": "City" }, "state": { "type": [ "string", "null" ], "description": "State or province" }, "zip": { "type": [ "string", "null" ], "description": "Postal code" }, "country": { "type": [ "string", "null" ], "description": "ISO country code" }, "notes": { "type": [ "string", "null" ], "description": "Free-form notes" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "description": "Customer status" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "customer_id", "status", "created_at" ] }, "Product": { "type": "object", "description": "Full product object returned by GET /products/{id} (single-product) responses. Extends ProductBase with nested collection resources: deals, activity_log, and inventory_movements. POST and PATCH responses use ProductBase (no nested collections). List responses use ProductListItem.", "properties": { "id": { "type": "integer", "description": "Database ID" }, "product_id": { "type": "string", "description": "Unique product identifier", "examples": [ "prod_a1b2c3d4e5" ] }, "version": { "type": "integer", "description": "Optimistic locking version. Incremented atomically on each update.", "minimum": 1 }, "family_id": { "type": [ "string", "null" ], "description": "Product family ID this product belongs to, or null" }, "family": { "type": [ "object", "null" ], "description": "Resolved product family object, or null if no family is assigned", "properties": { "family_id": { "type": "string", "description": "Family identifier" }, "name": { "type": "string", "description": "Family name" } } }, "name": { "type": "string", "description": "Product name" }, "description": { "type": [ "string", "null" ], "description": "Product description" }, "learn_more_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "URL shown as a 'Learn more' link in the widget detail panel" }, "features": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Short selling-point bullet strings displayed on the product card and detail panel" }, "sku": { "type": [ "string", "null" ], "description": "Stock keeping unit" }, "price": { "type": "number", "format": "double", "description": "Selling price" }, "base_price": { "type": "number", "format": "double", "description": "Base price before negotiation adjustments; falls back to price if not separately set" }, "price_type": { "type": "string", "enum": [ "once_off", "recurring", "percentage", "metered" ], "description": "Pricing model", "default": "once_off" }, "billing_cycle": { "type": [ "string", "null" ], "enum": [ "monthly", "quarterly", "annual", null ], "description": "Billing cycle when price_type is recurring" }, "cost": { "type": "number", "format": "double", "description": "Cost price" }, "type": { "type": "string", "description": "Product type (e.g. product, service)" }, "unit": { "type": "string", "description": "Unit of measure (e.g. unit, hour)" }, "tax_rate": { "type": "number", "format": "double", "description": "Tax rate as decimal" }, "pricing_model": { "type": "string", "enum": [ "fixed", "tiered", "volume", "usage" ], "description": "Pricing model strategy", "default": "fixed" }, "category": { "type": [ "string", "null" ], "description": "Product category" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "description": "Product status" }, "agent_discoverable": { "type": "boolean", "description": "Whether this product is discoverable and purchasable by AI agents" }, "stock_quantity": { "type": "integer", "description": "Quantity on hand" }, "track_inventory": { "type": "boolean", "description": "Whether inventory tracking is enabled for this product" }, "low_stock_threshold": { "type": [ "integer", "null" ], "description": "Stock level at which low-stock alerts are triggered, or null if not set" }, "configuration_schema": { "type": [ "object", "null" ], "description": "Product configuration schema for widget rendering, merged with linked option groups. Null if not configured." }, "metadata": { "type": [ "object", "null" ], "description": "Arbitrary key-value metadata (only in single-product response). Null if not set." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "requires_booking": { "type": "boolean", "description": "Whether this product requires a booking to purchase" }, "session_duration": { "type": [ "integer", "null" ], "description": "Session length in minutes", "minimum": 5, "maximum": 480 }, "buffer_time": { "type": [ "integer", "null" ], "description": "Buffer time between sessions in minutes", "minimum": 0, "maximum": 120 }, "max_advance_days": { "type": "integer", "description": "Maximum days in advance a booking can be made", "minimum": 1, "maximum": 365, "default": 90 }, "min_advance_hours": { "type": "integer", "description": "Minimum hours lead time required for a booking", "minimum": 0, "maximum": 168, "default": 24 }, "allow_staff_selection": { "type": "boolean", "description": "Whether customers can choose their preferred staff member", "default": true }, "deals": { "type": "array", "items": { "$ref": "#/components/schemas/DealListItem" }, "description": "Related deals for this product. Included by default in single-resource responses, absent in list responses." }, "activity_log": { "type": "array", "items": { "type": "object" }, "description": "Recent activity log entries for this product. Included by default in single-resource responses, absent in list responses." }, "inventory_movements": { "type": "array", "items": { "type": "object" }, "description": "Recent inventory movements for this product. Included by default in single-resource responses for track_inventory products, absent otherwise." } }, "required": [ "name", "price", "status" ] }, "ProductBase": { "type": "object", "description": "Product object returned by POST /products (create) and PATCH /products/{id} (update) responses. Contains all scalar product fields plus the resolved family object. Nested collection resources (deals, activity_log, inventory_movements) are only included in GET single-product responses \u2014 see the Product schema.", "properties": { "id": { "type": "integer", "description": "Database ID" }, "product_id": { "type": "string", "description": "Unique product identifier", "examples": [ "prod_a1b2c3d4e5" ] }, "version": { "type": "integer", "description": "Optimistic locking version. Incremented atomically on each update.", "minimum": 1 }, "family_id": { "type": [ "string", "null" ], "description": "Product family ID this product belongs to, or null" }, "family": { "type": [ "object", "null" ], "description": "Resolved product family object, or null if no family is assigned", "properties": { "family_id": { "type": "string", "description": "Family identifier" }, "name": { "type": "string", "description": "Family name" } } }, "name": { "type": "string", "description": "Product name" }, "description": { "type": [ "string", "null" ], "description": "Product description" }, "learn_more_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "URL shown as a 'Learn more' link in the widget detail panel" }, "features": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Short selling-point bullet strings displayed on the product card and detail panel" }, "sku": { "type": [ "string", "null" ], "description": "Stock keeping unit" }, "price": { "type": "number", "format": "double", "description": "Selling price" }, "base_price": { "type": "number", "format": "double", "description": "Base price before negotiation adjustments; falls back to price if not separately set" }, "price_type": { "type": "string", "enum": [ "once_off", "recurring", "percentage", "metered" ], "description": "Pricing model", "default": "once_off" }, "billing_cycle": { "type": [ "string", "null" ], "enum": [ "monthly", "quarterly", "annual", null ], "description": "Billing cycle when price_type is recurring" }, "cost": { "type": "number", "format": "double", "description": "Cost price" }, "type": { "type": "string", "description": "Product type (e.g. product, service)" }, "unit": { "type": "string", "description": "Unit of measure (e.g. unit, hour)" }, "tax_rate": { "type": "number", "format": "double", "description": "Tax rate as decimal" }, "pricing_model": { "type": "string", "enum": [ "fixed", "tiered", "volume", "usage" ], "description": "Pricing model strategy", "default": "fixed" }, "category": { "type": [ "string", "null" ], "description": "Product category" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "description": "Product status" }, "agent_discoverable": { "type": "boolean", "description": "Whether this product is discoverable and purchasable by AI agents" }, "stock_quantity": { "type": "integer", "description": "Quantity on hand" }, "track_inventory": { "type": "boolean", "description": "Whether inventory tracking is enabled for this product" }, "low_stock_threshold": { "type": [ "integer", "null" ], "description": "Stock level at which low-stock alerts are triggered, or null if not set" }, "requires_booking": { "type": "boolean", "description": "Whether this product requires a booking to purchase" }, "session_duration": { "type": [ "integer", "null" ], "description": "Session length in minutes", "minimum": 5, "maximum": 480 }, "buffer_time": { "type": [ "integer", "null" ], "description": "Buffer time between sessions in minutes", "minimum": 0, "maximum": 120 }, "max_advance_days": { "type": "integer", "description": "Maximum days in advance a booking can be made", "minimum": 1, "maximum": 365, "default": 90 }, "min_advance_hours": { "type": "integer", "description": "Minimum hours lead time required for a booking", "minimum": 0, "maximum": 168, "default": 24 }, "allow_staff_selection": { "type": "boolean", "description": "Whether customers can choose their preferred staff member", "default": true }, "configuration_schema": { "type": [ "object", "null" ], "description": "Product configuration schema for widget rendering, merged with linked option groups. Null if not configured." }, "metadata": { "type": [ "object", "null" ], "description": "Arbitrary key-value metadata. Null if not set." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "name", "price", "status" ] }, "ProductListItem": { "type": "object", "description": "Product object returned in list (GET /products without a specific ID) responses. Excludes cost, metadata, and the full family object; includes family_name string instead.", "properties": { "id": { "type": "integer", "description": "Database ID" }, "product_id": { "type": "string", "description": "Unique product identifier", "examples": [ "prod_a1b2c3d4e5" ] }, "family_id": { "type": [ "string", "null" ], "description": "Product family ID this product belongs to, or null" }, "family_name": { "type": [ "string", "null" ], "description": "Product family name (flat string, resolved from family_id), or null" }, "name": { "type": "string", "description": "Product name" }, "description": { "type": [ "string", "null" ], "description": "Product description" }, "learn_more_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "description": "URL shown as a 'Learn more' link in the widget detail panel" }, "features": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Short selling-point bullet strings displayed on the product card and detail panel" }, "sku": { "type": [ "string", "null" ], "description": "Stock keeping unit" }, "price": { "type": "number", "format": "double", "description": "Selling price" }, "base_price": { "type": "number", "format": "double", "description": "Base price before negotiation adjustments; falls back to price if not separately set" }, "price_type": { "type": "string", "enum": [ "once_off", "recurring", "percentage", "metered" ], "description": "Pricing model", "default": "once_off" }, "billing_cycle": { "type": [ "string", "null" ], "enum": [ "monthly", "quarterly", "annual", null ], "description": "Billing cycle when price_type is recurring" }, "type": { "type": "string", "description": "Product type (e.g. product, service)" }, "unit": { "type": "string", "description": "Unit of measure (e.g. unit, hour)" }, "tax_rate": { "type": "number", "format": "double", "description": "Tax rate as decimal" }, "pricing_model": { "type": "string", "enum": [ "fixed", "tiered", "volume", "usage" ], "description": "Pricing model strategy", "default": "fixed" }, "category": { "type": [ "string", "null" ], "description": "Product category" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "description": "Product status" }, "agent_discoverable": { "type": "boolean", "description": "Whether this product is discoverable and purchasable by AI agents" }, "stock_quantity": { "type": "integer", "description": "Quantity on hand" }, "track_inventory": { "type": "boolean", "description": "Whether inventory tracking is enabled for this product" }, "low_stock_threshold": { "type": [ "integer", "null" ], "description": "Stock level at which low-stock alerts are triggered, or null if not set" }, "configuration_schema": { "type": [ "object", "null" ], "description": "Product configuration schema for widget rendering, merged with linked option groups. Null if not configured." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" } }, "required": [ "name", "price", "status" ] }, "Contract": { "type": "object", "properties": { "contract_id": { "type": "integer", "description": "Contract ID" }, "version": { "type": "integer", "description": "Optimistic locking version. Incremented atomically on each update.", "minimum": 1 }, "customer_id": { "type": "string", "description": "Associated customer ID" }, "title": { "type": "string", "description": "Contract title" }, "description": { "type": [ "string", "null" ], "description": "Contract description" }, "contract_number": { "type": "string", "description": "Unique contract number" }, "status": { "type": "string", "enum": [ "draft", "signed", "pending", "active", "terminated", "expired" ], "description": "Current contract status" }, "value": { "type": "number", "format": "double", "description": "Contract value" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "start_date": { "type": "string", "format": "date", "description": "Contract start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "format": "date", "description": "Contract end date (YYYY-MM-DD)" }, "signed_date": { "type": [ "string", "null" ], "format": "date", "description": "Date the contract was signed" }, "renewal_type": { "type": "string", "enum": [ "manual", "auto", "none" ], "description": "Renewal type" }, "payment_terms": { "type": [ "string", "null" ], "description": "Payment terms description" }, "notes": { "type": [ "string", "null" ], "description": "Additional notes" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "customer": { "type": [ "object", "null" ], "description": "Resolved customer details. Always included in single-contract responses.", "properties": { "customer_id": { "type": "string", "description": "Customer identifier" }, "name": { "type": [ "string", "null" ], "description": "Customer display name (decrypted PII or company name)" }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Customer email address (decrypted PII)" }, "company": { "type": [ "string", "null" ], "description": "Company name" } } }, "activity_log": { "type": "array", "description": "Audit log entries for this contract. Included by default in single-contract responses; omit via field selection.", "items": { "type": "object", "properties": { "log_id": { "type": "string", "description": "Unique audit log entry ID" }, "action": { "type": "string", "description": "Action performed (e.g. created, updated, signed)" }, "actor_type": { "type": "string", "description": "Type of actor (e.g. user, api_key, system)" }, "actor_id": { "type": [ "string", "null" ], "description": "Identifier of the actor" }, "changes": { "type": [ "object", "null" ], "description": "JSON object describing field changes" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp of the audit event" } } } }, "renewal_terms": { "type": [ "object", "null" ], "description": "Structured renewal terms for this contract", "additionalProperties": true }, "renewal_count": { "type": "integer", "description": "Number of times this contract has been renewed", "minimum": 0 }, "renewal_opted_out": { "type": "boolean", "description": "Whether the customer has opted out of auto-renewal" }, "parent_contract_id": { "type": [ "string", "null" ], "description": "ID of the parent contract if this is a renewal" }, "signature": { "type": [ "object", "null" ], "description": "Cryptographic signature details. Included when the contract has a cryptographic signature.", "properties": { "contract_hash": { "type": "string", "description": "Hash of the contract content at time of signing" }, "signer_type": { "type": [ "string", "null" ], "description": "Type of signer (e.g. customer, agent)" }, "signer_id": { "type": [ "string", "null" ], "description": "Identifier of the signer" }, "signature_method": { "type": [ "string", "null" ], "description": "Signature method used (e.g. ed25519)" }, "signature_hash": { "type": [ "string", "null" ], "description": "Cryptographic signature hash" } } } }, "required": [ "contract_id", "customer_id", "title", "status", "value", "start_date", "end_date" ] }, "ContractListItem": { "type": "object", "description": "Contract object returned in list (GET /contracts without a specific ID) responses. Excludes nested customer object and activity_log array; includes customer_id for reference lookup.", "properties": { "contract_id": { "type": "integer", "description": "Contract ID" }, "version": { "type": "integer", "description": "Optimistic locking version. Incremented atomically on each update.", "minimum": 1 }, "customer_id": { "type": "string", "description": "Associated customer ID" }, "title": { "type": "string", "description": "Contract title" }, "description": { "type": [ "string", "null" ], "description": "Contract description" }, "contract_number": { "type": "string", "description": "Unique contract number" }, "status": { "type": "string", "enum": [ "draft", "signed", "pending", "active", "terminated", "expired" ], "description": "Current contract status" }, "value": { "type": "number", "format": "double", "description": "Contract value" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "start_date": { "type": "string", "format": "date", "description": "Contract start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "format": "date", "description": "Contract end date (YYYY-MM-DD)" }, "signed_date": { "type": [ "string", "null" ], "format": "date", "description": "Date the contract was signed" }, "renewal_type": { "type": "string", "enum": [ "manual", "auto", "none" ], "description": "Renewal type" }, "payment_terms": { "type": [ "string", "null" ], "description": "Payment terms description" }, "notes": { "type": [ "string", "null" ], "description": "Additional notes" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "renewal_terms": { "type": [ "object", "null" ], "description": "Structured renewal terms for this contract", "additionalProperties": true }, "renewal_count": { "type": "integer", "description": "Number of times this contract has been renewed", "minimum": 0 }, "renewal_opted_out": { "type": "boolean", "description": "Whether the customer has opted out of auto-renewal" }, "parent_contract_id": { "type": [ "string", "null" ], "description": "ID of the parent contract if this is a renewal" }, "signature": { "type": [ "object", "null" ], "description": "Cryptographic signature details. Included when the contract has a cryptographic signature.", "properties": { "contract_hash": { "type": "string", "description": "Hash of the contract content at time of signing" }, "signer_type": { "type": [ "string", "null" ], "description": "Type of signer (e.g. customer, agent)" }, "signer_id": { "type": [ "string", "null" ], "description": "Identifier of the signer" }, "signature_method": { "type": [ "string", "null" ], "description": "Signature method used (e.g. ed25519)" }, "signature_hash": { "type": [ "string", "null" ], "description": "Cryptographic signature hash" } } } }, "required": [ "contract_id", "customer_id", "title", "status", "value", "start_date", "end_date" ] }, "ApiKey": { "type": "object", "properties": { "key_id": { "type": "string", "description": "Unique key identifier" }, "name": { "type": "string", "description": "Human-readable key name" }, "description": { "type": [ "string", "null" ], "description": "Key description" }, "key_prefix": { "type": "string", "description": "Visible prefix for key identification (e.g. sb_live_xxxx)" }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ], "description": "Key status" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Authorized scopes" }, "rate_limit": { "type": "integer", "description": "Requests per minute" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiration timestamp" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last usage timestamp" }, "key_type": { "type": "string", "enum": [ "standard", "publishable" ], "description": "Key type: standard keys are secret server-side keys; publishable keys are safe to embed in client-side code" }, "last_used_ip": { "type": [ "string", "null" ], "description": "IP address of last request (only returned by single-key GET, not the list endpoint)" }, "last_rotated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of last key rotation, or null if never rotated" }, "total_requests": { "type": "integer", "description": "Total number of requests made with this key" }, "allowed_origins": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "CORS origin allowlist for publishable keys, or null if unrestricted" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the key was revoked, or null if still active (only returned by single-key GET, not the list endpoint)" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" } }, "required": [ "key_id", "name", "key_prefix", "key_type", "status", "scopes", "rate_limit", "total_requests", "created_at" ] }, "ApiKeyCreated": { "type": "object", "description": "Response when creating a new API key. The `api_key` field is the full key value \u2014 it is only shown once.", "properties": { "key_id": { "type": "string" }, "api_key": { "type": "string", "description": "Full API key value. Store securely \u2014 not shown again." }, "key_prefix": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "rate_limit": { "type": "integer" }, "expires_at": { "type": [ "string", "null" ] }, "allowed_origins": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Allowed CORS origins for this key. Null if unrestricted." } }, "required": [ "key_id", "api_key", "key_prefix", "name", "scopes", "rate_limit" ] }, "ApiKeyStats": { "type": "object", "properties": { "key_id": { "type": "string" }, "total_requests": { "type": "integer" }, "total_success": { "type": "integer" }, "total_errors": { "type": "integer" }, "requests_by_endpoint": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Request counts grouped by endpoint path" }, "requests_by_status": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Request counts grouped by HTTP status code" }, "period": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" } }, "required": [ "start_date", "end_date" ] } }, "required": [ "key_id", "total_requests", "total_success", "total_errors", "period" ] }, "FormattedAmount": { "type": "object", "description": "Monetary amount with currency formatting", "properties": { "amount": { "type": "string", "description": "Decimal amount with correct currency precision", "examples": [ "1500.00" ] }, "currency": { "type": "string", "description": "ISO 4217 currency code", "examples": [ "AUD" ] }, "formatted": { "type": "string", "description": "Locale-formatted currency string", "examples": [ "A$1,500.00" ] } }, "required": [ "amount", "currency", "formatted" ] }, "DealCreateRequest": { "type": "object", "description": "Request body for creating a new deal", "required": [ "title" ], "properties": { "customer_id": { "type": "string", "description": "Existing customer ID (optional \u2014 omit for widget negotiations or draft deals created before customer info is collected)" }, "title": { "type": "string", "description": "Deal title", "maxLength": 255 }, "description": { "type": "string", "description": "Deal description", "maxLength": 65535 }, "currency": { "type": "string", "description": "ISO 4217 currency code", "default": "USD" }, "presentation_currency": { "type": "string", "description": "Currency displayed to the buyer (ISO 4217). Defaults to currency if not provided." }, "settlement_currency": { "type": "string", "description": "Currency the seller receives settlement in (ISO 4217). Defaults to currency if not provided." }, "status": { "type": "string", "enum": [ "draft", "in_progress", "pending_payment", "pending_signature", "awaiting_signatures", "partially_accepted", "closed", "cancelled", "expired" ], "default": "draft", "description": "Initial deal status" }, "deal_type": { "type": "string", "enum": [ "one_time", "recurring" ], "description": "Deal type" }, "billing_cycle": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ], "description": "Billing cycle. **Required** when deal_type is 'recurring'. Must be one of: monthly, quarterly, annual." }, "notes": { "type": "string", "description": "Internal notes", "maxLength": 65535 }, "metadata": { "type": "object", "description": "Optional metadata key-value pairs" }, "tax_rate": { "type": "number", "minimum": 0, "maximum": 100, "description": "Tax rate percentage for the deal" }, "template_id": { "type": "string", "maxLength": 255, "description": "ID of a deal template to create the deal from" } }, "if": { "properties": { "deal_type": { "const": "recurring" } }, "required": [ "deal_type" ] }, "then": { "required": [ "billing_cycle" ] } }, "DealAddItemRequest": { "type": "object", "description": "Request body for adding a line item to a deal", "properties": { "product_id": { "type": "string", "description": "Product ID to link" }, "name": { "type": "string", "description": "Item name" }, "unit_price": { "type": "number", "format": "double", "description": "Price per unit", "minimum": 0 }, "quantity": { "type": "integer", "description": "Quantity", "minimum": 1, "default": 1 }, "description": { "type": "string", "description": "Item description", "nullable": true }, "configuration": { "type": "object", "description": "CPQ configuration with option selections. Drives the Configure-Price-Quote flow, linking product options to line items.", "properties": { "option_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of selected product option IDs" } }, "nullable": true }, "price_type": { "type": "string", "description": "Billing model for this line item. Defaults to `once_off` if omitted.", "enum": [ "once_off", "recurring", "metered" ] }, "billing_cycle": { "type": "string", "description": "Billing frequency for recurring or metered line items. Required when `price_type` is `recurring` or `metered`.", "enum": [ "monthly", "quarterly", "annual" ], "nullable": true } }, "required": [ "product_id", "name", "unit_price" ] }, "DealUpdateItemRequest": { "type": "object", "description": "Request body for updating a line item in a deal (e.g. changing quantity or unit price). Requires item_id query parameter.", "properties": { "quantity": { "type": "integer", "description": "New quantity for the line item", "minimum": 1 }, "unit_price": { "type": "number", "description": "Override unit price for the line item", "minimum": 0 } } }, "DealApplyDiscountRequest": { "type": "object", "description": "Request body for applying a discount to a deal", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed" ], "description": "Discount type" }, "value": { "type": "number", "format": "double", "description": "Discount value", "minimum": 0 }, "code": { "type": "string", "description": "Promo or discount code for tracking. Used in activity logging and returned in API responses.", "nullable": true }, "description": { "type": "string", "description": "Human-readable discount description", "nullable": true } }, "required": [ "type", "value" ] }, "DealSignRequest": { "type": "object", "description": "Request body for cryptographically signing a deal. The deal must be in `pending_signature` status. Requires `deals:sign` scope (implied by `deals:write`). The `signature_data` and `signed_at` fields are always server-generated and cannot be set by the client. When `signer_customer_id` is provided, the caller must be authorized: session users must be tenant admins, API keys require the deal to belong to the specified customer, and delegations must include `deals:sign` in allowed_actions.\n\n**ETA Compliance (Human Signers):** `consent_to_sign: true` is required for all human (non-agent) signers. This captures explicit consent under the Electronic Transactions Act 1999 (Cth) s.10. This consent event is recorded as a discrete audit trail entry with timestamp and IP address.\n\n**Agent Signing:** When signing via delegation (API key + X-Delegation-ID header), `consent_to_sign` is not required \u2014 authority derives from the delegation chain (agency law). Agent signers must have trust level 2 (Established) or higher.", "properties": { "signer_type": { "type": "string", "enum": [ "user", "customer", "agent", "api_key" ], "description": "Type of signer" }, "signer_id": { "type": "string", "description": "Identifier of who is signing (user ID, customer ID, etc.)" }, "signer_customer_id": { "type": "string", "nullable": true, "description": "Reference to customer record. When provided, authorization is validated: API key auth requires the deal to belong to this customer, delegation auth requires deals:sign in allowed_actions." }, "consent_to_sign": { "type": "boolean", "description": "Required for human (non-agent) signers. Confirms the signer consents to signing this document electronically under the Electronic Transactions Act 1999 (Cth). A `consent_to_sign_granted` audit event is recorded with IP address, user agent, and timestamp. Not required for agent signers (authority derived from delegation chain)." } } }, "DealCreateConfiguredRequest": { "type": "object", "description": "Request body for creating a fully configured deal atomically. Combines customer creation/matching, product validation, configuration checking, line item creation, and discount application in a single call. Requires agent:execute scope. Provide either items (explicit line items) or saved_config_id (load from saved configuration) \u2014 at least one is required.", "properties": { "saved_config_id": { "type": "string", "description": "Saved configuration short code or internal ID. If provided, items, currency, and customer info are inherited from the saved config. Prevents double-conversion \u2014 returns 409 if already converted." }, "customer": { "type": "object", "description": "Customer details. If email matches existing customer, that customer is used. Optional when saved_config_id is provided and the config has customer info.", "properties": { "name": { "type": "string", "description": "Customer name" }, "email": { "type": "string", "format": "email", "description": "Customer email" }, "phone": { "type": "string", "description": "Phone number" }, "company": { "type": "string", "description": "Company name" } }, "required": [ "name", "email" ] }, "customer_id": { "type": "string", "description": "Existing customer ID (alternative to customer object)" }, "items": { "type": "array", "description": "Line items with product configurations", "minItems": 1, "items": { "type": "object", "properties": { "product_id": { "type": "string", "description": "Product ID" }, "quantity": { "type": "integer", "minimum": 1, "description": "Quantity (default: 1)" }, "unit_price": { "type": "number", "description": "Unit price override" }, "name": { "type": "string", "description": "Line item name override" }, "configuration": { "type": "object", "description": "Product configuration", "properties": { "option_ids": { "type": "array", "items": { "type": "string" }, "description": "Selected option IDs" } } } }, "required": [ "product_id" ] } }, "discounts": { "type": "array", "description": "Discounts to apply", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "fixed", "percentage" ] }, "value": { "type": "number", "exclusiveMinimum": 0 }, "code": { "type": "string", "description": "Discount code" } }, "required": [ "type", "value" ] } }, "template_id": { "type": "string", "description": "Template ID for defaults" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency" }, "notes": { "type": "string", "description": "Deal notes" }, "metadata": { "type": "object", "description": "Custom metadata" }, "dry_run": { "type": "boolean", "description": "Validate without creating" } }, "required": [] }, "DealConvertSavedConfigResponse": { "type": "object", "description": "Response returned when a deal is created from a saved configuration (saved_config_id provided).", "properties": { "deal_id": { "type": "string", "description": "Created deal ID" }, "saved_config_code": { "type": "string", "description": "Short code of the saved configuration that was converted" }, "price_deltas": { "type": "array", "description": "Products whose prices changed between the saved snapshot and current prices", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "snapshot_price": { "type": "number" }, "current_price": { "type": "number" }, "difference": { "type": "number" } } } } } }, "DealPartialAcceptRequest": { "type": "object", "description": "Request body for partial acceptance of a deal. Removes rejected items, recalculates totals, transitions to 'partially_accepted' status, and fires a deal.partially_accepted webhook. The deal must be in 'in_progress' or 'pending_signature' status.", "properties": { "accepted_items": { "type": "array", "description": "Item IDs the buyer is keeping. Must contain at least one item.", "items": { "type": "string" }, "minItems": 1 }, "rejected_items": { "type": "array", "description": "Item IDs the buyer is rejecting. These will be removed from the deal and totals recalculated.", "items": { "type": "string" } }, "create_declined_deal": { "type": "boolean", "description": "When true, rejected items are copied to a new cancelled deal for audit/reporting. Defaults to false." } }, "required": [ "accepted_items" ], "additionalProperties": false }, "DealEscrowRequest": { "type": "object", "description": "Request body for creating an escrow hold on a deal. Authorizes a Stripe PaymentIntent with `capture_method: manual` \u2014 funds are held but not captured until all conditions are fulfilled or the escrow is released.", "properties": { "amount": { "type": "number", "format": "double", "description": "Amount to hold in escrow. Defaults to `deposit_required` if set, otherwise the deal total.", "minimum": 0 }, "currency": { "type": "string", "description": "ISO 4217 currency code. Defaults to the deal currency." }, "conditions": { "type": "array", "description": "Conditions that must be fulfilled before funds are released.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Condition type identifier (e.g. 'delivery', 'inspection', 'approval')" }, "config": { "type": "object", "description": "Condition-specific configuration", "additionalProperties": true } }, "required": [ "type" ] } }, "expires_in": { "type": "integer", "description": "Seconds until the escrow hold expires. Defaults to 604800 (7 days).", "minimum": 1 } }, "required": [ "conditions" ] }, "DealReleaseEscrowRequest": { "type": "object", "description": "Request body for releasing escrow funds to the seller. Captures the held PaymentIntent. Requires all conditions to be fulfilled or a manual override.", "properties": [], "additionalProperties": false }, "DealRefundEscrowRequest": { "type": "object", "description": "Request body for refunding escrow funds back to the buyer. Cancels the held PaymentIntent and returns funds.", "properties": { "reason": { "type": "string", "description": "Reason for the refund. Defaults to 'manual'.", "enum": [ "manual", "condition_failed", "deal_cancelled", "fraud", "duplicate" ] } }, "additionalProperties": false }, "DealFulfillConditionRequest": { "type": "object", "description": "Request body for marking an escrow condition as fulfilled. When all conditions are fulfilled, the escrow is eligible for release.", "properties": { "condition_id": { "type": "string", "description": "ID of the escrow condition to mark as fulfilled." }, "met_by": { "type": "string", "description": "Identifier of who fulfilled this condition (user ID, agent ID, or external reference).", "nullable": true } }, "required": [ "condition_id" ], "additionalProperties": false }, "DealRevokeCredentialRequest": { "type": "object", "description": "Request body for revoking the verifiable credential associated with a deal. Revoked credentials are immediately invalid and the revocation is published to the trust registry.", "properties": { "reason": { "type": "string", "description": "Reason for revocation. Defaults to 'manual'.", "enum": [ "manual", "deal_cancelled", "fraud", "expired", "superseded" ] } }, "additionalProperties": false }, "DealUnsignRequest": { "type": "object", "description": "Request body for removing a signature from a deal, reverting it to unsigned state. This is a legally significant reversal \u2014 the audit trail records the removal along with the reason. Requires `deals:write` scope.", "properties": { "reason": { "type": "string", "description": "Reason for removing the signature. Recommended for audit compliance." } }, "additionalProperties": false }, "DealRecordOutcomeRequest": { "type": "object", "description": "Request body for recording a deal outcome (win or loss). Outcome data feeds into analytics, forecasting, and AI win-rate suggestions.", "properties": { "reason": { "type": "string", "description": "Outcome reason code. Use a win/loss reason slug from your configured outcome reasons.", "minLength": 1 }, "notes": { "type": "string", "description": "Free-text notes about the outcome for internal reference.", "nullable": true }, "competitor_name": { "type": "string", "description": "Name of the competitor that won the deal (for loss outcomes). Used in competitive analytics.", "nullable": true } }, "required": [ "reason" ], "additionalProperties": false }, "DealSaveAsTemplateRequest": { "type": "object", "description": "Request body for saving a deal as a reusable template. The template captures the deal's line items, pricing, terms, and configuration so new deals can be created from it.", "properties": { "name": { "type": "string", "description": "Name for the new template.", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "description": "Optional description of what this template is for.", "nullable": true } }, "required": [ "name" ], "additionalProperties": false }, "DealSetTermsRequest": { "type": "object", "description": "Request body for setting structured deal terms. Terms define payment schedules, delivery conditions, obligations, SLAs, and more for machine-readable agent negotiation.", "properties": { "terms": { "$ref": "#/components/schemas/DealTerms" } }, "required": [ "terms" ] }, "DealTerms": { "type": "object", "description": "Machine-readable structured deal terms. Full JSON Schema available at GET /api/schemas/deal-terms.json", "additionalProperties": false, "properties": { "terms_schema_version": { "type": "string", "description": "Schema version for forward compatibility", "examples": [ "1.0" ] }, "payment_terms": { "type": "object", "description": "Payment schedule and conditions", "properties": { "type": { "type": "string", "enum": [ "upfront", "net_7", "net_14", "net_30", "net_60", "net_90", "milestone", "installment", "upon_delivery", "custom" ] }, "due_date": { "type": "string", "format": "date-time" }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "amount": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]{1,4})?$" }, "percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "due_date": { "type": "string", "format": "date-time" }, "due_on_event": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "invoiced", "paid", "overdue", "waived" ] } }, "required": [ "label" ] } }, "late_fee": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "value": { "type": "string" }, "grace_period_days": { "type": "integer", "minimum": 0 } } } } }, "delivery": { "type": "object", "description": "Delivery method, timeline, and conditions", "properties": { "method": { "type": "string", "enum": [ "digital", "physical", "service", "hybrid" ] }, "deadline": { "type": "string", "format": "date-time" }, "estimated_days": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "description" ] } }, "location": { "type": "string" } } }, "obligations": { "type": "array", "description": "Obligations each party must fulfill", "items": { "type": "object", "properties": { "party": { "type": "string", "enum": [ "seller", "buyer" ] }, "description": { "type": "string" }, "deadline": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "fulfilled", "waived", "breached" ] } }, "required": [ "party", "description" ] } }, "sla": { "type": "array", "description": "Service Level Agreements", "items": { "type": "object", "properties": { "metric": { "type": "string" }, "target": { "type": "string" }, "measurement_period": { "type": "string" }, "penalty": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "credit_percentage", "credit_fixed", "termination_right" ] }, "value": { "type": "string" } } } }, "required": [ "metric", "target" ] } }, "acceptance": { "type": "object", "description": "Acceptance criteria and review process", "properties": { "criteria": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "verifiable": { "type": "boolean" } }, "required": [ "description" ] } }, "review_period_days": { "type": "integer", "minimum": 0 }, "auto_accept": { "type": "boolean" } } }, "warranty": { "type": "object", "description": "Warranty or guarantee terms", "properties": { "duration_days": { "type": "integer", "minimum": 0 }, "scope": { "type": "string" }, "exclusions": { "type": "array", "items": { "type": "string" } } } }, "termination": { "type": "object", "description": "Termination and cancellation conditions", "properties": { "notice_period_days": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "trigger": { "type": "string" }, "penalty": { "type": "string" } }, "required": [ "trigger" ] } }, "refund_policy": { "type": "string", "enum": [ "full", "prorated", "none", "custom" ] } } }, "renewal": { "type": "object", "description": "Renewal and extension terms", "properties": { "type": { "type": "string", "enum": [ "auto", "manual", "none" ] }, "period": { "type": "string", "description": "ISO 8601 duration (e.g. P1Y, P6M)" }, "price_adjustment": { "type": "string", "enum": [ "fixed", "cpi", "negotiated", "percentage" ] }, "price_adjustment_value": { "type": "string" }, "notice_period_days": { "type": "integer", "minimum": 0 } } }, "custom_terms": { "type": "array", "description": "Additional custom terms not covered by the standard schema", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "description": "String, number, or boolean value" } }, "required": [ "key", "label", "value" ] } } } }, "DealTermsComparison": { "type": "object", "description": "Structured comparison of terms between two deals", "properties": { "deal_id_1": { "type": "string" }, "deal_id_2": { "type": "string" }, "has_terms": { "type": "object", "properties": { "deal_1": { "type": "boolean" }, "deal_2": { "type": "boolean" } } }, "sections": { "type": "object", "description": "Per-section comparison results" }, "summary": { "type": "array", "items": { "type": "string" }, "description": "Human-readable summary of differences" } } }, "DealUpdateRequest": { "type": "object", "description": "Request body for updating a deal. To change deal status, use POST /deals?action=transition instead.", "properties": { "customer_id": { "type": "string" }, "title": { "type": "string", "maxLength": 255 }, "description": { "type": "string", "maxLength": 65535 }, "notes": { "type": "string", "maxLength": 65535 }, "deal_type": { "type": "string", "enum": [ "one_time", "recurring" ] }, "billing_cycle": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ] }, "currency": { "type": "string" }, "tax_rate": { "type": "number", "format": "double", "description": "Tax rate \u2014 accepts either decimal (0.10) or percentage (10) for 10%. Values >= 1 are auto-normalized to decimal.", "minimum": 0, "maximum": 100 }, "deposit_required": { "type": "number", "format": "double", "description": "Required deposit amount in the deal currency. Must be >= 0.", "minimum": 0 }, "metadata": { "type": "object" } }, "if": { "properties": { "deal_type": { "const": "recurring" } }, "required": [ "deal_type" ] }, "then": { "required": [ "billing_cycle" ] } }, "CustomerCreateRequest": { "type": "object", "description": "Request body for creating a customer", "properties": { "name": { "type": "string", "description": "Customer name" }, "email": { "type": "string", "format": "email", "description": "Email address (must be unique)" }, "phone": { "type": "string", "description": "Phone number (will be normalized to E.164 format)" }, "address": { "type": "string" }, "company": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string", "description": "ISO country code" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "default": "active" } }, "required": [ "name", "email" ] }, "CustomerUpdateRequest": { "type": "object", "description": "Request body for updating a customer. All fields optional.", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "address": { "type": "string" }, "company": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "country": { "type": "string" }, "notes": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] } } }, "ProductCreateRequest": { "type": "object", "description": "Request body for creating a product", "properties": { "name": { "type": "string", "description": "Product name" }, "price": { "type": "number", "format": "double", "description": "Selling price", "minimum": 0 }, "description": { "type": "string" }, "sku": { "type": "string" }, "price_type": { "type": "string", "enum": [ "once_off", "recurring", "percentage", "metered" ], "default": "once_off" }, "billing_cycle": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ] }, "cost": { "type": "number", "format": "double", "default": 0 }, "type": { "type": "string", "enum": [ "product", "service", "subscription", "bundle" ], "default": "product" }, "unit": { "type": "string", "default": "unit" }, "tax_rate": { "type": "number", "format": "double", "description": "Tax rate \u2014 accepts either decimal (0.10) or percentage (10) for 10%. Values >= 1 are auto-normalized to decimal.", "minimum": 0, "maximum": 100, "default": 0 }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ], "default": "active" }, "stock_quantity": { "type": "integer", "default": 0 }, "track_inventory": { "type": "boolean", "description": "Whether inventory is tracked for this product" }, "low_stock_threshold": { "type": "integer", "description": "Stock level at which low stock alerts are triggered", "minimum": 0 }, "pricing_model": { "type": "string", "enum": [ "fixed", "tiered", "volume", "usage" ], "description": "Pricing model for this product" }, "metadata": { "type": "object", "description": "Optional metadata key-value pairs" }, "configuration_schema": { "type": "object", "description": "JSON schema defining configurable options for this product" }, "family_id": { "type": "string", "description": "Product family ID to associate this product with", "maxLength": 50 }, "requires_booking": { "type": "boolean", "default": false, "description": "Whether this product requires a booking" }, "session_duration": { "type": "integer", "description": "Session length in minutes", "minimum": 5, "maximum": 480 }, "buffer_time": { "type": "integer", "description": "Buffer time between sessions in minutes", "minimum": 0, "maximum": 120 }, "max_advance_days": { "type": "integer", "description": "Maximum days in advance a booking can be made", "minimum": 1, "maximum": 365, "default": 90 }, "min_advance_hours": { "type": "integer", "description": "Minimum hours lead time required for a booking", "minimum": 0, "maximum": 168, "default": 24 }, "allow_staff_selection": { "type": "boolean", "description": "Whether customers can choose their preferred staff member", "default": true }, "learn_more_url": { "type": "string", "maxLength": 2048, "description": "URL linking to more information about the product" }, "features": { "type": "array", "items": { "type": "string" }, "description": "List of product features" } }, "required": [ "name", "price" ] }, "ProductUpdateRequest": { "type": "object", "description": "Request body for updating a product. All fields optional.", "properties": { "name": { "type": "string" }, "price": { "type": "number", "format": "double", "minimum": 0 }, "description": { "type": "string" }, "sku": { "type": "string" }, "price_type": { "type": "string", "enum": [ "once_off", "recurring", "percentage", "metered" ] }, "billing_cycle": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ] }, "cost": { "type": "number", "format": "double" }, "type": { "type": "string", "enum": [ "product", "service", "subscription", "bundle" ] }, "unit": { "type": "string" }, "tax_rate": { "type": "number", "format": "double", "description": "Tax rate \u2014 accepts either decimal (0.10) or percentage (10) for 10%. Values >= 1 are auto-normalized to decimal.", "minimum": 0, "maximum": 100 }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "archived" ] }, "stock_quantity": { "type": "integer" }, "track_inventory": { "type": "boolean" }, "low_stock_threshold": { "type": "integer", "minimum": 0 }, "pricing_model": { "type": "string", "enum": [ "fixed", "tiered", "volume", "usage" ] }, "metadata": { "type": "object" }, "configuration_schema": { "type": "object" }, "family_id": { "type": "string", "maxLength": 50 }, "requires_booking": { "type": "boolean", "default": false, "description": "Whether this product requires a booking" }, "session_duration": { "type": "integer", "description": "Session length in minutes", "minimum": 5, "maximum": 480 }, "buffer_time": { "type": "integer", "description": "Buffer time between sessions in minutes", "minimum": 0, "maximum": 120 }, "max_advance_days": { "type": "integer", "description": "Maximum days in advance a booking can be made", "minimum": 1, "maximum": 365, "default": 90 }, "min_advance_hours": { "type": "integer", "description": "Minimum hours lead time required for a booking", "minimum": 0, "maximum": 168, "default": 24 }, "allow_staff_selection": { "type": "boolean", "description": "Whether customers can choose their preferred staff member", "default": true }, "learn_more_url": { "type": "string", "maxLength": 2048, "description": "URL linking to more information about the product" }, "features": { "type": "array", "items": { "type": "string" }, "description": "List of product features" } } }, "ContractCreateRequest": { "type": "object", "description": "Request body for creating a contract. When `deal_id` is provided, the fields `customer_id`, `title`, `value`, `start_date`, and `end_date` are auto-populated from the deal and become optional.", "properties": { "deal_id": { "type": "string", "description": "Deal ID to create a contract from. Auto-populates customer_id, title, value, currency, start_date, and end_date from the deal. Any of those fields may still be provided to override the deal-derived values." }, "customer_id": { "type": "string", "description": "Customer ID. Required unless `deal_id` is provided (auto-populated from deal)." }, "title": { "type": "string", "description": "Contract title. Required unless `deal_id` is provided (auto-populated from deal)." }, "value": { "type": "number", "format": "double", "description": "Contract value. Required unless `deal_id` is provided (auto-populated from deal total).", "minimum": 0 }, "start_date": { "type": "string", "format": "date", "description": "Start date (YYYY-MM-DD). Required unless `deal_id` is provided (defaults to today)." }, "end_date": { "type": "string", "format": "date", "description": "End date (YYYY-MM-DD, must be after start_date). Required unless `deal_id` is provided (defaults to one year from today)." }, "description": { "type": "string" }, "contract_number": { "type": "string" }, "currency": { "type": "string", "default": "USD" }, "renewal_type": { "type": "string", "enum": [ "manual", "auto", "none" ], "default": "manual" }, "payment_terms": { "type": "string" }, "notes": { "type": "string" }, "renewal_terms": { "type": "object", "description": "Structured renewal terms (JSON)" } }, "oneOf": [ { "required": [ "deal_id" ], "description": "Create from a deal \u2014 auto-populates customer_id, title, value, start_date, end_date." }, { "required": [ "customer_id", "title", "value", "start_date", "end_date" ], "description": "Create without a deal \u2014 all five core fields must be supplied explicitly." } ] }, "ContractUpdateRequest": { "type": "object", "description": "Request body for updating a contract. All fields optional.", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "value": { "type": "number", "format": "double" }, "currency": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "end_date": { "type": "string", "format": "date" }, "renewal_type": { "type": "string", "enum": [ "manual", "auto", "none" ] }, "payment_terms": { "type": "string" }, "notes": { "type": "string" }, "renewal_terms": { "type": "object", "description": "Structured renewal terms (JSON)" }, "status": { "type": "string", "enum": [ "draft", "pending", "signed", "active", "terminated", "expired" ], "description": "Contract status" }, "customer_id": { "type": "string", "description": "Reassign the contract to a different customer" }, "contract_number": { "type": "string", "description": "Update the contract reference number" } } }, "ApiKeyCreateRequest": { "type": "object", "description": "Request body for creating an API key", "properties": { "name": { "type": "string", "description": "Human-readable name for the key" }, "description": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "*", "*:read", "deals:read", "deals:write", "deals:sign", "customers:read", "customers:write", "products:read", "products:write", "contracts:read", "contracts:write", "webhooks:read", "webhooks:write", "audit:export", "agent:*", "agent:discover", "agent:negotiate", "agent:execute", "intelligence:read", "intelligence:write", "billing:read", "billing:write", "trust:read", "trust:write", "staff:read", "staff:write", "team:read", "team:write", "bookings:read", "bookings:write", "queue:read", "queue:write", "sites:read", "sites:write", "delegations:read", "delegations:write", "admin" ] }, "default": [ "*" ], "description": "Authorized scopes for the key" }, "environment": { "type": "string", "enum": [ "live", "test" ], "default": "live", "description": "Key environment. Live keys use `sb_live_*` prefix, test keys use `sb_test_*`." }, "rate_limit": { "type": "integer", "default": 1000, "description": "Requests per minute" }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiration timestamp (ISO 8601). Omit for no expiration." }, "allowed_origins": { "type": "array", "items": { "type": "string" }, "description": "List of allowed origins for CORS restriction of this API key" } }, "required": [ "name" ] }, "StructuredDealTerms": { "type": "object", "description": "Machine-readable structured deal terms for agent-to-agent commerce", "required": [ "pricing_model", "payment_terms" ], "properties": { "pricing_model": { "type": "string", "enum": [ "fixed", "per_unit", "tiered", "usage_based", "subscription" ], "description": "How pricing is calculated" }, "payment_terms": { "type": "string", "enum": [ "due_on_receipt", "net_15", "net_30", "net_60", "net_90", "custom" ], "description": "When payment is due" }, "payment_schedule": { "type": "object", "properties": { "frequency": { "type": "string", "enum": [ "one_time", "weekly", "monthly", "quarterly", "annually" ] }, "installments": { "type": "integer", "minimum": 1 } } }, "delivery_timeline": { "type": "object", "properties": { "value": { "type": "number", "exclusiveMinimum": 0 }, "unit": { "type": "string", "enum": [ "hours", "days", "weeks", "months" ] }, "description": { "type": "string" } } }, "sla": { "type": "object", "properties": { "uptime_percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "response_time_hours": { "type": "number", "exclusiveMinimum": 0 }, "resolution_time_hours": { "type": "number", "exclusiveMinimum": 0 }, "support_hours": { "type": "string" } } }, "cancellation_policy": { "type": "object", "properties": { "allowed": { "type": "boolean" }, "notice_days": { "type": "integer", "minimum": 0 }, "penalty_percentage": { "type": "number", "minimum": 0, "maximum": 100 }, "refund_policy": { "type": "string" } } }, "warranty": { "type": "object", "properties": { "included": { "type": "boolean" }, "duration_days": { "type": "integer", "minimum": 0 }, "description": { "type": "string" } } }, "auto_renew": { "type": "boolean", "description": "Whether the deal automatically renews" }, "custom_terms": { "type": "object", "additionalProperties": true, "description": "Custom key-value pairs for domain-specific terms" } } }, "NegotiationRound": { "type": "object", "description": "A single round in a deal negotiation", "properties": { "negotiation_id": { "type": "string" }, "deal_id": { "type": "string" }, "round_number": { "type": "integer" }, "proposer_type": { "type": "string", "enum": [ "agent", "user" ] }, "proposer_id": { "type": "string" }, "proposed_terms": { "$ref": "#/components/schemas/StructuredDealTerms" }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "proposed", "counter_proposed", "accepted", "rejected", "expired" ] }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "term_changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "from": [], "to": [] } } } } }, "Escrow": { "type": "object", "description": "Escrow hold created for a deal. Funds are authorized on Stripe (capture_method: manual) but not captured until all release conditions are fulfilled.", "properties": { "escrow_id": { "type": "string", "description": "Unique escrow identifier (prefix: esc_)" }, "deal_id": { "type": "string", "description": "Associated deal ID" }, "tenant_id": { "type": "string", "description": "Tenant that owns this escrow" }, "amount": { "type": "string", "description": "Amount held in escrow as a decimal string (e.g. \"250.00\")" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "status": { "type": "string", "enum": [ "held", "released", "refunded", "expired" ], "description": "Current escrow status" }, "stripe_payment_intent_id": { "type": "string", "description": "Stripe PaymentIntent ID for the authorized hold" }, "conditions": { "type": "array", "description": "Release conditions that must be fulfilled before funds can be captured", "items": { "type": "object", "properties": { "condition_id": { "type": "string", "description": "Unique condition identifier (prefix: cond_)" }, "escrow_id": { "type": "string" }, "condition_type": { "type": "string", "enum": [ "signature_collected", "delivery_confirmed", "inspection_period_elapsed", "manual_approval", "api_callback" ] }, "condition_config": { "type": [ "object", "null" ] }, "met_at": { "type": [ "string", "null" ], "format": "date-time" }, "met_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } } }, "conditions_summary": { "type": "object", "description": "Aggregate counts of fulfilled vs total conditions", "properties": { "total": { "type": "integer" }, "met": { "type": "integer" }, "remaining": { "type": "integer" }, "all_met": { "type": "boolean" } } }, "authorization": { "type": "object", "description": "Stripe authorization window health", "properties": { "last_authorized_at": { "type": [ "string", "null" ], "format": "date-time" }, "auth_expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "auth_days_remaining": { "type": [ "number", "null" ] }, "auth_status": { "type": [ "string", "null" ], "enum": [ "ok", "warning", "critical", null ], "description": "Authorization health: ok (>3 days remaining), warning (1-3 days), critical (<1 day)" } } }, "released_at": { "type": [ "string", "null" ], "format": "date-time" }, "refunded_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "last_authorized_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "escrow_id", "deal_id", "tenant_id", "amount", "currency", "status", "conditions", "conditions_summary", "created_at" ] }, "DealTemplate": { "type": "object", "description": "Reusable deal template for programmatic offer generation", "properties": { "template_id": { "type": "string" }, "tenant_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "template_data": { "type": "object", "description": "The full template payload (products, pricing, terms, etc.)" }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "usage_count": { "type": "integer", "description": "Number of deals created from this template (included in list responses)" }, "created_by": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DealTemplateListResponse": { "type": "object", "properties": { "error": { "type": "boolean" }, "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/DealTemplate" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer" } } } } } } }, "Webhook": { "type": "object", "description": "A registered webhook endpoint", "properties": { "webhook_id": { "type": "string", "description": "Unique webhook identifier (wh_*)", "examples": [ "wh_a1b2c3d4e5f6g7h8" ] }, "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" }, "description": "Subscribed event types" }, "description": { "type": [ "string", "null" ], "description": "Human-readable description" }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Current webhook status" }, "consecutive_failures": { "type": "integer", "description": "Number of consecutive delivery failures" }, "total_deliveries": { "type": "integer", "description": "Total delivery attempts made" }, "total_failures": { "type": "integer", "description": "Total failed deliveries" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the webhook was last triggered" }, "last_failure_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the last failure occurred" }, "last_failure_reason": { "type": "string", "nullable": true, "description": "Error message from the last failure" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "webhook_id", "url", "events", "status", "created_at" ] }, "WebhookEvent": { "type": "object", "description": "A webhook event record with sequence number for cursor-based replay", "properties": { "event_id": { "type": "string", "description": "Unique event identifier (whe_*)" }, "event_sequence": { "type": "integer", "format": "int64", "description": "Monotonically increasing sequence number per tenant" }, "event_type": { "type": "string", "description": "Event type (e.g. deal.created)" }, "payload": { "type": "object", "description": "Full event payload" }, "status": { "type": "string", "enum": [ "pending", "delivered", "partially_delivered", "failed" ], "description": "Aggregate delivery status" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "event_id", "event_sequence", "event_type", "payload", "status", "created_at" ] }, "DeadLetterEntry": { "type": "object", "description": "A failed webhook delivery that exhausted all retry attempts", "properties": { "delivery_id": { "type": "string", "description": "Unique delivery identifier (whd_*)" }, "event_id": { "type": "string", "nullable": true, "description": "Associated event ID" }, "webhook_id": { "type": "string", "description": "Target webhook ID" }, "webhook_url": { "type": "string", "nullable": true, "description": "Webhook endpoint URL" }, "webhook_description": { "type": "string", "nullable": true }, "event_type": { "type": "string" }, "payload": { "type": "object", "description": "Original event payload" }, "status": { "type": "string", "const": "failed" }, "attempts": { "type": "integer", "description": "Total delivery attempts made" }, "max_attempts": { "type": "integer", "description": "Maximum attempts allowed" }, "response_code": { "type": "integer", "nullable": true, "description": "Last HTTP response code" }, "response_body": { "type": "string", "nullable": true, "description": "Last response body (truncated to 1000 chars)" }, "error_message": { "type": "string", "nullable": true, "description": "Last error message" }, "is_replay": { "type": "boolean", "description": "Whether this was a replayed delivery" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "delivery_id", "webhook_id", "event_type", "payload", "status", "attempts", "max_attempts", "created_at" ] }, "Pagination": { "type": "object", "description": "Offset-based pagination metadata (returned when no cursor params are provided)", "properties": { "total": { "type": "integer", "description": "Total number of records available" }, "limit": { "type": "integer", "description": "Maximum results per page" }, "offset": { "type": "integer", "description": "Current offset" }, "count": { "type": "integer", "description": "Number of records in this response" } }, "required": [ "total", "limit", "offset", "count" ] }, "CursorPagination": { "type": "object", "description": "Cursor-based pagination metadata (returned when ?after= or ?before= is provided). Cursors are opaque base64 strings \u2014 do not parse or construct them.", "properties": { "has_more": { "type": "boolean", "description": "Whether there are more records beyond this page" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to pass as ?after= for the next page. Null when there are no more records." }, "prev_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor to pass as ?before= to go back to the previous page. Null on the first page." } }, "required": [ "has_more", "next_cursor", "prev_cursor" ] }, "ValidationResult": { "type": "object", "description": "Data returned when validate_only=true. The request body is valid but no resource was created.", "properties": { "valid": { "type": "boolean", "const": true, "description": "Always true when validation passes" }, "message": { "type": "string", "example": "Validation passed" } }, "required": [ "valid", "message" ] }, "ValidationResponse": { "type": "object", "description": "Response returned when validate_only=true. The request body was validated without persisting any data.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "$ref": "#/components/schemas/ValidationResult" } }, "required": [ "error", "success", "data" ] }, "BatchResult": { "type": "object", "description": "Result of a single operation within a batch request", "properties": { "index": { "type": "integer", "description": "Position of this operation in the original batch request (0-based)" }, "status": { "type": "integer", "description": "HTTP status code of the sub-operation (e.g. 200, 201, 204)" }, "data": { "type": "object", "description": "Response data from the sub-operation (varies by operation type)" } }, "required": [ "index", "status", "data" ] }, "BatchResponse": { "type": "object", "description": "Response envelope for POST /batch", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "results": { "type": "array", "description": "Results for each operation in the batch, in order", "items": { "$ref": "#/components/schemas/BatchResult" } }, "total": { "type": "integer", "description": "Total number of operations that completed successfully" } }, "required": [ "results", "total" ] } }, "required": [ "error", "success", "data" ] }, "SuccessResponse": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "description": "Response data (varies by endpoint)" } }, "required": [ "error", "success" ] }, "DashboardStatsResponse": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "counts": { "type": "object", "description": "Total record counts across core entities", "properties": { "customers": { "type": "integer", "description": "Total number of customers" }, "deals": { "type": "integer", "description": "Total number of deals" }, "products": { "type": "integer", "description": "Total number of products" }, "contracts": { "type": "integer", "description": "Total number of contracts" } }, "required": [ "customers", "deals", "products", "contracts" ] }, "pipeline": { "type": "object", "description": "Deal pipeline analytics including conversion rates, forecasts, and stage breakdowns", "properties": { "pipeline": { "type": "object", "description": "Deal counts and total value keyed by status (e.g. draft, in_progress, closed)", "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer" }, "total_value": { "type": "number" } } } }, "total_deals": { "type": "integer", "description": "Total deal count across all statuses" }, "conversion_rate": { "type": [ "number", "null" ], "description": "Percentage of completed deals that were closed (0-100)" }, "avg_days_to_close": { "type": [ "number", "null" ], "description": "Average days from deal creation to close" }, "avg_deal_value": { "type": [ "number", "null" ], "description": "Average value of closed deals" }, "total_revenue": { "type": [ "number", "null" ], "description": "Sum of all closed deal values" }, "active_pipeline_value": { "type": "number", "description": "Total value of all active (non-terminal) deals" }, "forecasted_revenue": { "type": [ "number", "null" ], "description": "Projected revenue from active pipeline using historical conversion rate" }, "forecast_confidence": { "type": [ "object", "null" ], "description": "Confidence interval for the revenue forecast" }, "bottleneck": { "type": [ "object", "null" ], "description": "The pipeline stage with the most active deals", "properties": { "status": { "type": "string" }, "count": { "type": "integer" } } }, "transitions": { "type": "object", "description": "Deal status transition counts keyed by 'from \u2192 to' string", "additionalProperties": { "type": "integer" } }, "subscription_metrics": { "type": [ "object", "null" ], "description": "MRR, ARR, and churn metrics for subscription deals" }, "outcome_summary": { "type": [ "object", "null" ], "description": "Top loss reasons and outcome breakdown for closed deals" } } }, "revenue_series": { "type": "array", "description": "Daily revenue totals for the last 30 days (closed deals only)", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "Calendar date (YYYY-MM-DD)" }, "total": { "type": "number", "description": "Sum of deal totals closed on this date" }, "count": { "type": "integer", "description": "Number of deals closed on this date" } }, "required": [ "date", "total", "count" ] } }, "attention": { "type": "object", "description": "Items that require merchant attention (expiring or stale records)", "properties": { "expiring_deals": { "type": "array", "description": "Active deals expiring within the next 7 days", "items": { "type": "object", "properties": { "deal_id": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "number" }, "expires_at": { "type": "string", "format": "date-time" }, "customer_id": { "type": "string" } } } }, "expiring_contracts": { "type": "array", "description": "Active or signed contracts ending within the next 30 days", "items": { "type": "object", "properties": { "contract_id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string" }, "value": { "type": "number" }, "end_date": { "type": "string", "format": "date" }, "customer_id": { "type": "string" } } } }, "stale_deals": { "type": "array", "description": "Active deals with no activity in the last 14 days", "items": { "type": "object", "properties": { "deal_id": { "type": "string" }, "status": { "type": "string" }, "total": { "type": "number" }, "updated_at": { "type": "string", "format": "date-time" }, "customer_id": { "type": "string" } } } } }, "required": [ "expiring_deals", "expiring_contracts", "stale_deals" ] } }, "required": [ "counts", "pipeline", "revenue_series", "attention" ] } }, "required": [ "error", "success", "data" ] }, "PaymentIntentResponse": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "client_secret": { "type": "string", "description": "Stripe PaymentIntent client secret for frontend confirmation" }, "payment_intent_id": { "type": "string", "description": "Stripe PaymentIntent ID" }, "amount": { "type": "number", "description": "Payment amount" }, "currency": { "type": "string", "description": "ISO 4217 currency code" } }, "required": [ "client_secret", "payment_intent_id", "amount", "currency" ] } }, "required": [ "error", "success", "data" ] }, "DeleteResponse": { "type": "object", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" } }, "required": [ "message" ] } }, "required": [ "error", "success", "data" ] }, "CustomerDeleteResponse": { "type": "object", "description": "Response returned when a customer is permanently deleted", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "customer_id": { "type": "string", "description": "ID of the deleted customer" } }, "required": [ "message", "customer_id" ] } }, "required": [ "error", "success", "data" ] }, "DealDeleteResponse": { "type": "object", "description": "Response returned when an already-cancelled deal is permanently deleted", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "deal_id": { "type": "string", "description": "ID of the deleted deal" } }, "required": [ "message", "deal_id" ] } }, "required": [ "error", "success", "data" ] }, "ProductDeleteResponse": { "type": "object", "description": "Response returned when a product is permanently deleted", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "product_id": { "type": "string", "description": "ID of the deleted product" } }, "required": [ "message", "product_id" ] } }, "required": [ "error", "success", "data" ] }, "ContractDeleteResponse": { "type": "object", "description": "Response returned when a contract is permanently deleted", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "contract_id": { "type": "integer", "description": "ID of the deleted contract" } }, "required": [ "message", "contract_id" ] } }, "required": [ "error", "success", "data" ] }, "WebhookDeleteResponse": { "type": "object", "description": "Response returned when a webhook is permanently deleted", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "webhook_id": { "type": "string", "description": "ID of the deleted webhook" } }, "required": [ "message", "webhook_id" ] } }, "required": [ "error", "success", "data" ] }, "BundleRuleDeleteResponse": { "type": "object", "description": "Response returned when a bundle pricing rule is permanently deleted", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "bundle_id": { "type": "string", "description": "ID of the deleted bundle rule" } }, "required": [ "message", "bundle_id" ] } }, "required": [ "error", "success", "data" ] }, "CompatibilityRuleDeleteResponse": { "type": "object", "description": "Response returned when a compatibility rule is permanently deleted", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "message": { "type": "string", "description": "Success message" }, "rule_id": { "type": "string", "description": "ID of the deleted compatibility rule" } }, "required": [ "message", "rule_id" ] } }, "required": [ "error", "success", "data" ] }, "BundleRule": { "type": "object", "description": "A bundle pricing rule that applies a discount when a qualifying combination of product options is selected", "properties": { "bundle_id": { "type": "string", "description": "Unique identifier for the bundle rule" }, "product_id": { "type": "string", "nullable": true, "description": "Product this rule applies to, or null for rules that apply across all products" }, "name": { "type": "string", "description": "Display name for the bundle rule" }, "discount_type": { "type": "string", "enum": [ "fixed", "percent" ], "description": "Whether the discount is a fixed currency amount or a percentage" }, "discount_value": { "type": "number", "description": "Discount amount (currency units for fixed, 0-100 for percent)" }, "min_options": { "type": "integer", "description": "Minimum number of bundle options that must be selected to trigger the discount" }, "is_active": { "type": "boolean", "description": "Whether this bundle rule is currently active" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the rule was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the rule was last updated" }, "option_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of the product options that form this bundle" }, "options": { "type": "array", "items": { "type": "object", "properties": { "option_id": { "type": "string", "description": "Option identifier" }, "option_name": { "type": "string", "description": "Human-readable option name" } }, "required": [ "option_id", "option_name" ] }, "description": "Options included in this bundle with their display names" } }, "required": [ "bundle_id", "name", "discount_type", "discount_value", "min_options", "is_active", "created_at", "updated_at", "option_ids", "options" ] }, "BundleRuleResponse": { "type": "object", "description": "Success response containing a single bundle pricing rule", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "bundle": { "$ref": "#/components/schemas/BundleRule" } }, "required": [ "bundle" ] } }, "required": [ "error", "success", "data" ] }, "BundleRuleListResponse": { "type": "object", "description": "Success response containing a paginated list of bundle pricing rules", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "bundles": { "type": "array", "items": { "$ref": "#/components/schemas/BundleRule" }, "description": "List of bundle pricing rules" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of matching records" }, "limit": { "type": "integer", "description": "Maximum records returned per page" }, "offset": { "type": "integer", "description": "Number of records skipped" }, "count": { "type": "integer", "description": "Number of records in this response" } }, "required": [ "total", "limit", "offset", "count" ] } }, "required": [ "bundles", "pagination" ] } }, "required": [ "error", "success", "data" ] }, "CompatibilityRule": { "type": "object", "description": "A compatibility rule defining a requires, excludes, or includes_price relationship between two product options", "properties": { "rule_id": { "type": "string", "description": "Unique identifier for the compatibility rule" }, "product_id": { "type": "string", "nullable": true, "description": "Product this rule applies to, or null for rules that apply across all products" }, "source_option_id": { "type": "string", "description": "The option that triggers this rule when selected" }, "target_option_id": { "type": "string", "description": "The option affected by this rule" }, "rule_type": { "type": "string", "enum": [ "requires", "excludes", "includes_price" ], "description": "Type of compatibility relationship: requires (source forces target), excludes (source prevents target), includes_price (source adds target price)" }, "message": { "type": "string", "nullable": true, "description": "Optional message shown to users when this rule is triggered" }, "is_active": { "type": "boolean", "description": "Whether this compatibility rule is currently enforced" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the rule was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the rule was last updated" }, "source_option_name": { "type": "string", "nullable": true, "description": "Display name of the source option" }, "target_option_name": { "type": "string", "nullable": true, "description": "Display name of the target option" }, "product_name": { "type": "string", "nullable": true, "description": "Display name of the product this rule is scoped to" } }, "required": [ "rule_id", "source_option_id", "target_option_id", "rule_type", "is_active", "created_at", "updated_at" ] }, "CompatibilityRuleResponse": { "type": "object", "description": "Success response containing a single compatibility rule", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/CompatibilityRule" } }, "required": [ "rule" ] } }, "required": [ "error", "success", "data" ] }, "CompatibilityRuleListResponse": { "type": "object", "description": "Success response containing a paginated list of compatibility rules", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/CompatibilityRule" }, "description": "List of compatibility rules" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of matching records" }, "limit": { "type": "integer", "description": "Maximum records returned per page" }, "offset": { "type": "integer", "description": "Number of records skipped" }, "count": { "type": "integer", "description": "Number of records in this response" } }, "required": [ "total", "limit", "offset", "count" ] } }, "required": [ "rules", "pagination" ] } }, "required": [ "error", "success", "data" ] }, "ErrorResponse": { "type": "object", "description": "Structured error response with machine-readable recovery hints for AI agents", "properties": { "error": { "type": "boolean", "const": true }, "code": { "type": "string", "description": "Machine-readable error code in dotted notation (e.g. 'validation_error.invalid_fields', 'conflict.deal_already_closed')", "examples": [ "validation_error.invalid_fields", "not_found", "conflict.deal_already_closed", "authentication_error.invalid_credentials", "rate_limited", "internal_error" ] }, "category": { "type": "string", "description": "Error category for programmatic error handling", "enum": [ "validation_error", "authentication_error", "authorization_error", "not_found", "conflict", "rate_limited", "transient_error", "internal_error" ] }, "message": { "type": "string", "description": "Human-readable error message" }, "recovery": { "type": "object", "description": "Machine-readable recovery hints for AI agents and automated systems", "properties": { "action": { "type": "string", "description": "Recommended recovery action", "enum": [ "fix_request", "authenticate", "check_permissions", "check_resource_id", "resolve_conflict", "refetch_and_retry", "retry", "contact_support", "check_status", "none" ] }, "retryable": { "type": "boolean", "description": "Whether the request can be retried (possibly after a delay)" }, "retry_after_seconds": { "type": "integer", "description": "Recommended delay before retrying (only present when retryable is true)" }, "max_retries": { "type": "integer", "description": "Maximum recommended retry attempts" }, "hint": { "type": "string", "description": "Human-readable recovery guidance" } }, "required": [ "action", "retryable" ] }, "ref": { "type": "string", "description": "Error trace ID for support correlation (present when Logger is available)" }, "details": { "type": "object", "description": "Additional error details", "properties": { "fields": { "type": "object", "description": "Field-level validation errors (for validation_error category)", "additionalProperties": { "type": "object", "properties": { "code": { "type": "string", "description": "Field error code (e.g. 'required', 'invalid', 'invalid_value')" }, "message": { "type": "string", "description": "Human-readable field error message" }, "allowed_values": { "type": "array", "items": { "type": "string" }, "description": "List of allowed values (when applicable)" } }, "required": [ "code", "message" ] } } } } }, "required": [ "error", "code", "category", "message", "recovery" ] }, "DelegationProposal": { "type": "object", "properties": { "id": { "type": "string", "description": "Proposal ID (starts with dprop_)" }, "tenant_id": { "type": "string" }, "proposer_api_key_id": { "type": "string" }, "target_api_key_id": { "type": "string" }, "parent_delegation_id": { "type": "string", "nullable": true }, "proposed_actions": { "type": "array", "items": { "type": "string" } }, "proposed_spending_limits": { "type": "object", "nullable": true }, "proposed_duration_hours": { "type": "integer", "nullable": true }, "message": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected", "countered", "expired" ] }, "round": { "type": "integer" }, "previous_proposal_id": { "type": "string", "nullable": true }, "response_message": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Site": { "type": "object", "properties": { "site_id": { "type": "string", "example": "site_a1b2c3d4e5f6" }, "domain": { "type": "string", "example": "mystore.com" }, "name": { "type": "string", "example": "My Store" }, "status": { "type": "string", "enum": [ "active", "inactive", "coming_soon" ], "example": "coming_soon" }, "analytics_enabled": { "type": "boolean", "example": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "site_id", "domain", "name", "status", "analytics_enabled" ] }, "DealSettlement": { "type": "object", "properties": { "id": { "type": "string", "description": "Settlement ID (setl_...)" }, "deal_id": { "type": "string" }, "participant_id": { "type": "string" }, "amount": { "type": "string", "description": "Settlement amount (decimal string)" }, "currency": { "type": "string", "example": "USD" }, "status": { "type": "string", "enum": [ "pending", "processing", "settled", "failed" ], "description": "pending=awaiting execution; processing=transfer initiated; settled=complete; failed=transfer error" }, "payment_method": { "type": "string", "enum": [ "usdc", "stripe", "pending" ], "description": "usdc for agent participants; stripe for merchant participants with Stripe Connect" }, "stripe_transfer_id": { "type": "string", "nullable": true }, "usdc_tx_id": { "type": "string", "nullable": true }, "attempts": { "type": "integer" }, "error_message": { "type": "string", "nullable": true }, "settled_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "participant": { "type": "object", "properties": { "role": { "type": "string" }, "scope_description": { "type": "string", "nullable": true }, "revenue_share_percent": { "type": "number", "nullable": true }, "agent_name": { "type": "string", "nullable": true }, "agent_key_id": { "type": "string", "nullable": true }, "is_agent": { "type": "boolean" } } } } }, "StaffCreateRequest": { "type": "object", "description": "Request body for creating a new staff member", "required": [ "display_name" ], "properties": { "display_name": { "type": "string", "maxLength": 255, "description": "Full display name of the staff member" }, "title": { "type": "string", "maxLength": 255, "description": "Job title or role (e.g. Senior Consultant)" }, "bio": { "type": "string", "maxLength": 65535, "description": "Short biography shown to customers" }, "avatar_url": { "type": "string", "maxLength": 2048, "description": "URL of the staff member's profile photo" }, "user_id": { "type": "string", "maxLength": 50, "description": "Linked tenant user account ID" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active", "description": "Availability status" }, "max_daily_sessions": { "type": "integer", "minimum": 1, "maximum": 100, "default": 8, "description": "Maximum number of bookings the staff member can take per day" }, "default_session_duration": { "type": "integer", "minimum": 5, "maximum": 480, "default": 60, "description": "Default booking duration in minutes" }, "buffer_time": { "type": "integer", "minimum": 0, "maximum": 240, "default": 15, "description": "Gap in minutes between consecutive bookings" }, "timezone": { "type": "string", "maxLength": 100, "default": "UTC", "description": "IANA timezone identifier (e.g. America/New_York)" }, "metadata": { "type": "object", "description": "Arbitrary key-value metadata (max 3 levels deep, 4KB serialized)" }, "schedule": { "type": "array", "maxItems": 7, "description": "Weekly recurring availability \u2014 one entry per active day", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6, "description": "0 = Sunday, 6 = Saturday" }, "start_time": { "type": "string", "description": "Start time in HH:MM:SS format" }, "end_time": { "type": "string", "description": "End time in HH:MM:SS format" }, "is_available": { "type": "boolean" } }, "required": [ "day_of_week" ] } }, "product_ids": { "type": "array", "maxItems": 100, "items": { "type": "string" }, "description": "Product IDs this staff member is qualified to deliver" } } }, "StaffUpdateRequest": { "type": "object", "description": "Request body for updating an existing staff member (all fields optional)", "properties": { "display_name": { "type": "string", "maxLength": 255, "description": "Full display name of the staff member" }, "title": { "type": "string", "maxLength": 255, "description": "Job title or role" }, "bio": { "type": "string", "maxLength": 65535, "description": "Short biography shown to customers" }, "avatar_url": { "type": "string", "maxLength": 2048, "description": "URL of the staff member's profile photo" }, "user_id": { "type": "string", "maxLength": 50, "description": "Linked tenant user account ID" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Availability status" }, "max_daily_sessions": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of bookings per day" }, "default_session_duration": { "type": "integer", "minimum": 5, "maximum": 480, "description": "Default booking duration in minutes" }, "buffer_time": { "type": "integer", "minimum": 0, "maximum": 240, "description": "Gap in minutes between consecutive bookings" }, "timezone": { "type": "string", "maxLength": 100, "description": "IANA timezone identifier" }, "metadata": { "type": "object", "description": "Arbitrary key-value metadata (max 3 levels deep, 4KB serialized)" }, "schedule": { "type": "array", "maxItems": 7, "description": "Replace the weekly recurring availability schedule", "items": { "type": "object", "properties": { "day_of_week": { "type": "integer", "minimum": 0, "maximum": 6 }, "start_time": { "type": "string" }, "end_time": { "type": "string" }, "is_available": { "type": "boolean" } }, "required": [ "day_of_week" ] } }, "product_ids": { "type": "array", "maxItems": 100, "items": { "type": "string" }, "description": "Replace all product assignments with this list" } } }, "WidgetConfigItem": { "type": "object", "description": "Widget configuration object returned in authenticated list responses", "properties": { "widget_id": { "type": "string", "description": "Unique widget identifier (wgt_*)" }, "title": { "type": "string", "description": "Widget display title" }, "theme_color": { "type": "string", "description": "Primary theme color as CSS hex (e.g. #2563eb)" }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "CAD", "AUD", "NZD", "CHF", "JPY", "MXN", "BRL" ], "description": "ISO 4217 settlement currency code" }, "display_currencies": { "type": "array", "items": { "type": "string" }, "description": "ISO 4217 currency codes available for buyer display conversion" }, "products": { "type": "string", "description": "Comma-separated product IDs available in the widget" }, "cta_text": { "type": "string", "description": "Custom call-to-action button label" }, "step_1_name": { "type": "string", "description": "Custom label for the Products step" }, "step_2_name": { "type": "string", "description": "Custom label for the Configure step" }, "step_3_name": { "type": "string", "description": "Custom label for the Summary step" }, "step_4_name": { "type": "string", "description": "Custom label for the Negotiate step (8-step flow)" }, "step_5_name": { "type": "string", "description": "Custom label for the Customer/Details step (8-step flow)" }, "step_6_name": { "type": "string", "description": "Custom label for the Terms step (8-step flow)" }, "step_7_name": { "type": "string", "description": "Custom label for the Payment step (8-step flow)" }, "step_8_name": { "type": "string", "description": "Custom label for the Confirmation step (8-step flow)" }, "config_version": { "type": "integer", "description": "Step-name mapping version: 1=legacy 5-step, 2=current 8-step" }, "enable_promo_codes": { "type": "boolean", "description": "Whether buyers can enter promotional codes" }, "enable_discount_step": { "type": "boolean", "description": "Whether the dedicated discount step is shown" }, "auto_discounts": { "type": "object", "nullable": true, "description": "Automatic discount rules based on cart contents or quantity thresholds" }, "contract_template_id": { "type": "string", "nullable": true, "description": "Contract template used for terms shown to buyers" }, "deal_template_id": { "type": "string", "nullable": true, "description": "Deal template used to pre-populate the widget" }, "enable_negotiation": { "type": "boolean", "description": "Whether buyers can submit counter-offers" }, "negotiation_mode": { "type": "string", "enum": [ "price_only", "item_selection", "terms_only", "full" ], "description": "Negotiation scope" }, "auto_accept_threshold": { "type": "number", "nullable": true, "description": "Minimum counter-offer percentage auto-accepted (0-100)" }, "locale": { "type": "string", "nullable": true, "description": "BCP 47 language tag for the widget UI (e.g. en, en-AU, es, de)" }, "locale_overrides": { "type": "object", "nullable": true, "description": "Custom string overrides for widget i18n labels" }, "show_social_proof": { "type": "boolean", "description": "Whether social proof indicators are shown" }, "show_smart_defaults": { "type": "boolean", "description": "Whether AI-suggested smart defaults are pre-filled" }, "social_proof_threshold": { "type": "integer", "description": "Minimum completed deals before social proof is displayed" }, "show_stock_quantity": { "type": "boolean", "description": "Whether remaining stock quantity is shown" }, "saved_config_ttl_days": { "type": "integer", "description": "Days a buyer's saved configuration is retained (1-365)" }, "payment_type": { "type": "string", "enum": [ "full", "deposit", "quote" ], "description": "Payment collection mode" }, "deposit_type": { "type": "string", "enum": [ "fixed", "percentage" ], "nullable": true, "description": "Deposit calculation method" }, "deposit_value": { "type": "number", "nullable": true, "description": "Deposit amount (fixed) or percentage (0-100)" }, "deposit_note": { "type": "string", "nullable": true, "description": "Note about remaining balance shown to buyer" }, "logo_url": { "type": "string", "nullable": true, "description": "Merchant logo URL displayed in the widget header" }, "font_family": { "type": "string", "nullable": true, "description": "CSS font-family applied to widget text" }, "custom_css": { "type": "string", "nullable": true, "description": "Custom CSS injected into the widget shadow DOM" }, "dark_mode": { "type": "boolean", "description": "Whether the widget renders in dark mode by default" }, "border_radius": { "type": "integer", "nullable": true, "description": "Border radius in pixels applied to cards and buttons (0-16)" }, "button_style": { "type": "string", "enum": [ "filled", "outlined", "text" ], "description": "Primary button visual style" }, "product_selection_mode": { "type": "string", "enum": [ "single", "multiple" ], "description": "Whether the widget allows selecting one or multiple products" }, "analytics_mode": { "type": "string", "nullable": true, "description": "Analytics targets (gtm, ga4, segment, callback \u2014 comma-separated)" }, "analytics_callback": { "type": "string", "nullable": true, "description": "Global JavaScript function name invoked with analytics events" }, "analytics_consent": { "type": "boolean", "description": "Whether analytics requires explicit buyer consent before firing" }, "booking_config": { "type": "object", "nullable": true, "description": "Widget-level booking step configuration (enable_booking, staff_ids, duration, availability_source, custom_hours, buffer_time, max_advance_days, confirmation)" }, "signature_mode": { "type": "string", "enum": [ "checkbox", "type", "draw", "digital" ], "description": "Method used to capture buyer signature on the terms step" }, "step_order": { "type": "string", "nullable": true, "description": "Comma-separated step names defining custom widget step order" }, "skip_steps": { "type": "string", "nullable": true, "description": "Comma-separated step names omitted from the widget flow" }, "site_id": { "type": "string", "description": "ID of the site this widget is associated with" }, "site_name": { "type": "string", "description": "Display name of the associated site" }, "site_domain": { "type": "string", "description": "Domain of the associated site (e.g. example.com)" }, "api_key": { "type": "string", "description": "Publishable API key (sb_pub_*) for embedding this widget" }, "api_key_id": { "type": "string", "description": "ID of the associated publishable API key" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Widget status" }, "created_at": { "type": "string", "description": "ISO 8601 datetime when the widget was created" } } }, "WidgetConfigSingle": { "allOf": [ { "$ref": "#/components/schemas/WidgetConfigItem" }, { "type": "object", "description": "Additional fields present only in authenticated single-widget GET responses", "properties": { "network_config": { "type": "object", "nullable": true, "description": "Widget network and retry configuration overrides (fetch_timeout, retry_max, retry_base_delay, retry_max_delay, retry_jitter, total_retry_budget, cache_products_ttl, cache_config_ttl, cache_assets_ttl, negotiate_poll_interval, negotiate_sse_timeout, heartbeat_interval, heartbeat_offline_interval, abandon_timeout)" }, "step_conditions": { "type": "object", "nullable": true, "description": "Conditional step visibility rules keyed by step name (e.g. {\"terms\": {\"minTotal\": 1000}})" } } } ] }, "WidgetConfigUpdateResponse": { "type": "object", "description": "Updated widget configuration returned after a successful PATCH. Contains all config fields but excludes site info and api_key (those do not change on update).", "properties": { "widget_id": { "type": "string", "description": "Unique widget identifier (wgt_*)" }, "title": { "type": "string", "description": "Widget display title" }, "theme_color": { "type": "string", "description": "Primary theme color as CSS hex (e.g. #2563eb)" }, "currency": { "type": "string", "enum": [ "USD", "EUR", "GBP", "CAD", "AUD", "NZD", "CHF", "JPY", "MXN", "BRL" ], "description": "ISO 4217 settlement currency code" }, "display_currencies": { "type": "array", "items": { "type": "string" }, "description": "ISO 4217 currency codes available for buyer display conversion" }, "products": { "type": "string", "description": "Comma-separated product IDs available in the widget" }, "cta_text": { "type": "string", "description": "Custom call-to-action button label" }, "step_1_name": { "type": "string", "description": "Custom label for the Products step" }, "step_2_name": { "type": "string", "description": "Custom label for the Configure step" }, "step_3_name": { "type": "string", "description": "Custom label for the Summary step" }, "step_4_name": { "type": "string", "description": "Custom label for the Negotiate step (8-step flow)" }, "step_5_name": { "type": "string", "description": "Custom label for the Customer/Details step (8-step flow)" }, "step_6_name": { "type": "string", "description": "Custom label for the Terms step (8-step flow)" }, "step_7_name": { "type": "string", "description": "Custom label for the Payment step (8-step flow)" }, "step_8_name": { "type": "string", "description": "Custom label for the Confirmation step (8-step flow)" }, "config_version": { "type": "integer", "description": "Step-name mapping version: 1=legacy 5-step, 2=current 8-step" }, "enable_promo_codes": { "type": "boolean", "description": "Whether buyers can enter promotional codes" }, "enable_discount_step": { "type": "boolean", "description": "Whether the dedicated discount step is shown" }, "auto_discounts": { "type": "object", "nullable": true, "description": "Automatic discount rules based on cart contents or quantity thresholds" }, "contract_template_id": { "type": "string", "nullable": true, "description": "Contract template used for terms shown to buyers" }, "deal_template_id": { "type": "string", "nullable": true, "description": "Deal template used to pre-populate the widget" }, "enable_negotiation": { "type": "boolean", "description": "Whether buyers can submit counter-offers" }, "negotiation_mode": { "type": "string", "enum": [ "price_only", "item_selection", "terms_only", "full" ], "description": "Negotiation scope" }, "auto_accept_threshold": { "type": "number", "nullable": true, "description": "Minimum counter-offer percentage auto-accepted (0-100)" }, "locale": { "type": "string", "nullable": true, "description": "BCP 47 language tag for the widget UI (e.g. en, en-AU, es, de)" }, "locale_overrides": { "type": "object", "nullable": true, "description": "Custom string overrides for widget i18n labels" }, "show_social_proof": { "type": "boolean", "description": "Whether social proof indicators are shown" }, "show_smart_defaults": { "type": "boolean", "description": "Whether AI-suggested smart defaults are pre-filled" }, "social_proof_threshold": { "type": "integer", "description": "Minimum completed deals before social proof is displayed" }, "show_stock_quantity": { "type": "boolean", "description": "Whether remaining stock quantity is shown" }, "saved_config_ttl_days": { "type": "integer", "description": "Days a buyer's saved configuration is retained (1-365)" }, "payment_type": { "type": "string", "enum": [ "full", "deposit", "quote" ], "description": "Payment collection mode" }, "deposit_type": { "type": "string", "enum": [ "fixed", "percentage" ], "nullable": true, "description": "Deposit calculation method" }, "deposit_value": { "type": "number", "nullable": true, "description": "Deposit amount (fixed) or percentage (0-100)" }, "deposit_note": { "type": "string", "nullable": true, "description": "Note about remaining balance shown to buyer" }, "logo_url": { "type": "string", "nullable": true, "description": "Merchant logo URL displayed in the widget header" }, "font_family": { "type": "string", "nullable": true, "description": "CSS font-family applied to widget text" }, "custom_css": { "type": "string", "nullable": true, "description": "Custom CSS injected into the widget shadow DOM" }, "dark_mode": { "type": "boolean", "description": "Whether the widget renders in dark mode by default" }, "border_radius": { "type": "integer", "nullable": true, "description": "Border radius in pixels applied to cards and buttons (0-16)" }, "button_style": { "type": "string", "enum": [ "filled", "outlined", "text" ], "description": "Primary button visual style" }, "product_selection_mode": { "type": "string", "enum": [ "single", "multiple" ], "description": "Whether the widget allows selecting one or multiple products" }, "analytics_mode": { "type": "string", "nullable": true, "description": "Analytics targets (gtm, ga4, segment, callback \u2014 comma-separated)" }, "analytics_callback": { "type": "string", "nullable": true, "description": "Global JavaScript function name invoked with analytics events" }, "analytics_consent": { "type": "boolean", "description": "Whether analytics requires explicit buyer consent before firing" }, "booking_config": { "type": "object", "nullable": true, "description": "Widget-level booking step configuration (enable_booking, staff_ids, duration, availability_source, custom_hours, buffer_time, max_advance_days, confirmation)" }, "signature_mode": { "type": "string", "enum": [ "checkbox", "type", "draw", "digital" ], "description": "Method used to capture buyer signature on the terms step" }, "step_order": { "type": "string", "nullable": true, "description": "Comma-separated step names defining custom widget step order" }, "skip_steps": { "type": "string", "nullable": true, "description": "Comma-separated step names omitted from the widget flow" }, "network_config": { "type": "object", "nullable": true, "description": "Widget network and retry configuration overrides" }, "step_conditions": { "type": "object", "nullable": true, "description": "Conditional step visibility rules keyed by step name" } } }, "WidgetConfigPublic": { "type": "object", "properties": { "merchant_available": { "type": "boolean", "description": "Whether the merchant has sufficient credit to accept new deals. False when credit balance is below deal cost." }, "merchant_contact": { "type": "object", "nullable": true, "description": "Merchant contact info for buyer fallback when merchant_available is false.", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" } } }, "display_currencies": { "type": "array", "items": { "type": "string" }, "description": "ISO 4217 currency codes available for buyer display conversion in the widget" }, "payment_type": { "type": "string", "enum": [ "full", "deposit", "quote" ], "description": "Payment collection mode" }, "deposit_type": { "type": "string", "enum": [ "fixed", "percentage" ], "nullable": true, "description": "Deposit calculation method" }, "deposit_value": { "type": "number", "nullable": true, "description": "Deposit amount (fixed) or percentage (0-100)" }, "deposit_note": { "type": "string", "nullable": true, "description": "Note about remaining balance shown to buyer" }, "deal_template_id": { "type": "string", "nullable": true, "description": "Deal template ID used to pre-populate the widget with template products and pricing" }, "deal_template": { "type": "object", "nullable": true, "description": "Deal template data for pre-populating the widget. Included when deal_template_id is set and template is active.", "properties": { "name": { "type": "string", "description": "Template name, used as widget title fallback" }, "template_data": { "type": "object", "description": "Template configuration including line_items, discounts, terms, and metadata", "properties": { "title": { "type": "string" }, "currency": { "type": "string" }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": "string" }, "name": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "number" } } } }, "discounts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "fixed", "percentage" ] }, "value": { "type": "number" } } } } } } } }, "booking_config": { "type": "object", "nullable": true, "description": "Widget-level booking step configuration (enable_booking, staff_ids, duration, availability_source, custom_hours, buffer_time, max_advance_days, confirmation)" }, "config_version": { "type": "integer", "description": "Configuration version number for cache invalidation", "default": 1 }, "product_selection_mode": { "type": "string", "enum": [ "single", "multiple" ], "description": "Whether the widget allows selecting one or multiple products", "default": "single" }, "ab_test": { "type": "object", "nullable": true, "description": "Active A/B test configuration, or null if no test is running", "properties": { "ab_test_id": { "type": "string" }, "api_key_a": { "type": "string" }, "api_key_b": { "type": "string" }, "weight_b": { "type": "number" }, "widget_a_id": { "type": "string" }, "widget_b_id": { "type": "string" } } }, "widget_id": { "type": "string", "description": "Unique identifier for this widget configuration" }, "updated_at": { "type": "string", "description": "MD5 content hash of the config. Changes whenever any field is updated. Used by the widget SDK to invalidate the product cache." }, "title": { "type": "string", "description": "Widget display title shown in the header" }, "theme_color": { "type": "string", "description": "Primary theme color as a CSS hex value (e.g. #2563eb)" }, "currency": { "type": "string", "description": "ISO 4217 settlement currency code (e.g. USD, AUD, EUR)" }, "products": { "type": "string", "description": "Comma-separated product IDs available for selection in the widget" }, "cta_text": { "type": "string", "description": "Custom call-to-action button label (e.g. 'Get Started', 'Buy Now')" }, "step_1_name": { "type": "string", "description": "Custom label for the Products step" }, "step_2_name": { "type": "string", "description": "Custom label for the Configure step" }, "step_3_name": { "type": "string", "description": "Custom label for the Summary step" }, "step_4_name": { "type": "string", "description": "Custom label for the Negotiate step (8-step flow)" }, "step_5_name": { "type": "string", "description": "Custom label for the Customer/Details step (8-step flow)" }, "step_6_name": { "type": "string", "description": "Custom label for the Terms step (8-step flow)" }, "step_7_name": { "type": "string", "description": "Custom label for the Payment step (8-step flow)" }, "step_8_name": { "type": "string", "description": "Custom label for the Confirmation step (8-step flow)" }, "enable_promo_codes": { "type": "boolean", "description": "Whether buyers can enter promotional codes in the widget" }, "enable_discount_step": { "type": "boolean", "description": "Whether the dedicated discount step is shown in the widget flow" }, "auto_discounts": { "type": "object", "nullable": true, "description": "Automatic discount rules applied based on cart contents or quantity thresholds" }, "contract_template_id": { "type": "string", "nullable": true, "description": "Contract template ID used to generate the terms agreement presented to buyers" }, "enable_negotiation": { "type": "boolean", "description": "Whether buyers can submit counter-offers and negotiate pricing" }, "negotiation_mode": { "type": "string", "enum": [ "price_only", "item_selection", "terms_only", "full" ], "description": "Negotiation scope: price_only allows price counter-offers only; full allows line item and terms changes" }, "auto_accept_threshold": { "type": "number", "nullable": true, "description": "Minimum acceptable counter-offer percentage (0-100). Counter-offers at or above this threshold are auto-accepted." }, "locale": { "type": "string", "nullable": true, "description": "BCP 47 language tag for the widget UI (e.g. en, en-AU, es, de, fr, ja)" }, "locale_overrides": { "type": "object", "nullable": true, "description": "Custom string overrides for widget i18n labels keyed by dot-separated translation paths" }, "show_social_proof": { "type": "boolean", "description": "Whether social proof indicators (recent activity, buyer counts) are shown in the widget" }, "show_smart_defaults": { "type": "boolean", "description": "Whether AI-suggested smart defaults are pre-filled in the widget configuration step" }, "social_proof_threshold": { "type": "integer", "description": "Minimum number of completed deals before social proof indicators are displayed" }, "show_stock_quantity": { "type": "boolean", "description": "Whether remaining stock quantity is displayed alongside products" }, "saved_config_ttl_days": { "type": "integer", "description": "Number of days a buyer's saved widget configuration is retained before expiry" }, "logo_url": { "type": "string", "nullable": true, "description": "Merchant logo URL displayed in the widget header" }, "font_family": { "type": "string", "nullable": true, "description": "CSS font-family value applied to widget text (e.g. 'Inter', 'Georgia')" }, "custom_css": { "type": "string", "nullable": true, "description": "Custom CSS injected into the widget shadow DOM for advanced styling" }, "dark_mode": { "type": "boolean", "description": "Whether the widget renders in dark mode by default" }, "border_radius": { "type": "integer", "nullable": true, "description": "CSS border-radius in pixels applied to widget cards and buttons" }, "button_style": { "type": "string", "enum": [ "filled", "outline", "ghost" ], "description": "Primary button visual style variant", "default": "filled" }, "analytics_mode": { "type": "string", "nullable": true, "description": "Analytics event dispatch mode (e.g. gtm, custom, null to disable)" }, "analytics_callback": { "type": "string", "nullable": true, "description": "Global JavaScript function name invoked with analytics events when analytics_mode is custom" }, "analytics_consent": { "type": "boolean", "description": "Whether analytics event tracking requires explicit buyer consent" }, "network_config": { "type": "object", "nullable": true, "description": "Widget network and retry configuration (timeout_ms, max_retries, retry_delay_ms)" }, "signature_mode": { "type": "string", "enum": [ "checkbox", "drawn", "typed" ], "description": "Method used to capture buyer signature on the terms step", "default": "checkbox" }, "step_order": { "type": "string", "nullable": true, "description": "Comma-separated step names defining custom widget step ordering" }, "skip_steps": { "type": "string", "nullable": true, "description": "Comma-separated step names to omit from the widget flow" }, "step_conditions": { "type": "object", "nullable": true, "description": "Conditional visibility rules for steps keyed by step name" }, "stripe_publishable_key": { "type": "string", "nullable": true, "description": "Stripe publishable key (pk_live_* or pk_test_*) used by the widget to initialise Stripe.js for payment collection" }, "base_url": { "type": "string", "description": "Regional API base URL used by the widget SDK for all API calls (e.g. https://api-au.salesbooth.com)" }, "region": { "type": "string", "description": "Tenant data residency region code (au, eu, us)" } } }, "PaymentCreateIntentRequest": { "type": "object", "title": "create-intent", "deprecated": true, "description": "Deprecated: use POST /payment-intent instead. Retained for backward compatibility only. Request body for the legacy action=create-intent route on POST /payments.", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "The deal to create a PaymentIntent for.", "maxLength": 255 }, "amount": { "type": "number", "description": "Override amount in currency units. Defaults to deal balance due.", "minimum": 0, "maximum": 99999999.99 }, "currency": { "type": "string", "description": "ISO 4217 currency code. Defaults to deal currency.", "maxLength": 3 } }, "additionalProperties": false }, "PaymentConfirmRequest": { "type": "object", "title": "confirm", "description": "Request body for action=confirm. Confirms that a Stripe PaymentIntent has succeeded.", "required": [ "deal_id", "payment_intent_id" ], "properties": { "deal_id": { "type": "string", "description": "The deal the payment belongs to.", "maxLength": 255 }, "payment_intent_id": { "type": "string", "description": "The Stripe PaymentIntent ID to confirm.", "maxLength": 255 } }, "additionalProperties": false }, "PaymentCaptureRequest": { "type": "object", "title": "capture", "description": "Request body for action=capture. Captures a previously-authorized PaymentIntent.", "required": [ "deal_id", "payment_intent_id" ], "properties": { "deal_id": { "type": "string", "description": "The deal the payment belongs to.", "maxLength": 255 }, "payment_intent_id": { "type": "string", "description": "The Stripe PaymentIntent ID to capture.", "maxLength": 255 }, "amount_to_capture": { "type": "number", "description": "Amount to capture in currency units. Defaults to the full authorized amount.", "minimum": 0, "maximum": 99999999.99 } }, "additionalProperties": false }, "PaymentRefundRequest": { "type": "object", "title": "refund", "description": "Request body for action=refund. Processes a partial or full refund for a deal.", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "The deal to refund payment for.", "maxLength": 255 }, "amount": { "type": "number", "description": "Amount to refund in currency units. Defaults to the full payment amount.", "minimum": 0, "maximum": 99999999.99 }, "reason": { "type": "string", "description": "Reason for the refund.", "maxLength": 255 } }, "additionalProperties": false }, "PaymentRecordManualRequest": { "type": "object", "title": "record-manual", "description": "Request body for action=record-manual. Records a manual (non-Stripe) payment against a deal.", "required": [ "deal_id", "amount", "method" ], "properties": { "deal_id": { "type": "string", "description": "The deal to record the payment against.", "maxLength": 255 }, "amount": { "type": "number", "description": "Amount received in currency units.", "minimum": 0.01, "maximum": 99999999.99 }, "method": { "type": "string", "description": "Payment method used.", "enum": [ "cash", "wire", "cheque", "bank_transfer", "other" ] }, "reference": { "type": "string", "description": "External reference or transaction ID.", "maxLength": 255 }, "notes": { "type": "string", "description": "Additional notes about the payment.", "maxLength": 65535 } }, "additionalProperties": false }, "PaymentChargeSavedMethodRequest": { "type": "object", "title": "charge-saved-method", "description": "Request body for action=charge-saved-method. Charges a customer's saved payment method off-session (agent use).", "required": [ "deal_id", "customer_id" ], "properties": { "deal_id": { "type": "string", "description": "The deal to charge payment for.", "maxLength": 255 }, "customer_id": { "type": "string", "description": "The customer whose saved payment method to charge.", "maxLength": 255 }, "payment_method_id": { "type": "string", "description": "Specific Stripe payment method ID to use. Defaults to the customer's default payment method.", "maxLength": 255 } }, "additionalProperties": false }, "PaymentPollIntentRequest": { "type": "object", "title": "poll-intent", "description": "Request body for action=poll-intent. Polls a Stripe PaymentIntent status without requiring a webhook.", "required": [ "payment_intent_id" ], "properties": { "payment_intent_id": { "type": "string", "description": "The Stripe PaymentIntent ID to poll.", "maxLength": 255 } }, "additionalProperties": false }, "PaymentGenerateLinkRequest": { "type": "object", "title": "generate-link", "description": "Request body for action=generate-link. Generates a Stripe Checkout Session URL for customer self-payment.", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "The deal to generate a payment link for.", "maxLength": 255 }, "success_url": { "type": "string", "description": "URL to redirect the customer to after successful payment.", "maxLength": 2048 }, "cancel_url": { "type": "string", "description": "URL to redirect the customer to if they cancel the payment.", "maxLength": 2048 } }, "additionalProperties": false }, "PaymentSaveSettingsRequest": { "type": "object", "title": "save-settings", "description": "Request body for action=save-settings. Saves payment method toggles and invoice settings.", "properties": { "payment_methods": { "type": "object", "description": "Payment method enable/disable toggles keyed by method name." }, "invoice_settings": { "type": "object", "description": "Invoice generation and delivery settings." } }, "additionalProperties": false }, "PaymentConnectStripeRequest": { "type": "object", "title": "connect-stripe", "description": "Request body for action=connect-stripe. Initiates Stripe Connect onboarding. No body fields required.", "additionalProperties": false }, "PaymentDisconnectStripeRequest": { "type": "object", "title": "disconnect-stripe", "description": "Request body for action=disconnect-stripe. Disconnects the Stripe account. No body fields required.", "additionalProperties": false }, "ActivityRuleUpdateRequest": { "type": "object", "description": "Request body for updating a notification rule. All fields are optional; only provided fields are updated.", "properties": { "name": { "type": "string", "description": "Human-readable name for the rule" }, "event_type": { "type": "string", "description": "Event type pattern to match (e.g. 'deal.created', '*' for all events)" }, "conditions": { "type": "object", "description": "Optional filter conditions applied to matching events", "additionalProperties": true }, "channels": { "type": "array", "description": "Notification delivery channels", "items": { "type": "string", "enum": [ "in_app", "email", "webhook" ] } }, "webhook_url": { "type": "string", "format": "uri", "description": "Webhook URL to call when the rule matches (only used when channels includes 'webhook')" }, "enabled": { "type": "boolean", "description": "Whether the rule is active" } }, "additionalProperties": false }, "AnalyticsSettingsUpdateRequest": { "type": "object", "description": "Request body for updating analytics tracking settings. All fields are optional; only provided fields are updated.", "properties": { "enabled": { "type": "boolean", "description": "Enable or disable session recording and analytics tracking" }, "record_mouse": { "type": "boolean", "description": "Record mouse movement events" }, "record_clicks": { "type": "boolean", "description": "Record click events" }, "record_scroll": { "type": "boolean", "description": "Record scroll events" }, "record_input": { "type": "boolean", "description": "Record input field events (use with caution \u2014 may capture sensitive data)" }, "mask_inputs": { "type": "boolean", "description": "Mask input field values in recordings" }, "block_sensitive": { "type": "boolean", "description": "Block recording of elements matching the block_selector" }, "block_selector": { "type": "string", "description": "CSS selector for elements to exclude from recordings (e.g. '.rr-block, [data-rr-block]')" } }, "additionalProperties": false }, "PreferencesUpdateRequest": { "type": "object", "description": "Request body for updating user or tenant preferences. Use the ?scope query parameter to target user preferences (language, theme) or tenant preferences (recommendations_dismissed). Only recognised keys are applied.", "properties": { "language": { "type": "string", "description": "Preferred display language (user scope only, e.g. 'en', 'fr')" }, "theme": { "type": "string", "description": "Preferred UI theme (user scope only, e.g. 'light', 'dark')" }, "recommendations_dismissed": { "description": "Dismissed recommendation identifiers (tenant scope only)", "oneOf": [ { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } }, "additionalProperties": true }, "ProfileUpdateRequest": { "type": "object", "description": "Request body for updating the current user's profile. All fields are optional; only provided fields are updated.", "properties": { "first_name": { "type": "string", "description": "User's first name (cannot be empty if provided)" }, "last_name": { "type": "string", "description": "User's last name (cannot be empty if provided)" }, "phone": { "type": "string", "description": "User's phone number" } }, "additionalProperties": false }, "SiteBlockUpdateRequest": { "type": "object", "description": "Request body for updating a site block. All fields are optional; only provided fields are updated.", "properties": { "name": { "type": "string", "description": "Display name for the block" }, "slug": { "type": "string", "description": "URL-safe identifier for the block (must be unique within the site)" }, "category": { "type": "string", "description": "Category label used for organising blocks" }, "content": { "type": "string", "description": "HTML or structured content for the block" }, "status": { "type": "string", "enum": [ "active", "draft", "disabled" ], "description": "Publication status of the block" }, "description": { "type": "string", "description": "Optional description of the block's purpose" }, "sort_order": { "type": "integer", "description": "Display order relative to other blocks in the same category" } }, "additionalProperties": false }, "TenantListItem": { "type": "object", "description": "A single tenant entry returned in the GET /tenants response.", "properties": { "tenant_id": { "type": "string", "description": "Unique tenant identifier" }, "name": { "type": "string", "description": "Display name of the tenant" }, "slug": { "type": "string", "description": "URL-safe slug for the tenant" }, "logo_url": { "type": [ "string", "null" ], "description": "URL to the tenant's logo image, or null if not set" }, "role": { "type": "string", "description": "The authenticated user's role within this tenant" }, "is_current": { "type": "boolean", "description": "Whether this tenant is the user's currently active tenant" }, "is_sandbox": { "type": "boolean", "description": "Whether this tenant is a sandbox (test) environment" }, "region": { "type": "string", "description": "Data residency region code (e.g. 'au', 'eu', 'us')" }, "regional_endpoint": { "type": "string", "description": "API base URL for the tenant's region" } } }, "TenantsListResponse": { "type": "object", "description": "Success response for GET /tenants.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "tenants": { "type": "array", "description": "List of tenants accessible to the authenticated user", "items": { "$ref": "#/components/schemas/TenantListItem" } }, "current_tenant_id": { "type": "string", "description": "The tenant_id of the user's currently active tenant" }, "user": { "type": "object", "description": "Basic info about the authenticated user", "properties": { "user_id": { "type": "string", "description": "Unique user identifier" }, "name": { "type": "string", "description": "User's display name" }, "email": { "type": "string", "description": "User's email address" } } } } } }, "required": [ "error", "success" ] }, "TenantSettingsUpdateRequest": { "type": "object", "description": "Request body for updating tenant-level settings. All fields are optional; only provided fields are updated.", "properties": { "company_name": { "type": "string", "description": "Legal or trading name of the business" }, "website": { "type": "string", "description": "Business website URL" }, "address": { "type": "string", "description": "Street address (first line)" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State or province" }, "postal_code": { "type": "string", "description": "Postcode or ZIP code" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (e.g. 'US', 'AU')" }, "logo_url": { "type": "string", "description": "Path to uploaded logo file (must be an /uploads/ path or empty string to remove)" }, "industry": { "type": "string", "description": "Industry or sector the business operates in" }, "tax_id": { "type": "string", "description": "Business tax identification number" }, "default_tax_rate": { "type": "string", "description": "Default tax rate applied to new deals (e.g. '0.1' for 10%)" }, "primary_color": { "type": "string", "description": "Brand primary colour as a CSS hex value (e.g. '#2563eb')" }, "custom_domain": { "type": "string", "description": "Custom domain for the tenant's hosted pages" }, "currency": { "type": "string", "description": "Default ISO 4217 currency code (e.g. 'USD', 'AUD')" } }, "additionalProperties": false }, "SubscriptionListItem": { "type": "object", "description": "A subscription item returned by GET /subscriptions. Represents a recurring deal with subscription billing metadata.", "properties": { "deal_id": { "type": "string", "description": "Unique identifier for the deal" }, "customer_id": { "type": "string", "description": "Identifier of the customer associated with this subscription" }, "status": { "type": "string", "enum": [ "pending", "open", "closed", "cancelled", "pending_payment", "disputed", "refunded" ], "description": "Deal status" }, "deal_type": { "type": "string", "const": "recurring", "description": "Always 'recurring' for subscriptions" }, "billing_cycle": { "type": [ "string", "null" ], "enum": [ "monthly", "quarterly", "annual", null ], "description": "Billing cadence for the subscription" }, "subscription_status": { "type": [ "string", "null" ], "enum": [ "active", "paused", "cancelled", "past_due", "suspended", null ], "description": "Current lifecycle status of the subscription" }, "next_billing_date": { "type": [ "string", "null" ], "format": "date", "description": "Date of the next scheduled billing charge" }, "billing_period_start": { "type": [ "string", "null" ], "format": "date", "description": "Start date of the current billing period" }, "billing_period_end": { "type": [ "string", "null" ], "format": "date", "description": "End date of the current billing period" }, "retry_count": { "type": [ "integer", "null" ], "description": "Number of payment retry attempts for the current billing period" }, "renewal_count": { "type": [ "integer", "null" ], "description": "Total number of successful renewals since subscription creation" }, "parent_deal_id": { "type": [ "string", "null" ], "description": "ID of the root/original subscription deal in the renewal chain" }, "total": { "type": [ "number", "null" ], "description": "Total amount charged per billing cycle" }, "currency": { "type": [ "string", "null" ], "maxLength": 3, "description": "ISO 4217 currency code" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the deal was created" }, "customer_name": { "type": [ "string", "null" ], "description": "Display name of the customer" }, "customer_email": { "type": [ "string", "null" ], "format": "email", "description": "Email address of the customer" } }, "required": [ "deal_id", "customer_id", "status", "deal_type" ] }, "SubscriptionMeter": { "type": "object", "description": "A usage meter added to a subscription for metered billing. Returned by POST /subscriptions with action=add-meter.", "properties": { "meter_id": { "type": "string", "description": "Unique meter identifier (e.g. mtr_abc123)" }, "subscription_deal_id": { "type": "string", "description": "The subscription deal this meter is attached to" }, "metric_name": { "type": "string", "description": "Name of the metric being tracked (e.g. api_calls, seats, storage_gb)" }, "billing_model": { "type": "string", "enum": [ "per_unit", "tiered", "volume" ], "description": "Billing model for this meter" }, "unit_price": { "type": "number", "description": "Price per unit (for per_unit model)" }, "included_quantity": { "type": "number", "description": "Free units included in the base subscription before billing begins" }, "tiers": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "up_to": { "type": [ "number", "null" ], "description": "Upper bound for this tier (null = unlimited)" }, "unit_price": { "type": "number", "description": "Price per unit in this tier" } } }, "description": "Pricing tiers (for tiered/volume billing models)" }, "currency": { "type": "string", "maxLength": 3, "description": "ISO 4217 currency code for billing" }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Meter status" } }, "required": [ "meter_id", "subscription_deal_id", "metric_name", "billing_model", "status" ] }, "SubscriptionMeterArchived": { "type": "object", "description": "Confirmation that a usage meter has been archived. Returned by POST /subscriptions with action=remove-meter.", "properties": { "meter_id": { "type": "string", "description": "The meter that was archived" }, "status": { "type": "string", "const": "archived", "description": "Always 'archived'" } }, "required": [ "meter_id", "status" ] }, "SubscriptionUsageRecord": { "type": "object", "description": "A recorded usage event for metered billing. Returned by POST /subscriptions with action=record-usage.", "properties": { "usage_id": { "type": "string", "description": "Unique usage record identifier" }, "meter_id": { "type": "string", "description": "The meter this usage was recorded against" }, "deal_id": { "type": "string", "description": "The subscription deal" }, "metric_name": { "type": "string", "description": "Name of the metric recorded" }, "quantity": { "type": "number", "description": "Usage quantity recorded" }, "idempotency_key": { "type": [ "string", "null" ], "description": "Client-provided deduplication key" }, "metadata": { "type": [ "object", "null" ], "description": "Optional metadata associated with this usage event" }, "recorded_at": { "type": "string", "format": "date-time", "description": "Timestamp when the usage was recorded" } }, "required": [ "usage_id", "meter_id", "deal_id", "metric_name", "quantity", "recorded_at" ] }, "OptionGroup": { "type": "object", "description": "A configuration option group attached to a product, as returned by ProductConfigService::formatOptionGroup(). Each group contains a set of selectable options (returned separately as `options` when the product action=options endpoint embeds them).", "properties": { "group_id": { "type": "string", "description": "Unique option group identifier", "examples": [ "grp_a1b2c3d4e5f6" ] }, "name": { "type": "string", "description": "Display name of the option group" }, "description": { "type": [ "string", "null" ], "description": "Optional description shown to the buyer" }, "selection_type": { "type": "string", "enum": [ "single", "multiple" ], "description": "Whether the buyer can select one or many options" }, "is_required": { "type": "boolean", "description": "Whether the buyer must make a selection before proceeding" }, "min_selections": { "type": "integer", "minimum": 0, "description": "Minimum number of options that must be selected (for multiple selection_type)" }, "max_selections": { "type": [ "integer", "null" ], "minimum": 1, "description": "Maximum number of options that may be selected, or null for unlimited" }, "display_style": { "type": "string", "enum": [ "pills", "cards", "swatches", "checkboxes", "dropdown" ], "description": "Visual presentation style used in the widget" }, "sort_order": { "type": "integer", "description": "Display ordering position (ascending)" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Whether the group is active and shown in the widget" }, "version": { "type": "integer", "minimum": 1, "description": "Optimistic locking version" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO 8601 creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO 8601 last-update timestamp" } }, "required": [ "group_id", "name", "selection_type", "is_required", "min_selections", "max_selections", "display_style", "sort_order", "status", "version", "created_at", "updated_at" ] }, "StaffMember": { "type": "object", "description": "A staff member record", "properties": { "staff_id": { "type": "string", "example": "stf_abc123def456" }, "display_name": { "type": "string" }, "title": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "avatar_url": { "type": "string", "nullable": true }, "max_daily_sessions": { "type": "integer", "description": "Maximum bookings per day", "example": 8 }, "default_session_duration": { "type": "integer", "description": "Default session duration in minutes", "example": 60 }, "buffer_time": { "type": "integer", "description": "Buffer time between sessions in minutes", "example": 15 }, "timezone": { "type": "string", "example": "UTC" }, "created_at": { "type": "string", "format": "date-time" }, "bio": { "type": "string", "nullable": true, "description": "Staff bio \u2014 only present when fetching a single staff member" }, "user_id": { "type": "string", "nullable": true, "description": "Linked user account ID \u2014 only present when fetching a single staff member" }, "metadata": { "type": "object", "nullable": true, "description": "Arbitrary metadata \u2014 only present when fetching a single staff member" }, "updated_at": { "type": "string", "format": "date-time", "description": "Only present when fetching a single staff member" }, "schedule": { "type": "array", "description": "Weekly schedule entries \u2014 only present when fetching a single staff member", "items": { "type": "object" } }, "overrides": { "type": "array", "description": "Date-specific schedule overrides \u2014 only present when fetching a single staff member", "items": { "type": "object" } }, "products": { "type": "array", "description": "Product assignments \u2014 only present when fetching a single staff member", "items": { "type": "object" } } }, "required": [ "staff_id", "display_name", "status", "max_daily_sessions", "default_session_duration", "buffer_time", "timezone", "created_at" ] }, "StaffGetResponse": { "type": "object", "description": "Response from GET /staff. Returns a paginated list when no `id` is provided, or a single staff member with full details (including schedule, overrides and product assignments) when `id` is specified.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "staff": { "description": "Single StaffMember object (detail mode) or array of StaffMember objects (list mode)" }, "pagination": { "type": "object", "description": "Pagination metadata \u2014 only present in list mode", "properties": { "total": { "type": "integer", "description": "Total number of staff members matching the filter" }, "limit": { "type": "integer", "description": "Page size" }, "offset": { "type": "integer", "description": "Number of records skipped" }, "count": { "type": "integer", "description": "Number of records returned in this page" } }, "required": [ "total", "limit", "offset", "count" ] } } } }, "required": [ "error", "success" ] }, "StaffWriteResponse": { "type": "object", "description": "Response from POST or PATCH /staff \u2014 returns the created or updated staff member", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "staff": { "$ref": "#/components/schemas/StaffMember" } }, "required": [ "staff" ] } }, "required": [ "error", "success" ] }, "BudgetResponse": { "type": "object", "description": "Response from GET /budget \u2014 current budget settings and spend tracking", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "budget": { "type": "object", "description": "Budget configuration and current spend", "properties": { "monthly_limit": { "type": "number", "nullable": true, "description": "Monthly spending limit in dollars; null if no limit is set" }, "monthly_limit_cents": { "type": "integer", "description": "Monthly spending limit in cents; 0 if no limit is set" }, "alert_at_percent": { "type": "array", "items": { "type": "integer" }, "description": "Percentage thresholds at which budget alert emails are sent (e.g. [80, 100])" }, "current_spend": { "type": "number", "description": "Current month's total spend in dollars" }, "current_spend_cents": { "type": "integer", "description": "Current month's total spend in cents" }, "percent_used": { "type": "number", "description": "Percentage of the monthly limit consumed; 0 when no limit is set" } }, "required": [ "monthly_limit_cents", "alert_at_percent", "current_spend", "current_spend_cents", "percent_used" ] } }, "required": [ "budget" ] } }, "required": [ "error", "success" ] }, "CacheStatsResponse": { "type": "object", "description": "Response from GET /cache \u2014 cache statistics across all tiers. When no backend is available, only `available` and `message` are returned.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Whether any cache backend (APCu or Redis) is available" }, "hit_rate": { "type": "number", "description": "Cache hit rate as a percentage (0\u2013100); only present when cache is available" }, "counters": { "type": "object", "description": "Cumulative operation counters; only present when cache is available", "properties": { "hits": { "type": "integer" }, "misses": { "type": "integer" }, "writes": { "type": "integer" }, "deletes": { "type": "integer" }, "prefix_invalidations": { "type": "integer" } } }, "backends": { "type": "object", "description": "Which cache tiers are active; only present when cache is available", "properties": { "l1_apcu": { "type": "boolean", "description": "Whether APCu (L1 in-process cache) is enabled" }, "l2_redis": { "type": "boolean", "description": "Whether Redis (L2 shared cache) is enabled" } } }, "apcu": { "type": "object", "description": "APCu in-process cache statistics; only present when APCu is enabled", "properties": { "num_slots": { "type": "integer" }, "num_entries": { "type": "integer" }, "memory_size": { "type": "integer", "description": "Used memory in bytes" }, "memory_size_human": { "type": "string", "example": "12.5 MB" }, "hits": { "type": "integer" }, "misses": { "type": "integer" }, "start_time": { "type": "string", "format": "date-time" }, "uptime_seconds": { "type": "integer" } } }, "memory": { "type": "object", "description": "APCu shared memory segment statistics; only present when APCu is enabled", "properties": { "total": { "type": "integer", "description": "Total shared memory segment size in bytes" }, "available": { "type": "integer", "description": "Available shared memory in bytes" }, "utilization": { "type": "number", "description": "Memory utilization as a percentage" } } }, "redis": { "type": "object", "description": "Redis cache statistics; only present when Redis is enabled", "properties": { "used_memory_human": { "type": "string", "example": "1.23M" }, "connected_clients": { "type": [ "integer", "string" ], "description": "Number of connected Redis clients; 'unknown' if unavailable" } } }, "message": { "type": "string", "description": "Human-readable status message; only present when cache is unavailable" } }, "required": [ "available" ] } }, "required": [ "error", "success" ] }, "ChannelsResponse": { "type": "object", "description": "Response from GET /channels \u2014 tenant communication channel settings", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "channels": { "type": "object", "description": "Configured communication channels for this tenant", "properties": { "voice_number": { "type": "string", "nullable": true, "description": "E.164 phone number for outbound voice calls (e.g. +61412345678)" }, "sms_number": { "type": "string", "nullable": true, "description": "E.164 phone number for outbound SMS messages" }, "from_email": { "type": "string", "nullable": true, "description": "Sender email address for outbound emails" }, "from_name": { "type": "string", "nullable": true, "description": "Sender display name for outbound emails" }, "reply_to_email": { "type": "string", "nullable": true, "description": "Reply-to / inbound email address" } } } }, "required": [ "channels" ] } }, "required": [ "error", "success" ] }, "QueueStatsResponse": { "type": "object", "description": "Response from GET /queue (no action or id param) \u2014 job queue statistics", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "description": "Response shape varies by query params. Default (no action/id): `queue` stats object. With `action=status` or `id`: `job` object.", "properties": { "queue": { "type": "object", "description": "Queue statistics \u2014 present when no action or id is specified", "properties": { "status_counts": { "type": "object", "description": "Count of jobs in each status", "properties": { "pending": { "type": "integer" }, "processing": { "type": "integer" }, "completed": { "type": "integer" }, "failed": { "type": "integer" }, "dead": { "type": "integer" } }, "required": [ "pending", "processing", "completed", "failed", "dead" ] }, "by_type": { "type": "object", "description": "Per-job-type status breakdown (job_type \u2192 status \u2192 count)", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer" } } }, "by_topic": { "type": "object", "description": "Per-topic status breakdown (topic \u2192 status \u2192 count)", "additionalProperties": { "type": "object", "additionalProperties": { "type": "integer" } } }, "topic_throughput_last_hour": { "type": "object", "description": "Number of completed jobs per topic in the last hour", "additionalProperties": { "type": "integer" } }, "avg_processing_seconds": { "type": "number", "nullable": true, "description": "Average job processing time in seconds over the last hour; null if no jobs completed" }, "throughput_last_hour": { "type": "integer", "description": "Total jobs completed across all topics in the last hour" }, "oldest_pending_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Scheduled time of the oldest pending job; null if queue is empty" }, "redis_queue_depths": { "type": "object", "description": "Current queue depth for Redis-backed topics", "additionalProperties": { "type": "integer" } } } }, "job": { "type": "object", "description": "Single job details \u2014 present when action=status or id is specified" } } } }, "required": [ "error", "success" ] }, "AvailabilityResponse": { "type": "object", "description": "Response from GET /availability. When `date` is provided returns `slots[]`; when `month` is provided returns `dates[]`.", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true, "description": "Always true for success responses" }, "data": { "type": "object", "properties": { "slots": { "type": "array", "description": "Available time slots \u2014 present when `date` query param is used", "items": { "type": "object", "properties": { "start_time": { "type": "string", "example": "09:00:00", "description": "Slot start time (HH:MM:SS)" }, "end_time": { "type": "string", "example": "10:00:00", "description": "Slot end time (HH:MM:SS)" }, "staff_id": { "type": "string", "example": "stf_abc123def456" }, "staff_name": { "type": "string" }, "duration": { "type": "integer", "description": "Slot duration in minutes" } }, "required": [ "start_time", "end_time", "staff_id", "staff_name", "duration" ] } }, "dates": { "type": "array", "description": "Dates with at least one available slot \u2014 present when `month` query param is used", "items": { "type": "string", "format": "date", "example": "2026-04-15" } }, "date": { "type": "string", "format": "date", "description": "The requested date \u2014 present when `date` query param is used" }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$", "description": "The requested month (YYYY-MM) \u2014 present when `month` query param is used" }, "product_id": { "type": "string", "description": "The product ID that was queried" }, "message": { "type": "string", "description": "Human-readable message (e.g. 'No staff assigned', 'Date is too soon')" } } } }, "required": [ "error", "success" ] }, "WebhookEventType": { "type": "string", "description": "A supported webhook event type. Subscribe to these events when creating or updating a webhook endpoint.", "enum": [ "deal.created", "deal.status_changed", "deal.closed", "deal.fulfilled", "deal.expired", "deal.unsigned", "deal.updated", "deal.item_added", "deal.item_removed", "deal.item_updated", "deal.discount_applied", "deal.partially_accepted", "deal.signature_added", "deal.created_configured", "deal.payment_received", "deal.payment_failed", "deal.payment_refunded", "deal.payment_overdue", "deal.negotiation_proposed", "deal.negotiation_counter_proposed", "deal.negotiation_accepted", "deal.negotiation_rejected", "negotiation.expired", "negotiation.proposed", "negotiation.countered", "negotiation.accepted", "negotiation.rejected", "negotiation.suggestion_generated", "contract.signed", "contract.activated", "contract.terminated", "contract.tamper_detected", "contract.auto_renewed", "contract.renewal_failed", "contract.renewal_opted_out", "contract.renewal_upcoming", "customer.created", "customer.updated", "customer.deleted", "payment.received", "escrow.created", "escrow.released", "escrow.refunded", "escrow.condition_fulfilled", "escrow.reauthorization_pending", "escrow.reauthorized", "escrow.reauthorization_failed", "credential.issued", "subscription.created", "subscription.renewed", "subscription.renewal_upcoming", "subscription.paused", "subscription.resumed", "subscription.cancelled", "subscription.upgraded", "subscription.downgraded", "subscription.changed", "subscription.past_due", "subscription.suspended", "subscription.cycle_changed", "subscription.payment_failed", "subscription.payment_retried", "subscription.proration_credit", "subscription.meter_added", "subscription.meter_removed", "subscription.usage_recorded", "subscription.usage_charges_applied", "product_family.created", "product_family.updated", "product_family.deleted", "option_group.created", "option_group.updated", "option_group.deleted", "option.created", "option.updated", "option.deleted", "compatibility_rule.created", "compatibility_rule.updated", "compatibility_rule.deleted", "bundle_rule.created", "bundle_rule.updated", "bundle_rule.deleted", "billing.low_balance", "billing.credit_added", "billing.credit_deducted", "billing.auto_topup", "billing.widget_degraded", "tenant.trust_level_changed", "tenant.trust_promoted", "tenant.trust_level_decay_warning", "service.circuit_opened", "service.circuit_closed", "circuit-breaker.backoff-increased", "saved_config.created", "saved_config.viewed", "saved_config.converted", "saved_config.expiring", "saved_config.expired", "security.csp_spike", "agent.workflow.planned", "agent.workflow.completed", "agent.workflow.failed", "agent.workflow.step_completed", "agent.workflow.step_retried", "agent.workflow.dead_lettered", "agent.workflow.cancelled", "agent.workflow.degraded", "agent.workflow.approved", "workflow.sell.proposal_received", "workflow.fulfill.delivered", "workflow.step_approved", "agent.approval_required", "agent.approval_resent", "agent.approval_escalated", "agent.trust.level_changed", "agent.trust.abuse_detected", "agent.trust.decay_warning", "agent.trust.credential_issued", "agent.trust.credential_presented", "agent.trust.credential_revoked", "agent.trust_cap_exceeded", "agent.anomaly_detected", "agent.spending_ceiling", "system.job_dead_letter", "job.completed", "job.failed", "queue.depth_alert", "trust.demoted", "trust.fraud_signal", "booking.created", "booking.cancelled", "booking.completed", "booking.no_show", "booking.held", "booking.hold_expired", "booking.rescheduled", "consent.expiring_soon", "consent.expired", "api_key.rotated", "deal.settlement_initiated", "deal.settlement_completed", "deal.settlement_failed", "deal.settlement_all_completed", "deal.participant_invited", "deal.participant_accepted", "deal.participant_withdrawn", "deal.participant_completed", "deal.settlement_created", "deal.signature_timeout", "federation.settlement_completed", "federation.settlement_failed", "federation.escrow_disputed", "federation.escrow_expired", "portal.payment_completed", "portal.contract_signed", "portal.change_requested", "encryption.rekey_completed", "delegation.granted", "delegation.revoked", "delegation.proposed", "delegation.accepted", "delegation.rejected", "delegation.countered", "delegation.expired", "delegation.budget_warning" ] }, "SiteBlockCreateRequest": { "type": "object", "required": [ "site_id", "name" ], "additionalProperties": false, "description": "Request body for creating a new site block.", "properties": { "site_id": { "type": "string", "maxLength": 50, "description": "ID of the site this block belongs to" }, "name": { "type": "string", "maxLength": 255, "description": "Display name for the block" }, "slug": { "type": "string", "maxLength": 255, "description": "URL-safe identifier for the block (auto-generated from name if omitted)" }, "category": { "type": "string", "maxLength": 100, "description": "Category label used for organising blocks" }, "content": { "type": "string", "description": "HTML or structured content for the block" }, "status": { "type": "string", "enum": [ "active", "draft", "disabled" ], "default": "draft", "description": "Publication status of the block" }, "description": { "type": "string", "maxLength": 500, "description": "Optional description of the block's purpose" }, "sort_order": { "type": "integer", "minimum": 0, "description": "Display order relative to other blocks in the same category" } } }, "DealParticipant": { "type": "object", "description": "A participant in a multi-agent deal", "properties": { "id": { "type": "string", "description": "Participant ID (part_...)" }, "deal_id": { "type": "string" }, "agent_api_key_id": { "type": "integer", "description": "Internal API key ID of the agent" }, "agent_name": { "type": "string", "nullable": true, "description": "Display name of the agent API key" }, "agent_key_id": { "type": "string", "nullable": true, "description": "Public key_id identifier of the agent API key" }, "delegation_id": { "type": "string", "nullable": true, "description": "Delegation ID if participant was invited via a delegation" }, "role": { "type": "string", "enum": [ "primary", "subcontractor", "reviewer", "observer", "required_signer" ], "description": "primary=deal owner; subcontractor=blocks close until complete; reviewer=view+comment; observer=read-only; required_signer=must sign before close" }, "scope_description": { "type": "string", "nullable": true, "description": "Description of this participant's assigned scope or responsibilities" }, "line_item_ids": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "Line item IDs assigned to this participant" }, "revenue_share_percent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "description": "Percentage of deal revenue allocated to this participant" }, "revenue_share_fixed": { "type": "number", "nullable": true, "minimum": 0, "description": "Fixed amount of deal revenue allocated to this participant" }, "status": { "type": "string", "enum": [ "invited", "accepted", "active", "completed", "withdrawn" ], "description": "Current lifecycle status of the participant" }, "invited_at": { "type": "string", "format": "date-time", "description": "When the participant was invited" }, "accepted_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the participant accepted the invitation" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the participant marked their scope as complete" } }, "required": [ "id", "deal_id", "agent_api_key_id", "role", "status", "invited_at" ] }, "DealParticipantResponse": { "type": "object", "description": "Response envelope for a single deal participant (invite, accept, complete, update, or remove actions)", "properties": { "error": { "type": "boolean", "const": false }, "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/DealParticipant" } }, "required": [ "error", "success", "data" ] }, "BillingTopupRequest": { "type": "object", "title": "topup", "description": "Request body for action=topup. Creates a Stripe Checkout session to add credits to the tenant account.", "required": [ "amount", "success_url", "cancel_url" ], "properties": { "amount": { "type": "number", "description": "Top-up amount in USD. Must be between $5.00 and $10,000.00.", "minimum": 5.0, "maximum": 10000.0, "example": 50.0 }, "success_url": { "type": "string", "description": "URL to redirect the user to after a successful payment.", "maxLength": 2048, "example": "https://app.example.com/billing?topup=success" }, "cancel_url": { "type": "string", "description": "URL to redirect the user to if they cancel the payment.", "maxLength": 2048, "example": "https://app.example.com/billing?topup=cancelled" } }, "additionalProperties": false }, "BillingAutoTopupRequest": { "type": "object", "title": "auto-topup", "description": "Request body for action=auto-topup. Enables or disables automatic credit top-up when balance falls low. When enabling, `amount` and `payment_method_id` are also required.", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "Whether to enable (true) or disable (false) automatic top-up." }, "amount": { "type": "number", "description": "Auto top-up amount in USD. Required when `enabled` is true. Must be at least $5.00.", "minimum": 5.0, "example": 20.0 }, "payment_method_id": { "type": "string", "description": "Stripe payment method ID to charge for auto top-ups. Required when `enabled` is true. Obtain a payment method by calling action=setup-intent first.", "maxLength": 255, "example": "pm_1OqLh2LkdIwHu7ixEBHGHpNK" } }, "additionalProperties": false }, "BillingSetupIntentRequest": { "type": "object", "title": "setup-intent", "description": "Request body for action=setup-intent. Creates a Stripe Setup Intent to save a payment method for future auto top-ups. No body fields are required.", "properties": {}, "additionalProperties": false }, "BillingAlertSettingsRequest": { "type": "object", "title": "alert-settings", "description": "Request body for action=alert-settings. Updates low-balance alert thresholds and notification channel preferences. All fields are optional; omitted fields retain their current values.", "properties": { "threshold": { "type": "number", "description": "Credit balance threshold (in USD) below which alerts are triggered. Must be non-negative.", "minimum": 0, "example": 10.0 }, "email_enabled": { "type": "boolean", "description": "Whether to send low-balance alert emails." }, "webhook_enabled": { "type": "boolean", "description": "Whether to fire a webhook event on low-balance alerts." } }, "additionalProperties": false }, "SubscriptionCreateRequest": { "type": "object", "title": "create", "description": "Request body for action=create. Activates recurring billing on a closed deal.", "required": [ "deal_id", "billing_cycle" ], "properties": { "deal_id": { "type": "string", "description": "The closed deal to activate recurring billing for.", "maxLength": 255 }, "billing_cycle": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ], "description": "Billing cadence for the subscription." } }, "additionalProperties": false }, "SubscriptionRenewRequest": { "type": "object", "title": "renew", "description": "Request body for action=renew. Creates a renewal deal for the next billing period.", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "The subscription deal to renew.", "maxLength": 255 } }, "additionalProperties": false }, "SubscriptionPauseRequest": { "type": "object", "title": "pause", "description": "Request body for action=pause. Pauses a subscription \u2014 no renewal deals will be generated until resumed.", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "The subscription deal to pause.", "maxLength": 255 } }, "additionalProperties": false }, "SubscriptionResumeRequest": { "type": "object", "title": "resume", "description": "Request body for action=resume. Resumes a paused subscription.", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "The subscription deal to resume.", "maxLength": 255 } }, "additionalProperties": false }, "SubscriptionCancelRequest": { "type": "object", "title": "cancel", "description": "Request body for action=cancel. Cancels a subscription immediately or at end of the current billing period.", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "The subscription deal to cancel.", "maxLength": 255 }, "end_of_period": { "type": "boolean", "description": "When true, the subscription remains active until the end of the current billing period. When false (default), cancellation is immediate.", "default": false }, "reason": { "type": "string", "description": "Optional cancellation reason.", "maxLength": 1000 }, "prorate": { "type": "boolean", "default": true, "description": "When true and cancellation is immediate, calculates and applies a prorated credit for unused billing days. Refunded via Stripe if a captured payment exists, otherwise issued as a credit note. Has no effect when end_of_period is true." } }, "additionalProperties": false }, "SubscriptionChangeRequest": { "type": "object", "title": "change", "description": "Request body for action=change. Upgrades or downgrades a subscription with optional proration.", "required": [ "deal_id", "line_items" ], "properties": { "deal_id": { "type": "string", "description": "The subscription deal to change.", "maxLength": 255 }, "line_items": { "type": "array", "description": "New line items for the subscription. Must contain at least one item.", "minItems": 1, "items": { "type": "object" } } }, "additionalProperties": false }, "SubscriptionChangeCycleRequest": { "type": "object", "title": "change-cycle", "description": "Request body for action=change-cycle. Switches the billing cycle (e.g. monthly to annual) with proration.", "required": [ "deal_id", "billing_cycle" ], "properties": { "deal_id": { "type": "string", "description": "The subscription deal whose billing cycle to change.", "maxLength": 255 }, "billing_cycle": { "type": "string", "enum": [ "monthly", "quarterly", "annual" ], "description": "The new billing cycle." } }, "additionalProperties": false }, "SubscriptionRetryPaymentRequest": { "type": "object", "title": "retry-payment", "description": "Request body for action=retry-payment. Retries payment for a past-due subscription.", "required": [ "deal_id" ], "properties": { "deal_id": { "type": "string", "description": "The past-due subscription deal.", "maxLength": 255 }, "grace_days": { "type": "integer", "description": "Grace period in days before the subscription is cancelled if payment still fails. 0 = reactivate immediately on success.", "minimum": 0 } }, "additionalProperties": false }, "SubscriptionAddMeterRequest": { "type": "object", "title": "add-meter", "description": "Request body for action=add-meter. Adds a usage meter to a subscription for metered billing.", "required": [ "deal_id", "metric_name" ], "properties": { "deal_id": { "type": "string", "description": "The subscription deal to add the meter to.", "maxLength": 255 }, "metric_name": { "type": "string", "description": "Name of the usage metric to track (e.g. 'api_calls', 'seats', 'storage_gb').", "maxLength": 255 }, "billing_model": { "type": "string", "enum": [ "per_unit", "tiered", "volume" ], "description": "Billing model for this meter. Defaults to per_unit.", "default": "per_unit" }, "unit_price": { "type": "number", "description": "Price per unit for per_unit billing model.", "minimum": 0 }, "included_quantity": { "type": "number", "description": "Number of free units included in the base subscription before metered charges apply.", "minimum": 0 }, "tiers": { "type": "array", "description": "Tier definitions for tiered or volume billing models.", "items": { "type": "object", "properties": { "up_to": { "type": [ "number", "null" ], "description": "Upper bound for this tier. null means unlimited (last tier only)." }, "unit_price": { "type": "number", "description": "Price per unit in this tier.", "minimum": 0 } } } }, "currency": { "type": "string", "description": "ISO 4217 currency code for this meter's charges. Defaults to the deal currency.", "maxLength": 3 } }, "additionalProperties": false }, "SubscriptionRemoveMeterRequest": { "type": "object", "title": "remove-meter", "description": "Request body for action=remove-meter. Archives a usage meter. Note: deal_id is not required; identify the meter by meter_id.", "required": [ "meter_id" ], "properties": { "meter_id": { "type": "string", "description": "The ID of the meter to archive.", "maxLength": 255 } }, "additionalProperties": false }, "SubscriptionRecordUsageRequest": { "type": "object", "title": "record-usage", "description": "Request body for action=record-usage. Records a metered usage event (idempotent). Send either top-level metric_name+quantity for a single record, or a records array for batch recording.", "required": [ "deal_id", "metric_name", "quantity" ], "properties": { "deal_id": { "type": "string", "description": "The subscription deal to record usage for.", "maxLength": 255 }, "metric_name": { "type": "string", "description": "Name of the metric to record usage for. Required when not using the records array.", "maxLength": 255 }, "quantity": { "type": "number", "description": "Usage quantity to record. Must be a positive number. Required when not using the records array.", "exclusiveMinimum": 0 }, "idempotency_key": { "type": "string", "description": "Client-provided key to prevent duplicate usage recording.", "maxLength": 255 }, "metadata": { "type": "object", "description": "Arbitrary key-value pairs to store with this usage record." }, "records": { "type": "array", "description": "Batch usage records. When provided, top-level metric_name and quantity are ignored.", "minItems": 1, "items": { "type": "object", "required": [ "metric_name", "quantity" ], "properties": { "metric_name": { "type": "string", "maxLength": 255 }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "idempotency_key": { "type": "string", "maxLength": 255 }, "metadata": { "type": "object" } } } } }, "additionalProperties": false } }, "responses": { "BadRequest": { "description": "Bad request \u2014 invalid input or validation failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "validation_error": { "summary": "Field-level validation errors", "value": { "error": true, "code": "validation_error.invalid_fields", "category": "validation_error", "message": "Validation failed", "recovery": { "action": "fix_request", "retryable": false, "hint": "Check the details.fields object for specific field errors." }, "details": { "fields": { "email": { "code": "invalid", "message": "Valid email is required" }, "customer_id": { "code": "required", "message": "Customer ID is required" } } } } }, "bad_request": { "summary": "General bad request", "value": { "error": true, "code": "validation_error.bad_request", "category": "validation_error", "message": "Invalid JSON in request body", "recovery": { "action": "fix_request", "retryable": false } } } } } } }, "Unauthorized": { "description": "Authentication required \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "code": "authentication_error.invalid_credentials", "category": "authentication_error", "message": "Unauthorized", "recovery": { "action": "authenticate", "retryable": false, "hint": "Provide valid authentication credentials." } } } } }, "Forbidden": { "description": "Insufficient permissions \u2014 API key lacks required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "code": "authorization_error.insufficient_scope", "category": "authorization_error", "message": "This action requires the deals:write scope", "recovery": { "action": "check_permissions", "retryable": false, "hint": "Verify your API key has the required scopes." } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "code": "not_found", "category": "not_found", "message": "Deal deal_abc123 not found", "recovery": { "action": "check_resource_id", "retryable": false, "hint": "Verify the resource ID exists and you have access to it." } } } } }, "RateLimited": { "description": "Rate limit exceeded", "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the rate limit resets", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "code": "rate_limited", "category": "rate_limited", "message": "Rate limit exceeded", "recovery": { "action": "retry", "retryable": true, "retry_after_seconds": 60, "max_retries": 3 } } } } }, "ServerError": { "description": "Internal server error", "headers": { "Retry-After": { "description": "Seconds to wait before retrying (present on transient errors)", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal_error": { "summary": "Non-retryable internal error", "value": { "error": true, "code": "internal_error", "category": "internal_error", "message": "An internal error occurred.", "recovery": { "action": "contact_support", "retryable": false, "hint": "If this persists, contact support with the error reference." }, "ref": "err_a1b2c3d4e5f6" } }, "transient_error": { "summary": "Retryable transient error", "value": { "error": true, "code": "transient_error", "category": "transient_error", "message": "Service temporarily unavailable", "recovery": { "action": "retry", "retryable": true, "retry_after_seconds": 5, "max_retries": 3 } } } } } } }, "Conflict": { "description": "Conflict \u2014 the resource is in a state that prevents this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "deal_already_closed": { "summary": "Deal is closed and immutable", "value": { "error": true, "code": "conflict.deal_already_closed", "category": "conflict", "message": "Deal deal_abc123 is already closed and cannot be modified", "recovery": { "action": "none", "retryable": false, "hint": "Closed deals are immutable. Create a new deal if needed." } } }, "invalid_state": { "summary": "Resource is in wrong state for operation", "value": { "error": true, "code": "conflict.invalid_state", "category": "conflict", "message": "Deal must be in pending_signature status to sign (current: draft)", "recovery": { "action": "check_status", "retryable": false, "hint": "Transition the deal to pending_signature before signing." } } } } } } }, "PreconditionFailed": { "description": "Precondition Failed \u2014 the resource has been modified since you last read it. The response includes the current resource state and an updated ETag so you can merge changes and retry.", "headers": { "ETag": { "description": "Current resource version as a weak ETag", "schema": { "type": "string", "example": "W/\"4\"" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorResponse" }, { "type": "object", "properties": { "data": { "description": "Current state of the resource for client-side merge" } } } ] }, "example": { "error": true, "code": "conflict.stale_version", "category": "conflict", "message": "Resource has been modified by another request. Refresh and retry.", "recovery": { "action": "refetch_and_retry", "retryable": true, "hint": "Read the current resource version from the response data, merge your changes, and retry with the new ETag." }, "data": { "deal_id": "deal_abc123", "version": 4, "status": "in_progress" } } } } }, "PreconditionRequired": { "description": "Precondition Required \u2014 the If-Match header is missing. PATCH and DELETE requests require an If-Match header containing the resource's current ETag for optimistic locking.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "code": "validation_error.precondition_required", "category": "validation_error", "message": "If-Match header is required", "recovery": { "action": "fix_request", "retryable": false, "hint": "Add an If-Match header with the resource ETag from a prior GET request." } } } } }, "IdempotencyConflict": { "description": "Conflict \u2014 the same Idempotency-Key was used with a different request body. Generate a new key for different requests.", "headers": { "Idempotency-Key": { "description": "Echo of the provided idempotency key", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": true, "code": "conflict.idempotency_key_reused", "category": "conflict", "message": "This idempotency key has already been used with a different request body", "recovery": { "action": "fix_request", "retryable": false, "hint": "Generate a new idempotency key for this request." } } } } } } } }