{ "openapi": "3.1.0", "info": { "title": "Drip API", "description": "\n# Drip API\n\n**Usage-based billing + execution ledger.**\n\n---\n\n## 60-Second Quickstart (Core SDK)\n\n### 1. Install\n\n```bash\nnpm install @drip-sdk/node\n```\n\n### 2. Set your API key\n\n```bash\n# Secret key - full API access (server-side only, never expose publicly)\nexport DRIP_API_KEY=sk_test_...\n\n# Use a secret key for the customer, billing, runs, pricing-plan, and webhook\n# flows documented in this reference.\n```\n\nOr use a \".env\" file (recommended):\n\n```bash\nnpm install dotenv\n# .env\nDRIP_API_KEY=sk_test_...\n```\n\nLoad your \".env\" at the top of your entry file:\n\n```typescript\nimport 'dotenv/config';\n```\n\n### 3. Create a customer and track usage\n\n```typescript\nimport 'dotenv/config';\nimport { drip } from '@drip-sdk/node';\n\n// Create a customer first\nconst customer = await drip.createCustomer({ externalCustomerId: 'user_123' });\n\n// Internal tracking only (no billing)\nawait drip.trackUsage({ customerId: customer.id, meter: 'api_calls', quantity: 1 });\n```\n\nThe `drip` singleton reads `DRIP_API_KEY` from your environment automatically.\n\n### Alternative: Explicit Configuration\n\n```typescript\nimport 'dotenv/config';\nimport { Drip } from '@drip-sdk/node';\n\n// Auto-reads DRIP_API_KEY from environment\nconst client = new Drip();\n\n// Or pass config explicitly with an Admin/Operator secret key\nconst clientWithSecret = new Drip({ apiKey: 'sk_test_...' });\n```\n\n### Full Example (Node.js)\n\n```typescript\nimport 'dotenv/config';\nimport { drip } from '@drip-sdk/node';\n\nasync function main() {\n // Verify connectivity\n await drip.ping();\n\n // Create a customer (at least one of externalCustomerId or onchainAddress required)\n const customer = await drip.createCustomer({ externalCustomerId: 'user_123' });\n\n // Internal tracking (no billing)\n await drip.trackUsage({\n customerId: customer.id,\n meter: 'llm_tokens',\n quantity: 842,\n metadata: { model: 'gpt-4o-mini' },\n });\n\n // Billable usage\n await drip.charge({\n customerId: customer.id,\n meter: 'api_calls',\n quantity: 1,\n });\n\n // Record an execution lifecycle\n await drip.recordRun({\n customerId: customer.id,\n workflow: 'research-agent',\n events: [\n { eventType: 'llm.call', quantity: 1700, units: 'tokens' },\n { eventType: 'tool.call', quantity: 1 },\n ],\n status: 'COMPLETED',\n });\n\n console.log(`Customer ${customer.id}: usage + run recorded`);\n}\n\nmain();\n```\n\n```python\nfrom drip import drip\n\n# Create a customer first\ncustomer = drip.create_customer(external_customer_id=\"user_123\")\n\n# Internal tracking only (no billing)\ndrip.track_usage(customer_id=customer.id, meter=\"api_calls\", quantity=1)\n```\n\nThe `drip` singleton reads `DRIP_API_KEY` from your environment automatically.\n\n### Alternative: Explicit Configuration (Python)\n\n```python\nfrom drip import Drip\n\n# Auto-reads DRIP_API_KEY from environment\nclient = Drip()\n\n# Or pass config explicitly with an Admin/Operator secret key\nclient_with_secret = Drip(api_key=\"sk_test_...\")\n```\n\n### Full Example (Python)\n\n```python\nfrom drip import drip\n\n# Verify connectivity\ndrip.ping()\n\n# Create a customer (at least one of external_customer_id or onchain_address required)\ncustomer = drip.create_customer(external_customer_id=\"user_123\")\n\n# Internal tracking (no billing)\ndrip.track_usage(\n customer_id=customer.id,\n meter=\"llm_tokens\",\n quantity=842,\n metadata={\"model\": \"gpt-4o-mini\"}\n)\n\n# Billable usage\ndrip.charge(\n customer_id=customer.id,\n meter=\"api_calls\",\n quantity=1\n)\n\n# Record execution lifecycle\ndrip.record_run(\n customer_id=customer.id,\n workflow=\"research-agent\",\n events=[\n {\"event_type\": \"llm.call\", \"quantity\": 1700, \"units\": \"tokens\"},\n {\"event_type\": \"tool.call\", \"quantity\": 1},\n ],\n status=\"COMPLETED\"\n)\n\nprint(f\"Customer {customer.id}: usage + run recorded\")\n```\n\n**Expected result:**\n- No errors\n- Events appear in your Drip dashboard within seconds\n\n**Install:** `npm install @drip-sdk/node` or `pip install drip-sdk`\n\n**Set API key:** `export DRIP_API_KEY=sk_test_...` or use a \".env\" file with `DRIP_API_KEY=sk_test_...` and load it with `import 'dotenv/config'` (for Node.js)\n\n---\n\n## REST API Quick Start\n\n### Step 1: Create a customer\n\n```bash\ncurl -X POST https://api.drippay.dev/v1/customers \\\n -H \"Authorization: Bearer sk_test_YOUR_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"externalCustomerId\": \"user_123\"}'\n```\n\n**You'll get back:**\n```json\n{\n \"id\": \"cmlxxxxxx...\",\n \"externalCustomerId\": \"user_123\",\n \"status\": \"ACTIVE\"\n}\n```\n\n### Step 2: Create pricing\n\nUse the same meter string in your pricing plan and your usage calls:\n\n```bash\ncurl -X POST https://api.drippay.dev/v1/pricing-plans \\\n -H \"Authorization: Bearer sk_test_YOUR_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"API Calls\",\n \"unitType\": \"api_calls\",\n \"unitPriceUsd\": 0.001\n }'\n```\n\n### Step 3: Charge usage\n\n```bash\ncurl -X POST https://api.drippay.dev/v1/usage \\\n -H \"Authorization: Bearer sk_test_YOUR_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"customerId\": \"CUSTOMER_ID_FROM_STEP_1\",\n \"usageType\": \"api_calls\",\n \"quantity\": 100,\n \"idempotencyKey\": \"charge_001\"\n }'\n```\n\n---\n\n## SDK Methods\n\n### Node.js (`@drip-sdk/node`)\n\n| Method | Description |\n|--------|-------------|\n| `createCustomer()` | Create a customer |\n| `getCustomer()` | Get customer details |\n| `listCustomers()` | List all customers |\n| `trackUsage()` | Record internal usage without billing |\n| `charge()` | Record usage and charge (requires pricing plan) |\n| `emitEvent()` | Record an execution event |\n| `recordRun()` | Record a complete agent run |\n| `startRun()` | Start a run |\n| `endRun()` | End a run |\n| `getBalance()` | Get customer balance |\n\n### Python (`drip-sdk`)\n\n| Method | Description |\n|--------|-------------|\n| `create_customer()` | Create a customer |\n| `get_customer()` | Get customer details |\n| `list_customers()` | List all customers |\n| `track_usage()` | Record internal usage without billing |\n| `charge()` | Record usage and charge (requires pricing plan) |\n| `emit_event()` | Record an execution event |\n| `record_run()` | Record a complete agent run |\n| `start_run()` | Start a run |\n| `end_run()` | End a run |\n| `get_balance()` | Get customer balance |\n\n---\n\n## Two Modes\n\n| Mode | How | When |\n|------|-----|------|\n| **Tracking only** | `trackUsage()` / `track_usage()` | Pilots, analytics, no billing yet |\n| **Billing** | `charge()` + pricing plan | Ready to charge customers |\n\nBoth modes record usage in the ledger. The difference is whether a charge is created.\n\nUse `POST /v1/usage/internal` when you want tracking only.\n\n---\n\n## Authentication\n\n```\nAuthorization: Bearer sk_test_YOUR_KEY\n```\n\n### Key Types\n\n| Key Prefix | Use For |\n|------------|---------|\n| `sk_test_*` / `sk_live_*` | Server-side API access (secret key) |\n| `pk_test_*` / `pk_live_*` | Public key identifier. The role-protected endpoints in this reference require a secret key |\n\n### API Key Roles\n\nSecret keys (`sk_*`) are assigned a role that controls which endpoints they can access. Roles are hierarchical: higher roles include all permissions of lower roles.\n\n| Role | Level | Permissions |\n|------|-------|-------------|\n| `READONLY` | Lowest | List and read resources (customers, charges, pricing plans, events) |\n| `OPERATOR` | Mid | + Create customers, charge usage, track internal usage, emit events, manage runs |\n| `ADMIN` | Highest | + Create/update/delete pricing plans, manage contracts, manage API keys |\n\nPublic keys (`pk_*`) are always `READONLY`: they cannot create or modify resources.\n\n> **Important:** To create, update, or delete **pricing plans** and **contracts**, you must use a secret key (`sk_*`) with the **ADMIN** role. Using a lower-role key returns `403 Forbidden`.\n\n---\n\n## Idempotency\n\nAlways include `idempotencyKey` in POST requests to prevent duplicates:\n\n```json\n{\n \"customerId\": \"cmlxxxxxx...\",\n \"usageType\": \"api_calls\",\n \"quantity\": 1,\n \"idempotencyKey\": \"req_unique_12345\"\n}\n```\n\nSame key = same result. Safe to retry on network failures.\n\n---\n\n## Error Codes\n\n| Status | Meaning | Fix |\n|--------|---------|-----|\n| **400** | Bad request | Check request body matches schema |\n| **401** | Invalid API key | Verify `Authorization: Bearer sk_...` header |\n| **404** | Not found | Customer/pricing plan doesn't exist. Create customer first. |\n| **409** | Duplicate | Resource with this ID already exists |\n| **422** | Validation error | Check required fields and types |\n\n---\n\n## Important Notes\n\n- **Always create a customer first** for billable onboarding flows. You cannot use made-up customer IDs.\n- **`POST /v1/events`** records execution events (what happened). It does **not** auto-create charges.\n- **`POST /v1/usage`** records usage and creates charges if a matching pricing plan exists.\n- **`POST /v1/usage/internal`** records usage without billing.\n- **Numbers as strings**: Monetary amounts are returned as strings (e.g., `\"0.001000\"`) to preserve precision.\n", "version": "1.0.0", "contact": { "name": "Drip Support", "email": "support@drippay.dev" }, "x-logo": { "url": "https://drippay.dev/logo.svg", "altText": "Drip" } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key from Drip Dashboard. Format: `sk_live_...` or `sk_test_...`" } }, "responses": { "BadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Validation failed", "code": "VALIDATION_ERROR", "details": [ { "path": "quantity", "message": "Must be positive" } ] } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid API key", "code": "UNAUTHORIZED" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Customer not found", "code": "NOT_FOUND" } } } }, "PaymentRequired": { "description": "Insufficient balance to process charge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Insufficient balance", "code": "PAYMENT_REQUIRED" } } } }, "Conflict": { "description": "Resource already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Customer already exists", "code": "DUPLICATE_CUSTOMER" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rate limit exceeded", "code": "RATE_LIMIT_EXCEEDED" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] }, "Address": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Ethereum address", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f00000" }, "UsdcAmount": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "USDC amount with up to 6 decimals", "example": "10.500000" } } }, "paths": { "/v1/webhooks/salesforce/{integrationId}": { "post": { "operationId": "salesforceWebhook", "summary": "Salesforce Change Data Capture webhook (HMAC-signed)", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "integrationId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers": { "post": { "operationId": "createCustomer", "summary": "Create a customer", "tags": [ "Customers" ], "description": "Create a customer. Just pass `externalCustomerId` (your user ID). Add `onchainAddress` later for on-chain billing.\n\n> **Requires a secret key (`sk_*`) with at least the `OPERATOR` role.**", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create a customer. At least one of `externalCustomerId` or `onchainAddress` must be provided.", "properties": { "externalCustomerId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your system customer ID. Required if `onchainAddress` is not provided.", "example": "user_789" }, "onchainAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Smart account address. Required if `externalCustomerId` is not provided. Optional for ledger-only use.", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f00000" }, "email": { "type": "string", "format": "email", "maxLength": 320, "description": "Optional end-customer email. When set, invoice PDFs are emailed here automatically on issue, past-due, and payment.", "example": "billing@acme.com" }, "isInternal": { "type": "boolean", "description": "Internal customer (visibility only, no billing)", "example": false, "default": false }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata", "example": { "plan": "pro", "source": "signup" } } }, "required": [] } } }, "description": "Create a customer. At least one of `externalCustomerId` or `onchainAddress` must be provided." }, "responses": { "201": { "description": "Customer created successfully", "content": { "application/json": { "schema": { "description": "Customer created successfully", "type": "object", "properties": { "id": { "type": "string", "description": "Internal customer ID", "example": "cus_abc123def456" }, "businessId": { "type": "string", "description": "Business ID this customer belongs to", "example": "biz_abc123" }, "name": { "type": "string", "nullable": true, "description": "Customer display name", "example": "Acme Logistics" }, "externalCustomerId": { "type": "string", "nullable": true, "description": "Your system customer ID (null if created with onchainAddress only)", "example": "user_789" }, "stripeCustomerId": { "type": "string", "nullable": true, "description": "Stripe customer ID linked via Connect or migration", "example": "cus_StripeXYZ" }, "onchainAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Smart account address (null for internal customers)", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f00000", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true, "description": "End-customer email used for invoice receipt delivery (null if not set)", "example": "billing@acme.com" }, "isInternal": { "type": "boolean", "description": "Internal customer (visibility only, no billing)", "example": false }, "status": { "type": "string", "enum": [ "ACTIVE", "LOW_BALANCE", "PAUSED" ], "description": "Customer status", "example": "ACTIVE" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Arbitrary metadata attached to the customer", "example": { "plan": "pro", "source": "signup" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" }, "provisioningStatus": { "type": "string", "enum": [ "provisioned", "pending", "skipped" ], "description": "Provisioning outcome for the customer smart account", "example": "provisioned" }, "fundingRequired": { "type": "boolean", "description": "True when the smart account exists but still needs funding before billing can proceed", "example": true }, "_warnings": { "type": "array", "items": { "type": "string" }, "description": "Non-fatal warnings generated while creating the customer", "example": [ "External customer ID resembles a patient identifier; avoid storing PHI in identifiers." ] } }, "required": [ "id", "businessId", "isInternal", "status", "createdAt", "updatedAt", "provisioningStatus" ] } } } }, "401": { "description": "Unauthorized - invalid or missing API key", "content": { "application/json": { "schema": { "description": "Unauthorized - invalid or missing API key", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden - customer blocked", "content": { "application/json": { "schema": { "description": "Forbidden - customer blocked", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "409": { "description": "Customer already exists", "content": { "application/json": { "schema": { "description": "Customer already exists", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Service temporarily unavailable: retry with backoff", "content": { "application/json": { "schema": { "description": "Service temporarily unavailable: retry with backoff", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "get": { "operationId": "listCustomers", "summary": "List customers", "tags": [ "Customers" ], "description": "List all customers for your business. Requires a secret key (`sk_*`). Returns up to 100 customers sorted by creation date (newest first).", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of customers to return" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Number of customers to skip (for pagination)" }, { "schema": { "type": "string", "enum": [ "ACTIVE", "LOW_BALANCE", "PAUSED" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by customer status" }, { "schema": { "type": "string" }, "in": "query", "name": "onchainAddress", "required": false, "description": "Filter by on-chain address" }, { "schema": { "type": "boolean" }, "in": "query", "name": "isInternal", "required": false, "description": "Filter by internal customers (true = internal only, false = billing customers only)" } ], "responses": { "200": { "description": "List of customers", "content": { "application/json": { "schema": { "description": "List of customers", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Internal customer ID", "example": "cus_abc123def456" }, "businessId": { "type": "string", "description": "Business ID this customer belongs to", "example": "biz_abc123" }, "name": { "type": "string", "nullable": true, "description": "Customer display name", "example": "Acme Logistics" }, "externalCustomerId": { "type": "string", "nullable": true, "description": "Your system customer ID (null if created with onchainAddress only)", "example": "user_789" }, "stripeCustomerId": { "type": "string", "nullable": true, "description": "Stripe customer ID linked via Connect or migration", "example": "cus_StripeXYZ" }, "onchainAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Smart account address (null for internal customers)", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f00000", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true, "description": "End-customer email used for invoice receipt delivery (null if not set)", "example": "billing@acme.com" }, "isInternal": { "type": "boolean", "description": "Internal customer (visibility only, no billing)", "example": false }, "status": { "type": "string", "enum": [ "ACTIVE", "LOW_BALANCE", "PAUSED" ], "description": "Customer status", "example": "ACTIVE" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Arbitrary metadata attached to the customer", "example": { "plan": "pro", "source": "signup" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "businessId", "isInternal", "status", "createdAt", "updatedAt" ] } }, "count": { "type": "integer", "description": "Number of customers returned" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/customers/{id}": { "get": { "operationId": "getCustomer", "summary": "Get a customer", "tags": [ "Customers" ], "description": "Retrieve a customer by their ID. Requires a secret key (`sk_*`).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Customer ID" } ], "responses": { "200": { "description": "Customer details", "content": { "application/json": { "schema": { "description": "Customer details", "type": "object", "properties": { "id": { "type": "string", "description": "Internal customer ID", "example": "cus_abc123def456" }, "businessId": { "type": "string", "description": "Business ID this customer belongs to", "example": "biz_abc123" }, "name": { "type": "string", "nullable": true, "description": "Customer display name", "example": "Acme Logistics" }, "externalCustomerId": { "type": "string", "nullable": true, "description": "Your system customer ID (null if created with onchainAddress only)", "example": "user_789" }, "stripeCustomerId": { "type": "string", "nullable": true, "description": "Stripe customer ID linked via Connect or migration", "example": "cus_StripeXYZ" }, "onchainAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Smart account address (null for internal customers)", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f00000", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true, "description": "End-customer email used for invoice receipt delivery (null if not set)", "example": "billing@acme.com" }, "isInternal": { "type": "boolean", "description": "Internal customer (visibility only, no billing)", "example": false }, "status": { "type": "string", "enum": [ "ACTIVE", "LOW_BALANCE", "PAUSED" ], "description": "Customer status", "example": "ACTIVE" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Arbitrary metadata attached to the customer", "example": { "plan": "pro", "source": "signup" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00Z" } }, "required": [ "id", "businessId", "isInternal", "status", "createdAt", "updatedAt" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "patch": { "operationId": "updateCustomer", "summary": "Update a customer", "tags": [ "Customers" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/billing-history": { "get": { "operationId": "getCustomerBillingHistory", "summary": "Get customer billing-field history", "tags": [ "Customers" ], "description": "Return every snapshot of this customer's billing-relevant fields (name, email), oldest → newest. A v1 snapshot is created when the customer is first created; each subsequent change appends a new version and seals the previous one.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Billing history", "content": { "application/json": { "schema": { "description": "Billing history", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Customer not found" } } } } } } }, "/v1/customers/{id}/revops-summary": { "get": { "operationId": "getCustomerRevOpsSummary", "summary": "Get RevOps summary", "tags": [ "Customers" ], "description": "Aggregated revenue/operations summary for a customer: reputation band, lifetime revenue, cost, gross margin, success rate, and top unit types. Requires a secret key (`sk_*`).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Customer ID" } ], "responses": { "200": { "description": "RevOps summary", "content": { "application/json": { "schema": { "description": "RevOps summary", "type": "object", "properties": { "reputationScore": { "type": "number" }, "reputationBand": { "type": "string", "enum": [ "EXCELLENT", "GOOD", "FAIR", "POOR", "HIGH_RISK" ] }, "lifetimeRevenueUsdc": { "type": "string" }, "lifetimeCostUsdc": { "type": "string" }, "grossMarginUsdc": { "type": "string" }, "grossMarginPct": { "type": "number" }, "chargeSuccessRate": { "type": "number" }, "disputeCount": { "type": "number" }, "anomalyCount": { "type": "number" }, "tenureDays": { "type": "number" }, "lastActivityAt": { "type": "string", "format": "date-time", "nullable": true }, "topUnitTypes": { "type": "array", "items": { "type": "object", "properties": { "unitType": { "type": "string" }, "revenueUsdc": { "type": "string" }, "marginPct": { "type": "number" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/customers/{id}/sync-balance": { "post": { "operationId": "syncCustomerBalance", "summary": "Sync customer balance", "tags": [ "Customers" ], "description": "\nTriggers an immediate balance sync for a customer. This fetches the current\non-chain balance and updates the database snapshot.\n\nUse this endpoint:\n- After a customer deposits funds on-chain\n- To verify balance accuracy before a charge\n- For debugging balance discrepancies\n\nThe response includes both previous and new balances, along with whether\na change was detected. Requires a secret key (`sk_*`).\n ", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Customer ID" } ], "responses": { "200": { "description": "Balance sync completed", "content": { "application/json": { "schema": { "description": "Balance sync completed", "type": "object", "properties": { "customerId": { "type": "string", "description": "Customer ID" }, "previousBalance": { "type": "string", "description": "Previous balance in USDC" }, "newBalance": { "type": "string", "description": "Current on-chain balance in USDC" }, "changed": { "type": "boolean", "description": "Whether the balance changed" }, "blockNumber": { "type": "string", "description": "Block number when balance was checked" }, "syncedAt": { "type": "string", "format": "date-time", "description": "Timestamp of sync" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/customers/{id}/provision": { "post": { "operationId": "provisionSmartAccount", "summary": "Provision smart account", "tags": [ "Customers" ], "description": "\nDeploy an ERC-4337 smart account for a customer and deposit USDC into the BillingModule.\n\nOn testnet (Base Sepolia), this automatically mints and deposits test USDC.\nOn mainnet, the customer must deposit USDC separately after deployment.\n\nThe smart account is owned by the billing authority for server-side management.\nRequires a secret key (`sk_*`).\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "deposit_amount_usdc": { "type": "string", "description": "USDC amount to deposit into BillingModule (testnet only, default: \"100\")" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Customer ID" } ], "responses": { "200": { "description": "Smart account provisioned", "content": { "application/json": { "schema": { "description": "Smart account provisioned", "type": "object", "properties": { "smart_account_address": { "type": "string" }, "already_deployed": { "type": "boolean" }, "deploy_tx_hash": { "type": "string", "nullable": true }, "fund_tx_hash": { "type": "string", "nullable": true }, "billing_deposit_tx_hash": { "type": "string", "nullable": true }, "billing_balance_usdc": { "type": "string" }, "funding_required": { "type": "boolean", "description": "True when the customer must fund their account via checkout (mainnet)" } } } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "description": "Invalid request", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/customers/{id}/spending-cap": { "put": { "operationId": "setCustomerSpendingCap", "summary": "Set customer spending cap", "tags": [ "Customers" ], "description": "Set or update a per-customer spending cap. Supports DAILY_CHARGE_LIMIT, MONTHLY_CHARGE_LIMIT, and SINGLE_CHARGE_LIMIT. When autoBlock=true (default), charges are rejected at 100% of the cap. Requires a secret key (`sk_*`).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "capType", "limitValue" ], "properties": { "capType": { "type": "string", "enum": [ "DAILY_CHARGE_LIMIT", "MONTHLY_CHARGE_LIMIT", "SINGLE_CHARGE_LIMIT" ], "description": "Type of spending cap" }, "limitValue": { "type": "number", "description": "Spending limit in USDC" }, "autoBlock": { "type": "boolean", "description": "Auto-block charges when cap is reached (default: true)" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Spending cap set", "content": { "application/json": { "schema": { "description": "Spending cap set", "type": "object", "properties": { "id": { "type": "string" }, "capType": { "type": "string" }, "limitValue": { "type": "string" }, "autoBlock": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/v1/customers/{id}/spending-caps": { "get": { "operationId": "listCustomerSpendingCaps", "summary": "List customer spending caps", "tags": [ "Customers" ], "description": "List all active spending caps for a customer, including current usage and last alert level. Requires a secret key (`sk_*`).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Spending caps", "content": { "application/json": { "schema": { "description": "Spending caps", "type": "object", "properties": { "caps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "capType": { "type": "string" }, "limitValue": { "type": "string" }, "currentUsage": { "type": "string" }, "autoBlock": { "type": "boolean" }, "lastAlertLevel": { "type": "string", "nullable": true } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/v1/customers/{id}/spending-caps/{capId}": { "delete": { "operationId": "removeCustomerSpendingCap", "summary": "Remove customer spending cap", "tags": [ "Customers" ], "description": "Deactivate a spending cap for a customer. Requires a secret key (`sk_*`).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "capId", "required": true } ], "responses": { "200": { "description": "Cap removed", "content": { "application/json": { "schema": { "description": "Cap removed", "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } }, "404": { "description": "Customer or cap not found", "content": { "application/json": { "schema": { "description": "Customer or cap not found", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/v1/customers/{id}/attach-plan": { "post": { "operationId": "attachPlanToCustomer", "summary": "Attach a Quickstart-managed plan to a customer", "tags": [ "Customers" ], "description": "Creates a Stripe Subscription on the merchant's connected account for the given Drip (customer, plan) pair. The plan MUST be Drip-managed (`managedBy=DRIP`); run provisionPlanOnStripe / POST `/pricing-plans/:id/reprovision-stripe` first if the plan is still `EXTERNAL`. Idempotent: re-calling with the same customer + plan returns the existing subscription.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string", "description": "Drip pricing plan id" }, "customerEmailOverride": { "type": "string", "description": "Optional email to send to Stripe when the Drip customer row has none. Ignored if the customer already has an email." } }, "required": [ "planId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Drip customer id" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/sync-stripe-customer": { "post": { "operationId": "syncCustomerToStripe", "summary": "Sync a Drip customer to Stripe (create cus_xxx and link)", "tags": [ "Customers" ], "description": "Create a Stripe Customer on the merchant's connected Stripe account for the given Drip customer and persist the resulting `cus_xxx` on the Drip customer row. Idempotent: if the Drip customer already has a `stripeCustomerId`, returns it unchanged. Works with API-key or OAuth-connected Stripe integrations. Email/name are pulled from the Drip customer's `metadata.email` / `metadata.name`, falling back to `externalCustomerId` when it looks like an email, then to `emailOverride` from the request body.\n\n> **Requires a secret key (`sk_*`) with at least the `OPERATOR` role.**", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "integrationId": { "type": "string", "description": "Specific Stripe integration to use. Omit to auto-select the workspace's active Stripe integration." }, "emailOverride": { "type": "string", "description": "Email to send to Stripe when the Drip customer has none in metadata or externalCustomerId." } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Drip customer id" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/hierarchy": { "get": { "operationId": "getCustomerHierarchy", "summary": "Get customer hierarchy", "tags": [ "Customers" ], "description": "Returns the full ancestor chain (parent, grandparent, …) and all descendants for a customer.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/rollup": { "get": { "operationId": "getCustomerRollup", "summary": "Get customer roll-up stats", "tags": [ "Customers" ], "description": "Aggregated invoice totals and usage across this customer and all descendants.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/drift/stripe": { "get": { "operationId": "listStripeDriftFindings", "summary": "List Stripe drift findings", "tags": [ "Drift" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/drift/customer": { "get": { "operationId": "listCustomerDriftFindings", "summary": "List customer churn-risk findings", "tags": [ "Drift" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/drift/config": { "get": { "operationId": "listConfigDriftFindings", "summary": "List config drift findings", "tags": [ "Drift" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/drift/summary": { "get": { "operationId": "getDriftSummary", "summary": "Per-kind drift summary", "tags": [ "Drift" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/drift/findings/{id}": { "get": { "operationId": "getDriftFinding", "summary": "Get a single drift finding (Mac-app deep-link target)", "tags": [ "Drift" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "operationId": "updateDriftFinding", "summary": "Acknowledge / resolve / suppress a finding", "tags": [ "Drift" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/drift/{kind}/run": { "post": { "operationId": "runDriftDetector", "summary": "Enqueue an on-demand drift detector run", "tags": [ "Drift" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "kind", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/webhooks/events": { "get": { "operationId": "listWebhookEventTypes", "summary": "List webhook event types", "tags": [ "Webhooks" ], "description": "Get all available webhook event types with descriptions. **Requires a secret key (sk_).** Public keys (pk_) will receive a 403 error.", "responses": { "200": { "description": "Available event types", "content": { "application/json": { "schema": { "description": "Available event types", "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string" }, "description": "List of all available event types", "example": [ "charge.succeeded", "charge.failed", "customer.balance.low", "customer.deposit.confirmed" ] }, "description": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Human-readable descriptions for each event type", "example": { "charge.succeeded": "Charge confirmed on-chain - unlock service, update billing UI", "charge.failed": "Charge failed - trigger retries, alerts, user notification", "customer.balance.low": "Customer drops below configured threshold - prevent surprise outages" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/webhooks": { "post": { "operationId": "createWebhook", "summary": "Create a webhook", "tags": [ "Webhooks" ], "description": "\nCreate a new webhook endpoint to receive real-time event notifications. **Requires a secret key (sk_).**\n\n**Important:** The `secret` is only returned once on creation. Save it\nimmediately for HMAC signature verification. Public keys (pk_) cannot access this endpoint.\n\n**Signature verification:**\n```javascript\nconst signature = crypto\n .createHmac('sha256', secret)\n .update(JSON.stringify(payload))\n .digest('hex');\n// Compare with X-Drip-Signature header\n```\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body for creating a webhook endpoint.", "properties": { "url": { "type": "string", "format": "uri", "description": "HTTPS endpoint URL. Must be publicly accessible and return 200 OK within 30 seconds.", "example": "https://api.example.com/webhooks/drip" }, "events": { "type": "array", "description": "Event types to subscribe to. Use [\"*\"] for all events.", "items": { "type": "string" }, "example": [ "charge.succeeded", "charge.failed", "customer.balance.low" ] }, "description": { "type": "string", "description": "Optional description to help identify this webhook", "example": "Production billing notifications" } }, "required": [ "url", "events" ] } } }, "description": "Request body for creating a webhook endpoint." }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "description": "Webhook created", "type": "object", "properties": { "id": { "type": "string", "description": "Unique webhook identifier", "example": "whk_abc123def456" }, "url": { "type": "string", "format": "uri", "description": "Your webhook endpoint", "example": "https://api.example.com/webhooks/drip" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Subscribed event types", "example": [ "charge.succeeded", "charge.failed", "customer.balance.low" ] }, "description": { "type": "string", "nullable": true, "description": "Optional description", "example": "Production billing events" }, "isActive": { "type": "boolean", "description": "Whether the webhook is active", "example": true }, "secret": { "type": "string", "description": "HMAC secret for signature verification. SAVE THIS - it will not be shown again!", "example": "whsec_abcdef123456789..." }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" }, "message": { "type": "string", "description": "Reminder to save the secret", "example": "Save the secret - it will not be shown again!" } } } } } }, "400": { "description": "Invalid URL or events", "content": { "application/json": { "schema": { "description": "Invalid URL or events", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "get": { "operationId": "listWebhooks", "summary": "List webhooks", "tags": [ "Webhooks" ], "description": "Get all webhooks for your business with delivery statistics. **Requires a secret key (sk_).** Public keys (pk_) will receive a 403 error.", "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "description": "List of webhooks", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique webhook identifier", "example": "whk_abc123def456" }, "url": { "type": "string", "format": "uri", "description": "Endpoint URL that receives events", "example": "https://api.example.com/webhooks/drip" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types this webhook subscribes to", "example": [ "charge.succeeded", "charge.failed" ] }, "description": { "type": "string", "nullable": true, "description": "Optional description", "example": "Production billing events" }, "isActive": { "type": "boolean", "description": "Whether the webhook is active", "example": true }, "healthStatus": { "type": "string", "enum": [ "HEALTHY", "DEGRADED", "UNHEALTHY" ], "description": "Health status from circuit breaker", "example": "HEALTHY" }, "consecutiveFailures": { "type": "integer", "description": "Number of consecutive delivery failures", "example": 0 }, "lastHealthChange": { "type": "string", "format": "date-time", "nullable": true, "description": "When health status last changed", "example": null }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" }, "stats": { "type": "object", "description": "Delivery statistics for this webhook", "properties": { "total": { "type": "integer", "description": "Total events sent", "example": 1250 }, "delivered": { "type": "integer", "description": "Successfully delivered", "example": 1245 }, "failed": { "type": "integer", "description": "Failed after retries", "example": 3 }, "pending": { "type": "integer", "description": "Currently retrying", "example": 2 } } } } } }, "count": { "type": "integer", "description": "Total webhooks", "example": 2 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/webhooks/{id}": { "get": { "operationId": "getWebhook", "summary": "Get a webhook", "tags": [ "Webhooks" ], "description": "Retrieve a webhook by ID with delivery statistics. **Requires a secret key (sk_).**", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook ID" } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "type": "object", "description": "Webhook details", "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook", "example": "whk_abc123def456" }, "url": { "type": "string", "format": "uri", "description": "The HTTPS endpoint that receives webhook payloads", "example": "https://api.example.com/webhooks/drip" }, "events": { "type": "array", "description": "List of event types this webhook subscribes to", "items": { "type": "string", "enum": [ "charge.succeeded", "charge.failed", "charge.refunded", "usage.recorded", "customer.created", "customer.deposit.confirmed", "customer.withdraw.confirmed", "customer.balance.low", "customer.usage_cap.reached", "customer.spending.warning", "customer.spending.blocked", "customer.spending.exceeded", "webhook.endpoint.unhealthy", "api_key.created", "api_key.rotated", "pricing_plan.updated", "transaction.created", "transaction.pending", "transaction.confirmed", "transaction.failed", "contract.created", "contract.updated", "contract.cancelled", "subscription.created", "subscription.cancelled", "invoice.created", "invoice.issued", "invoice.paid", "invoice.voided", "entitlement_plan.created", "entitlement_plan.updated", "entitlement_plan.deleted", "customer.entitlement.assigned" ] }, "example": [ "charge.succeeded", "charge.failed", "customer.balance.low" ] }, "isActive": { "type": "boolean", "description": "Whether the webhook is currently receiving events", "example": true }, "secret": { "type": "string", "description": "Secret key for verifying webhook signatures (only returned on creation)", "example": "whsec_abc123..." }, "description": { "type": "string", "description": "Optional description for this webhook", "example": "Production billing events" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the webhook was created", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "url", "events", "isActive" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Webhook not found" } } } } } }, "patch": { "operationId": "updateWebhook", "summary": "Update a webhook", "tags": [ "Webhooks" ], "description": "Update webhook URL, events, or status. **Requires a secret key (sk_).**", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "New webhook URL" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Events to subscribe to" }, "description": { "type": "string" }, "isActive": { "type": "boolean", "description": "Enable/disable the webhook" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook ID" } ], "responses": { "200": { "description": "Webhook updated", "content": { "application/json": { "schema": { "type": "object", "description": "Webhook updated", "properties": { "id": { "type": "string", "description": "Unique identifier for the webhook", "example": "whk_abc123def456" }, "url": { "type": "string", "format": "uri", "description": "The HTTPS endpoint that receives webhook payloads", "example": "https://api.example.com/webhooks/drip" }, "events": { "type": "array", "description": "List of event types this webhook subscribes to", "items": { "type": "string", "enum": [ "charge.succeeded", "charge.failed", "charge.refunded", "usage.recorded", "customer.created", "customer.deposit.confirmed", "customer.withdraw.confirmed", "customer.balance.low", "customer.usage_cap.reached", "customer.spending.warning", "customer.spending.blocked", "customer.spending.exceeded", "webhook.endpoint.unhealthy", "api_key.created", "api_key.rotated", "pricing_plan.updated", "transaction.created", "transaction.pending", "transaction.confirmed", "transaction.failed", "contract.created", "contract.updated", "contract.cancelled", "subscription.created", "subscription.cancelled", "invoice.created", "invoice.issued", "invoice.paid", "invoice.voided", "entitlement_plan.created", "entitlement_plan.updated", "entitlement_plan.deleted", "customer.entitlement.assigned" ] }, "example": [ "charge.succeeded", "charge.failed", "customer.balance.low" ] }, "isActive": { "type": "boolean", "description": "Whether the webhook is currently receiving events", "example": true }, "secret": { "type": "string", "description": "Secret key for verifying webhook signatures (only returned on creation)", "example": "whsec_abc123..." }, "description": { "type": "string", "description": "Optional description for this webhook", "example": "Production billing events" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the webhook was created", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "url", "events", "isActive" ] } } } }, "400": { "description": "Invalid URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Invalid URL" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Webhook not found" } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook", "tags": [ "Webhooks" ], "description": "Permanently delete a webhook. This cannot be undone. **Requires a secret key (sk_).**", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook ID" } ], "responses": { "204": { "description": "Webhook deleted", "content": { "application/json": { "schema": { "description": "Webhook deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "description": "Webhook not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Rotate webhook secret", "tags": [ "Webhooks" ], "description": "\nGenerate a new HMAC secret for signature verification. **Requires a secret key (sk_).**\n\n**Important:** The new secret is only returned once. Update your webhook\nhandler immediately to use the new secret.\n ", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook ID" } ], "responses": { "200": { "description": "New secret generated", "content": { "application/json": { "schema": { "description": "New secret generated", "type": "object", "properties": { "secret": { "type": "string", "description": "New HMAC secret (only shown once!)" }, "message": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "description": "Webhook not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List webhook deliveries", "tags": [ "Webhooks" ], "description": "Get recent delivery attempts for a webhook. **Requires a secret key (sk_).**", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false, "description": "Maximum deliveries to return" }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook ID" } ], "responses": { "200": { "description": "List of deliveries", "content": { "application/json": { "schema": { "description": "List of deliveries", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "eventId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "DELIVERED", "FAILED" ] }, "attempts": { "type": "integer" }, "responseCode": { "type": "integer", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "lastAttemptAt": { "type": "string", "format": "date-time", "nullable": true } } } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "description": "Webhook not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/webhooks/{id}/deliveries/{deliveryId}": { "get": { "operationId": "getWebhookDelivery", "summary": "Get a webhook delivery", "tags": [ "Webhooks" ], "description": "Retrieve details for a single webhook delivery attempt. **Requires a secret key (sk_).**", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook ID" }, { "schema": { "type": "string" }, "in": "path", "name": "deliveryId", "required": true, "description": "Delivery ID" } ], "responses": { "200": { "description": "Delivery details", "content": { "application/json": { "schema": { "description": "Delivery details", "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "eventId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "DELIVERED", "FAILED" ] }, "attempts": { "type": "integer" }, "responseCode": { "type": "integer", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "lastAttemptAt": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Webhook or delivery not found", "content": { "application/json": { "schema": { "description": "Webhook or delivery not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/webhooks/{id}/deliveries/{deliveryId}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Retry a delivery", "tags": [ "Webhooks" ], "description": "Manually retry a failed webhook delivery. **Requires a secret key (sk_).**", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook ID" }, { "schema": { "type": "string" }, "in": "path", "name": "deliveryId", "required": true, "description": "Delivery ID" } ], "responses": { "200": { "description": "Delivery queued for retry", "content": { "application/json": { "schema": { "description": "Delivery queued for retry", "type": "object", "properties": { "message": { "type": "string" }, "deliveryId": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Webhook or delivery not found", "content": { "application/json": { "schema": { "description": "Webhook or delivery not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Test a webhook", "tags": [ "Webhooks" ], "description": "Send a test event to verify the webhook endpoint is working. **Requires a secret key (sk_).**", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Webhook ID" } ], "responses": { "200": { "description": "Test event sent", "content": { "application/json": { "schema": { "description": "Test event sent", "type": "object", "properties": { "message": { "type": "string" }, "deliveryId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "DELIVERED", "FAILED", "NOT_SENT" ] }, "responseCode": { "type": "integer", "nullable": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Webhook not found", "content": { "application/json": { "schema": { "description": "Webhook not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/business/settings": { "get": { "operationId": "getBusinessSettings", "summary": "Get business settings", "tags": [ "Business" ], "description": "Returns business-level billing settings, including the default reporting currency used when no contract or pricing plan overrides it.", "responses": { "200": { "description": "Default Response" } } }, "patch": { "operationId": "updateBusinessSettings", "summary": "Update business settings", "tags": [ "Business" ], "description": "Update business-level billing settings. Currently only the default reporting currency is mutable via this endpoint.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations": { "get": { "operationId": "listIntegrations", "summary": "List marketplace & CRM integrations", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } }, "post": { "operationId": "createIntegration", "summary": "Create a marketplace / CRM integration", "tags": [ "Integrations" ], "description": "Create a new marketplace or CRM integration.\n\nSupported providers:\n- `AWS_MARKETPLACE` - AWS Marketplace Metering Service\n- `AZURE_MARKETPLACE` - Azure Marketplace SaaS metering\n- `GCP_MARKETPLACE` - GCP Cloud Commerce / Service Control\n- `STRIPE` - Stripe Billing Meter Events\n- `SALESFORCE` - Salesforce CRM (custom usage object)\n- `METRONOME` - Metronome usage ingestion\n\nSecret config fields are encrypted at rest and never returned on read.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/{id}": { "get": { "operationId": "getIntegration", "summary": "Get a marketplace integration", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "operationId": "updateIntegration", "summary": "Update an integration (rotate secrets, toggle status)", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "deleteIntegration", "summary": "Delete an integration", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/{id}/test": { "post": { "operationId": "testIntegration", "summary": "Test an integration connection", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/{id}/usage": { "post": { "operationId": "submitIntegrationUsage", "summary": "Submit a metered usage record to the provider", "tags": [ "Integrations" ], "description": "Forwards a single metered usage record to the connected marketplace or CRM. A MarketplaceMeterSubmission row is always written as an audit trail, even if the provider call fails. Idempotency is guaranteed via the `idempotencyKey` field (auto-generated when omitted).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/{id}/submissions": { "get": { "operationId": "listIntegrationSubmissions", "summary": "List recent meter submissions", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string", "enum": [ "PENDING", "SUBMITTED", "FAILED", "RETRYING", "REJECTED" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/test": { "post": { "operationId": "testStripeOnboarding", "summary": "Validate Stripe credentials (no side effects)", "tags": [ "Integrations" ], "description": "Validates a Stripe secret or restricted key (and optional webhook secret) against Stripe's /v1/account endpoint. Probes tax/billing/invoicing capabilities when scoped keys are provided. Returns account metadata on success. **No database writes.** Requires a secret key with the `ADMIN` role.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/connect": { "post": { "operationId": "connectStripeIntegration", "summary": "Connect a Stripe account via API key", "tags": [ "Integrations" ], "description": "Validates Stripe credentials, creates a `MarketplaceIntegration` row (idempotent on Stripe account ID), optionally flips `taxProvider` to `STRIPE_TAX`, and returns the webhook URL the merchant must paste into their Stripe dashboard. Retrying this endpoint with the same Stripe account returns the existing integration with `alreadyExists: true`. Requires `API_PUBLIC_BASE_URL` to be set; webhook URL has no host header fallback. **Requires a secret key with the `ADMIN` role.**", "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/oauth/init": { "post": { "operationId": "initStripeQuickstartOAuth", "summary": "Begin Stripe Connect OAuth (Quickstart mode)", "tags": [ "Integrations" ], "description": "Generates a Stripe Connect authorize URL and a signed state token. The frontend redirects the user's browser to `authorizeUrl`; Stripe then redirects back to `/v1/integrations/stripe/oauth/callback` where Drip exchanges the code, creates the integration, and auto-provisions the webhook endpoint. Gated on the `STRIPE_QUICKSTART_ENABLED` feature flag; returns 404 if disabled for the workspace.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/oauth/callback": { "get": { "operationId": "stripeQuickstartOAuthCallback", "summary": "Stripe Connect OAuth redirect handler", "tags": [ "Integrations" ], "description": "Public redirect endpoint Stripe posts the user back to after they authorize the Connect app. Verifies the state HMAC + expiry, exchanges the code for the connected `acct_…` id, creates the integration, auto-provisions the webhook endpoint, and 302-redirects the browser to the dashboard with a `?quickstart=success|error` hint.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/comms/slack/install": { "post": { "operationId": "commsSlackInstall", "summary": "Begin Slack OAuth (pre-call MVP)", "tags": [ "Integrations" ], "responses": { "200": { "description": "Authorize URL issued", "content": { "application/json": { "schema": { "description": "Authorize URL issued", "type": "object", "required": [ "authorizeUrl", "state", "expiresInSeconds" ], "properties": { "authorizeUrl": { "type": "string", "format": "uri" }, "state": { "type": "string" }, "expiresInSeconds": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "description": "Internal error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "description": "OAuth provider not configured", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/integrations/comms/slack/realtime/stream": { "get": { "operationId": "commsSlackRealtimeStream", "summary": "Stream managed Slack realtime messages to desktop clients", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/comms/slack/events/stream": { "get": { "operationId": "commsSlackEventsStream", "summary": "Stream managed Slack realtime messages to desktop clients", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/comms/linkedin/realtime/stream": { "get": { "operationId": "commsLinkedInRealtimeStream", "summary": "Stream managed LinkedIn realtime events to desktop clients", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/comms/linkedin/events/stream": { "get": { "operationId": "commsLinkedInEventsStream", "summary": "Stream managed LinkedIn realtime events to desktop clients", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/comms/linkedin/events": { "post": { "operationId": "commsLinkedInRealtimePublish", "summary": "Publish local LinkedIn realtime events to desktop clients", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/desktop/feature-flags": { "get": { "operationId": "desktopFeatureFlags", "summary": "Per-account desktop (dripos) feature-flag entitlements", "description": "Returns the per-account feature-flag entitlements for the authenticated business. The desktop (dripos) client treats every flag as a grant that fails closed: any flag not returned with `enabled: true` is denied client-side. Entitlements are resolved server-side from a per-account allowlist keyed on the business's unique email. Requires a secret key (`sk_*`); public keys (`pk_*`) receive `403 Forbidden`.", "tags": [ "Internal" ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Per-account feature-flag entitlements", "content": { "application/json": { "schema": { "type": "object", "properties": { "entitlements": { "type": "object", "description": "Map of desktop feature-flag key to grant. Any flag not present, or present with `enabled: false`, is denied client-side.", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether this flag is granted for the authenticated account." } }, "required": [ "enabled" ] }, "properties": { "postEngagementScrape": { "type": "object", "description": "LinkedIn post-engagement scraper. Restricted to allowlisted internal operators.", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] } }, "required": [ "postEngagementScrape" ] } }, "required": [ "entitlements" ] }, "example": { "entitlements": { "postEngagementScrape": { "enabled": false } } } } } }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "A public key (`pk_*`) was used. A secret key (`sk_*`) is required." } } } }, "/v1/integrations/comms/slack/callback": { "get": { "operationId": "commsSlackCallback", "summary": "Slack OAuth redirect handler", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/comms/gmail/install": { "post": { "operationId": "commsGmailInstall", "summary": "Begin Gmail OAuth (pre-call MVP)", "tags": [ "Integrations" ], "responses": { "200": { "description": "Authorize URL issued", "content": { "application/json": { "schema": { "description": "Authorize URL issued", "type": "object", "required": [ "authorizeUrl", "state", "expiresInSeconds" ], "properties": { "authorizeUrl": { "type": "string", "format": "uri" }, "state": { "type": "string" }, "expiresInSeconds": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "description": "Internal error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "description": "OAuth provider not configured", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/integrations/comms/gmail/callback": { "get": { "operationId": "commsGmailCallback", "summary": "Gmail OAuth redirect handler", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/comms/calendar/callback": { "get": { "operationId": "commsCalendarCallback", "summary": "Google Calendar OAuth redirect handler", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/comms": { "get": { "operationId": "commsList", "summary": "List comms integrations for the authenticated business", "tags": [ "Integrations" ], "responses": { "200": { "description": "Integrations list", "content": { "application/json": { "schema": { "description": "Integrations list", "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "provider", "status", "scopes", "createdAt" ], "properties": { "id": { "type": "string" }, "provider": { "type": "string", "enum": [ "SLACK", "GMAIL" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "ERROR", "PENDING" ] }, "externalAccountLabel": { "type": "string", "nullable": true }, "scopes": { "type": "array", "items": { "type": "string" } }, "lastSyncedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastErrorMessage": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "description": "Internal error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "description": "OAuth provider not configured", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/integrations/comms/slack/doctor": { "get": { "operationId": "commsSlackDoctor", "summary": "Diagnose Slack OAuth, realtime events, and stored comms state for the authenticated business", "tags": [ "Integrations" ], "responses": { "200": { "description": "Slack diagnostics", "content": { "application/json": { "schema": { "description": "Slack diagnostics", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "description": "Internal error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "description": "OAuth provider not configured", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/integrations/comms/messages": { "get": { "operationId": "commsMessagesList", "summary": "List recently ingested comms messages for the authenticated business", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string", "enum": [ "SLACK", "GMAIL" ] }, "in": "query", "name": "provider", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "since", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "before", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Comms messages list", "content": { "application/json": { "schema": { "description": "Comms messages list", "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "direction", "externalId", "body", "sentAt" ], "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "SLACK_DM", "SLACK_CHANNEL", "GMAIL" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "externalId": { "type": "string" }, "threadExternalId": { "type": "string", "nullable": true }, "senderEmail": { "type": "string", "nullable": true }, "senderHandle": { "type": "string", "nullable": true }, "channelName": { "type": "string", "nullable": true }, "subject": { "type": "string", "nullable": true }, "body": { "type": "string" }, "permalink": { "type": "string", "nullable": true }, "sentAt": { "type": "string", "format": "date-time" }, "metadata": { "type": [ "null", "object" ], "additionalProperties": true } } } }, "nextCursor": { "type": "string", "nullable": true }, "hasMore": { "type": "boolean" }, "complete": { "type": "boolean" }, "highWaterTs": { "type": "number", "nullable": true } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "description": "Bad request", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "description": "Internal error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "502": { "description": "Upstream provider error", "content": { "application/json": { "schema": { "description": "Upstream provider error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "description": "OAuth provider not configured", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/integrations/comms/slack/send": { "post": { "operationId": "commsSlackSend", "summary": "Send a Slack message through the authenticated business integration", "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target", "body" ], "properties": { "target": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1, "maxLength": 40000 } } } } } }, "responses": { "200": { "description": "Slack message sent", "content": { "application/json": { "schema": { "description": "Slack message sent", "type": "object", "required": [ "sourceId", "channelId", "ts" ], "properties": { "sourceId": { "type": "string" }, "channelId": { "type": "string" }, "threadExternalId": { "type": "string", "nullable": true }, "ts": { "type": "string" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "description": "Bad request", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "description": "Internal error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "502": { "description": "Upstream provider error", "content": { "application/json": { "schema": { "description": "Upstream provider error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "description": "OAuth provider not configured", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/integrations/comms/{id}": { "delete": { "operationId": "commsDelete", "summary": "Disconnect a comms integration", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Disconnected" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "description": "Internal error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "description": "OAuth provider not configured", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/integrations/comms/{id}/sync": { "post": { "operationId": "commsManualSync", "summary": "Trigger an immediate poll for a comms integration", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Sync result", "content": { "application/json": { "schema": { "description": "Sync result", "type": "object", "required": [ "inserted", "matchedCustomers", "errors" ], "properties": { "inserted": { "type": "integer", "minimum": 0 }, "matchedCustomers": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "description": "Internal error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "501": { "description": "Provider not yet supported by manual sync", "content": { "application/json": { "schema": { "description": "Provider not yet supported by manual sync" } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "description": "OAuth provider not configured", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/customers/{customerId}/comms/link": { "post": { "operationId": "commsLinkHandle", "summary": "Manually attribute past + future comm messages to a customer", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "customerId", "required": true } ], "responses": { "200": { "description": "Number of messages linked", "content": { "application/json": { "schema": { "description": "Number of messages linked", "type": "object", "required": [ "matched" ], "properties": { "matched": { "type": "integer", "minimum": 0 } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "description": "Forbidden", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "description": "Internal error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "OAuth provider not configured", "content": { "application/json": { "schema": { "description": "OAuth provider not configured", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/sync/touches": { "post": { "operationId": "syncTouches", "summary": "Sync customer touches from drip-cli", "tags": [ "Integrations" ], "description": "Push a batch of communication touches (iMessage / Slack / Gmail / LinkedIn / calendar / GitHub) to Drip. Body is truncated server-side to 200 chars; full message contents should never be sent. Each touch is matched to an existing Customer by email (case-insensitive); unmatched rows are still stored with customerId=null so a future re-resolve can backfill the link. Idempotent on `sourceId`. Capped at 500 touches per request.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/touches": { "get": { "operationId": "listCustomerTouches", "summary": "List recent touches for a customer", "tags": [ "Customers" ], "description": "Return the most recent touches for a customer, ordered by `ts` descending. Default limit 10, max 100. Touches are pushed by drip-cli via POST /v1/sync/touches; this endpoint surfaces the last-N preview metadata.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Customer ID" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/opens-since": { "get": { "operationId": "listEmailOpensSince", "summary": "List email opens since a unix timestamp", "tags": [ "Integrations" ], "description": "Return email-pixel opens with `opened_at >= ts` (unix seconds). drip-cli polls this endpoint with its last-sync watermark, matches incoming tokens against its local `email_opens` table, and updates open counts for tokens it owns. Unknown tokens are ignored. Capped at 5000 rows per call (default 1000); the cli re-polls with an advanced watermark.", "parameters": [ { "schema": { "type": "integer", "minimum": 0 }, "in": "query", "name": "ts", "required": true, "description": "Unix seconds. Returns opens with opened_at >= this value." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/migrate/dry-run": { "post": { "operationId": "stripeMigrateDryRun", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/migrate/execute": { "post": { "operationId": "stripeMigrateExecute", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/migrate/status": { "get": { "operationId": "stripeMigrateStatus", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/migrate/runs": { "get": { "operationId": "stripeMigrateListRuns", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/migrate/runs/{id}": { "get": { "operationId": "stripeMigrateGetRun", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "stripeMigrateRollback", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/migrate/runs/{id}/rollback": { "post": { "operationId": "stripeMigrateRollbackPost", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/stripe/customers": { "get": { "operationId": "stripeListCustomers", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/import/dry-run": { "post": { "operationId": "csvImportDryRun", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/import/execute": { "post": { "operationId": "csvImportExecute", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/import/status": { "get": { "operationId": "csvImportStatus", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/import/runs": { "get": { "operationId": "csvImportListRuns", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/import/runs/{id}": { "get": { "operationId": "csvImportGetRun", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "csvImportRollback", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/import/runs/{id}/rollback": { "post": { "operationId": "csvImportRollbackPost", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/lead-sources/webhook/connect": { "post": { "operationId": "connectLeadWebhookSource", "summary": "Create or rotate a lead-source webhook setup", "description": "Provisions (or rotates) a generic lead-source webhook for the authenticated business. Returns the public ingest endpoint, a bearer token to use in the `Authorization` header, the connection identifier, and a sample request body. Requires a secret key (`sk_*`) with the `ADMIN` role.", "tags": [ "Integrations" ], "responses": { "200": { "description": "Webhook setup created or rotated" } } } }, "/v1/lead-sources/webhook/status": { "get": { "operationId": "getLeadWebhookSourceStatus", "summary": "Get lead-source webhook status", "description": "Returns the current webhook connection status, including connection identifier, endpoint URL, token last-4, last ingest time, and last error message. Returns 404 when the webhook has not been configured for the business.", "tags": [ "Integrations" ], "responses": { "200": { "description": "Current webhook connection status" }, "404": { "description": "Lead webhook has not been configured (code `CLAY_CONNECTOR_NOT_FOUND`)" } } } }, "/v1/lead-sources/webhook/leads": { "get": { "operationId": "listLeadWebhookLeads", "summary": "List webhook leads for desktop sync", "description": "Returns a cursor-paginated batch of normalized webhook leads ingested for the authenticated business. Use `cursor` and `limit` (1–500, default 500) to page through results. Returns 404 when the webhook has not been configured.", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor returned by a previous response." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of leads to return." } ], "responses": { "200": { "description": "Paginated list of ingested webhook leads" }, "404": { "description": "Lead webhook has not been configured (code `CLAY_CONNECTOR_NOT_FOUND`)" } } } }, "/v1/connectors/leads/{connectionId}/ingest": { "post": { "operationId": "ingestLeadWebhookLeads", "summary": "Ingest leads from a webhook", "description": "Public webhook ingest endpoint. Authenticate with the bearer token returned by the connect call (`Authorization: Bearer `). The request body must contain a `leads` array of up to 500 records per call. Returns 202 with counts of received, created, duplicate, and skipped leads.\n\nError codes: `CLAY_CONNECTOR_NOT_FOUND` (404), `CLAY_CONNECTOR_DISCONNECTED` (403), `CLAY_CONNECTOR_TOKEN_REQUIRED` (401), `CLAY_CONNECTOR_TOKEN_INVALID` (401), `CLAY_EMPTY_PAYLOAD` (422), `CLAY_BATCH_TOO_LARGE` (422).", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 128 }, "in": "path", "name": "connectionId", "required": true, "description": "Connection identifier returned by the connect call." } ], "responses": { "202": { "description": "Leads accepted for ingestion" } } } }, "/v1/lead-sources/clay/connect": { "post": { "operationId": "connectClayLeadSource", "summary": "Create or rotate Clay lead-source webhook setup", "description": "Clay-branded alias of `POST /v1/lead-sources/webhook/connect`. Behaves identically; prefer the generic `/lead-sources/webhook/connect` route for new integrations.", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/lead-sources/clay/status": { "get": { "operationId": "getClayLeadSourceStatus", "summary": "Get Clay lead-source webhook status", "description": "Clay-branded alias of `GET /v1/lead-sources/webhook/status`. Behaves identically; prefer the generic `/lead-sources/webhook/status` route for new integrations.", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/lead-sources/clay/leads": { "get": { "operationId": "listClayIngestedLeads", "summary": "List Clay-ingested leads for desktop sync", "description": "Clay-branded alias of `GET /v1/lead-sources/webhook/leads`. Behaves identically; prefer the generic `/lead-sources/webhook/leads` route for new integrations.", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Opaque pagination cursor returned by a previous response." }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of leads to return." } ], "responses": { "200": { "description": "Paginated list of ingested Clay leads" }, "404": { "description": "Lead webhook has not been configured (code `CLAY_CONNECTOR_NOT_FOUND`)" } } } }, "/v1/connectors/clay/{connectionId}/ingest": { "post": { "operationId": "ingestClayLeads", "summary": "Ingest leads from Clay webhook", "description": "Clay-branded alias of `POST /v1/connectors/leads/{connectionId}/ingest`. Behaves identically; prefer the generic `/connectors/leads/{connectionId}/ingest` route for new integrations.", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "connectionId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/salesforce/{id}/sync/accounts": { "post": { "operationId": "triggerSalesforceAccountSync", "summary": "Trigger a Salesforce Account → Drip Customer sync", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/salesforce/{id}/sync/opportunities": { "post": { "operationId": "triggerSalesforceOpportunitySync", "summary": "Trigger a Salesforce Opportunity → Drip Contract sync", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/salesforce/{id}/sync/rollup": { "post": { "operationId": "triggerSalesforceSpendRollupPush", "summary": "Push per-Account spend rollups to Salesforce", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/salesforce/{id}/backfill": { "post": { "operationId": "triggerSalesforceBackfill", "summary": "Run a full Salesforce Accounts + Opportunities backfill via Bulk API 2.0", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/salesforce/{id}/field-mappings": { "get": { "operationId": "listSalesforceFieldMappings", "summary": "List Salesforce field mappings for an integration", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "operationId": "createSalesforceFieldMapping", "summary": "Create a Salesforce field mapping", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/salesforce/{id}/field-mappings/{mappingId}": { "patch": { "operationId": "updateSalesforceFieldMapping", "summary": "Update a Salesforce field mapping", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "mappingId", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "deleteSalesforceFieldMapping", "summary": "Delete a Salesforce field mapping", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "mappingId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/xero/connect": { "post": { "operationId": "xeroConnect", "summary": "Start the Xero OAuth 2.0 PKCE flow", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/xero/callback": { "get": { "operationId": "xeroCallback", "summary": "Xero OAuth 2.0 callback", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/xero": { "get": { "operationId": "xeroList", "summary": "List Xero integrations", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "xeroDisconnect", "summary": "Disconnect the Xero integration", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/xero/tenants": { "get": { "operationId": "xeroListTenants", "summary": "List Xero tenants connected to the active integration", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/xero/test": { "post": { "operationId": "xeroTest", "summary": "Test the Xero connection", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/xero/accounts/map": { "post": { "operationId": "xeroUpsertAccountMappings", "summary": "Upsert Xero account-code mappings", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/xero/accounts": { "get": { "operationId": "xeroListAccounts", "summary": "List Xero chart of accounts for a tenant", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/xero/push/{exportId}": { "post": { "operationId": "xeroPushExport", "summary": "Push a GL export to Xero as ManualJournals", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "exportId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/quickbooks/connect": { "post": { "operationId": "quickBooksConnect", "summary": "Start the QuickBooks Online OAuth 2.0 PKCE flow", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/quickbooks/callback": { "get": { "operationId": "quickBooksCallback", "summary": "QuickBooks Online OAuth 2.0 callback", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/quickbooks": { "get": { "operationId": "quickBooksList", "summary": "List QuickBooks integrations", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "quickBooksDisconnect", "summary": "Disconnect the QuickBooks integration", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/quickbooks/test": { "post": { "operationId": "quickBooksTest", "summary": "Test the QuickBooks connection", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/quickbooks/accounts/map": { "post": { "operationId": "quickBooksUpsertAccountMappings", "summary": "Upsert QuickBooks account-code mappings", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/quickbooks/accounts": { "get": { "operationId": "quickBooksListAccounts", "summary": "List QuickBooks Online chart of accounts", "tags": [ "Integrations" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/quickbooks/push/{exportId}": { "post": { "operationId": "quickBooksPushExport", "summary": "Push a GL export to QuickBooks Online as JournalEntries", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "exportId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/quickbooks/config": { "patch": { "operationId": "quickBooksUpdateConfig", "summary": "Update QuickBooks integration settings (defaultItemId, autoPush)", "tags": [ "Integrations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultItemId": { "type": "string", "description": "QBO Item ID used for all invoice line items when pushing native invoices. Must be an existing active Item in your QBO company (e.g. a \"Services\" product)." }, "autoPush": { "type": "boolean", "description": "When true, GL exports are pushed to QBO automatically." }, "integrationId": { "type": "string" } } } } } }, "responses": { "200": { "description": "Default Response" } } } }, "/v1/integrations/quickbooks/push-invoice/{invoiceId}": { "post": { "operationId": "quickBooksPushInvoice", "summary": "Push a Drip invoice to QuickBooks Online as a native Invoice", "tags": [ "Integrations" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "invoiceId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/usage": { "post": { "operationId": "recordUsage", "summary": "Record usage and charge", "tags": [ "Usage" ], "description": "\nRecord a billable usage event and immediately charge the customer.\n\n> **Requires a secret key (`sk_*`) with at least the `OPERATOR` role.**\n\nThis endpoint waits for on-chain confirmation before returning, ensuring\nthe charge is settled. For faster responses, use `POST /v1/usage/async`.\n\n**x402 Payment Flow:**\nIf the customer has insufficient balance, returns 402 with payment headers.\nThe client can sign a payment with their session key and retry with\n`X-Payment-*` headers to complete the charge.\n\n**Idempotency:**\nInclude an `idempotencyKey` to safely retry requests without duplicate charges.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Drip customer ID (cus_*). One of customerId, externalCustomerId, or stripeCustomerId is required.", "example": "cus_abc123def456" }, "externalCustomerId": { "type": "string", "maxLength": 255, "description": "Your own database's customer ID. If no Drip customer exists yet for (business, externalCustomerId), one is auto-provisioned as an internal customer on first use.", "example": "user_42" }, "stripeCustomerId": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$", "maxLength": 255, "description": "Stripe customer ID (`cus_…`) from your connected Stripe account. If no Drip customer exists yet for (business, stripeCustomerId), one is auto-provisioned and usage is forwarded to Stripe's Billing Meter Events. Intended for merchants who just finished Stripe OAuth, so you can start sending usage against Stripe IDs immediately without waiting for the background customer import.", "example": "cus_NffrFeUfNV2Hib" }, "usageType": { "type": "string", "description": "Usage type matching a pricing plan (defaults to \"generic\" if omitted)", "example": "api_call", "default": "generic" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Quantity of usage (defaults to 1 if omitted)", "example": 100, "default": 1 }, "units": { "type": "string", "maxLength": 50, "description": "Human-readable unit label for display (e.g., \"tokens\", \"API calls\", \"seconds\")", "example": "API calls" }, "description": { "type": "string", "maxLength": 500, "description": "Human-readable description for support/finance teams (e.g., \"Chat completion for Customer XYZ\")", "example": "Eligibility check for Pharmacy ABC (workflow: insurance_verify)" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique key to prevent duplicate charges. Required. Use a stable identifier like `{customerId}_{action}_{timestamp}` so retries produce the same key.", "example": "req_20240115_abc123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata", "example": { "endpoint": "/v1/chat", "model": "gpt-4" } }, "workflowId": { "type": "string", "description": "Link this usage to a workflow" }, "runId": { "type": "string", "description": "Link this usage to an agent run" }, "eventType": { "type": "string", "enum": [ "USAGE", "INFERENCE", "TOOL_CALL", "DELEGATION", "RETRIEVAL", "CUSTOM" ], "description": "Classify the type of usage event" }, "actionName": { "type": "string", "maxLength": 255, "description": "Name of the action performed (e.g., \"chat_completion\", \"image_generation\")" }, "outcome": { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "PENDING", "SKIPPED", "CANCELLED" ], "description": "Outcome of the action" }, "explanation": { "type": "string", "maxLength": 1000, "description": "Human-readable explanation of what happened" }, "parentEventId": { "type": "string", "description": "ID of the parent event (for building causality trees)" }, "retryOfEventId": { "type": "string", "description": "ID of the event this is retrying (for retry chain tracking)" }, "attemptNumber": { "type": "integer", "minimum": 1, "description": "Attempt number (1 = first try, 2 = first retry, etc.)" }, "inputHash": { "type": "string", "maxLength": 64, "description": "SHA-256 hash of the input for verification" }, "outputHash": { "type": "string", "maxLength": 64, "description": "SHA-256 hash of the output for verification" }, "input": { "type": "object", "additionalProperties": true, "description": "Raw input data (will be hashed for verification)" }, "output": { "type": "object", "additionalProperties": true, "description": "Raw output data (will be hashed for verification)" } }, "required": [ "idempotencyKey" ] } } } }, "responses": { "201": { "description": "Usage recorded. Either an on-chain charge was created (charge object populated) or the customer has no on-chain address and the request was auto-promoted to internal/visibility mode (charge=null, mode=internal).", "content": { "application/json": { "schema": { "description": "Usage recorded. Either an on-chain charge was created (charge object populated) or the customer has no on-chain address and the request was auto-promoted to internal/visibility mode (charge=null, mode=internal).", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "usageEventId": { "type": "string", "description": "Usage event ID" }, "isDuplicate": { "type": "boolean", "description": "True if this was a duplicate request matched by idempotencyKey", "example": false }, "charge": { "type": "object", "nullable": true, "description": "Populated when the customer has an on-chain address and a charge was created. `null` when the request was recorded as internal/visibility usage (no billing).", "properties": { "id": { "type": "string", "description": "Charge ID" }, "amountUsdc": { "type": "string", "description": "Charge amount in USDC" }, "amountToken": { "type": "string", "description": "Charge amount in token units" }, "txHash": { "type": "string", "nullable": true, "description": "Transaction hash" }, "status": { "type": "string", "enum": [ "PENDING", "PENDING_SETTLEMENT", "CONFIRMED" ] } } }, "mode": { "type": "string", "enum": [ "internal" ], "nullable": true, "description": "Present when the request was recorded as internal/visibility usage." }, "autoPromoted": { "type": "boolean", "nullable": true, "description": "True when /usage auto-promoted to /usage/internal because the customer has no on-chain address. Explicit internal customers get mode=internal with autoPromoted=false." }, "reason": { "type": "string", "nullable": true, "description": "Human-readable explanation of why the request was routed to the internal path." }, "x402": { "type": "object", "nullable": true, "description": "Present if payment was via x402 flow", "properties": { "paymentVerified": { "type": "boolean" }, "sessionKeyId": { "type": "string" } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "402": { "description": "Payment required - insufficient balance. Includes x402 payment details for automatic payment flow.", "content": { "application/json": { "schema": { "description": "Payment required - insufficient balance. Includes x402 payment details for automatic payment flow.", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "PAYMENT_REQUIRED" }, "payment": { "type": "object", "description": "Payment details for x402 flow. Sign with session key and retry with X-Payment-* headers.", "properties": { "amount": { "type": "string", "description": "Amount required in USDC" }, "recipient": { "type": "string", "description": "Payment recipient address" }, "currency": { "type": "string", "example": "USDC" }, "chain": { "type": "string", "example": "base-sepolia" }, "description": { "type": "string", "description": "Human-readable charge description" }, "usageId": { "type": "string", "description": "Unique usage identifier" }, "expiresAt": { "type": "integer", "description": "Unix timestamp (seconds) when payment expires" }, "timestamp": { "type": "integer", "description": "Unix timestamp (seconds) when request was created" }, "nonce": { "type": "string", "description": "Unique nonce for replay protection" } } }, "x402": { "type": "object", "description": "Full x402 protocol payload for client signing", "properties": { "version": { "type": "string", "example": "1.0.0" }, "paymentRequest": { "type": "object", "description": "Complete payment request to sign via EIP-712" } } }, "serverTime": { "type": "object", "description": "Server time for client clock synchronization", "properties": { "seconds": { "type": "integer" }, "milliseconds": { "type": "integer" }, "iso": { "type": "string", "format": "date-time" } } }, "checkout_url": { "type": "string", "nullable": true, "description": "URL for balance top-up" } } } } } }, "403": { "description": "Account paused — usage blocked until balance is restored", "content": { "application/json": { "schema": { "description": "Account paused — usage blocked until balance is restored", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer or pricing plan not found", "content": { "application/json": { "schema": { "description": "Customer or pricing plan not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.", "content": { "application/json": { "schema": { "description": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Billing temporarily paused or dependency unavailable", "content": { "application/json": { "schema": { "description": "Billing temporarily paused or dependency unavailable", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "get": { "operationId": "listUsageEvents", "summary": "List usage events", "tags": [ "Usage" ], "description": "Retrieve recent usage events for your business, including associated charges.", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of events to return" }, { "schema": { "type": "string" }, "in": "query", "name": "customerId", "required": false, "description": "Filter by customer ID" } ], "responses": { "200": { "description": "List of usage events", "content": { "application/json": { "schema": { "description": "List of usage events", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "onchainAddress": { "type": "string" }, "externalCustomerId": { "type": "string", "nullable": true } } }, "usageType": { "type": "string" }, "quantity": { "type": "string" }, "description": { "type": "string", "nullable": true, "description": "Human-readable description of the usage event" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" }, "charge": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "amountUsdc": { "type": "string" }, "txHash": { "type": "string", "nullable": true }, "status": { "type": "string" } } } } } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/usage/async": { "post": { "operationId": "recordUsageAsync", "summary": "Record usage (async)", "tags": [ "Usage" ], "description": "\nRecord a billable usage event and return immediately without waiting for settlement.\n\n> **Requires a secret key (`sk_*`) with at least the `OPERATOR` role.**\n\nThe charge will be processed in the background. Subscribe to webhooks\n(`charge.succeeded`, `charge.failed`) to get notified of the final status.\n\nUse this endpoint when you need fast response times and can handle\neventual consistency via webhooks.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Drip customer ID (cus_*). One of customerId, externalCustomerId, or stripeCustomerId is required.", "example": "cus_abc123def456" }, "externalCustomerId": { "type": "string", "maxLength": 255, "description": "Your own database's customer ID. If no Drip customer exists yet for (business, externalCustomerId), one is auto-provisioned as an internal customer on first use.", "example": "user_42" }, "stripeCustomerId": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$", "maxLength": 255, "description": "Stripe customer ID (`cus_…`) from your connected Stripe account. If no Drip customer exists yet for (business, stripeCustomerId), one is auto-provisioned and usage is forwarded to Stripe's Billing Meter Events. Intended for merchants who just finished Stripe OAuth, so you can start sending usage against Stripe IDs immediately without waiting for the background customer import.", "example": "cus_NffrFeUfNV2Hib" }, "usageType": { "type": "string", "description": "Usage type matching a pricing plan (defaults to \"generic\" if omitted)", "example": "api_call", "default": "generic" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Quantity of usage (defaults to 1 if omitted)", "example": 100, "default": 1 }, "units": { "type": "string", "maxLength": 50, "description": "Human-readable unit label for display (e.g., \"tokens\", \"API calls\", \"seconds\")", "example": "API calls" }, "description": { "type": "string", "maxLength": 500, "description": "Human-readable description for support/finance teams (e.g., \"Chat completion for Customer XYZ\")", "example": "Eligibility check for Pharmacy ABC (workflow: insurance_verify)" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique key to prevent duplicate charges. Required. Use a stable identifier like `{customerId}_{action}_{timestamp}` so retries produce the same key.", "example": "req_20240115_abc123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata", "example": { "endpoint": "/v1/chat", "model": "gpt-4" } }, "workflowId": { "type": "string", "description": "Link this usage to a workflow" }, "runId": { "type": "string", "description": "Link this usage to an agent run" }, "eventType": { "type": "string", "enum": [ "USAGE", "INFERENCE", "TOOL_CALL", "DELEGATION", "RETRIEVAL", "CUSTOM" ], "description": "Classify the type of usage event" }, "actionName": { "type": "string", "maxLength": 255, "description": "Name of the action performed (e.g., \"chat_completion\", \"image_generation\")" }, "outcome": { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "PENDING", "SKIPPED", "CANCELLED" ], "description": "Outcome of the action" }, "explanation": { "type": "string", "maxLength": 1000, "description": "Human-readable explanation of what happened" }, "parentEventId": { "type": "string", "description": "ID of the parent event (for building causality trees)" }, "retryOfEventId": { "type": "string", "description": "ID of the event this is retrying (for retry chain tracking)" }, "attemptNumber": { "type": "integer", "minimum": 1, "description": "Attempt number (1 = first try, 2 = first retry, etc.)" }, "inputHash": { "type": "string", "maxLength": 64, "description": "SHA-256 hash of the input for verification" }, "outputHash": { "type": "string", "maxLength": 64, "description": "SHA-256 hash of the output for verification" }, "input": { "type": "object", "additionalProperties": true, "description": "Raw input data (will be hashed for verification)" }, "output": { "type": "object", "additionalProperties": true, "description": "Raw output data (will be hashed for verification)" } }, "required": [ "idempotencyKey" ] } } } }, "responses": { "202": { "description": "Usage recorded, charge queued", "content": { "application/json": { "schema": { "description": "Usage recorded, charge queued", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "usageEventId": { "type": "string", "description": "Usage event ID" }, "isDuplicate": { "type": "boolean", "description": "True if this was a duplicate request matched by idempotencyKey", "example": false }, "charge": { "type": "object", "properties": { "id": { "type": "string", "description": "Charge ID" }, "amountUsdc": { "type": "string", "description": "Charge amount in USDC" }, "status": { "type": "string", "enum": [ "PENDING", "CONFIRMED" ], "example": "PENDING" }, "estimatedConfirmationTime": { "type": "string", "nullable": true, "description": "Human-readable estimate of when the charge will be confirmed (e.g. \"~15 seconds\", \"already confirmed\")" } } }, "message": { "type": "string", "example": "Charge queued for processing. Subscribe to webhooks for status updates." } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Account paused — usage blocked until balance is restored", "content": { "application/json": { "schema": { "description": "Account paused — usage blocked until balance is restored", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer or pricing plan not found", "content": { "application/json": { "schema": { "description": "Customer or pricing plan not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.", "content": { "application/json": { "schema": { "description": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Billing temporarily paused or dependency unavailable", "content": { "application/json": { "schema": { "description": "Billing temporarily paused or dependency unavailable", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/usage/internal": { "post": { "operationId": "recordInternalUsage", "summary": "Record internal usage (no billing)", "tags": [ "Usage" ], "description": "\nRecord a usage event for internal visibility tracking only. No billing or charges are created.\n\n> **Requires a secret key (`sk_*`) with at least the `OPERATOR` role.**\n\n**Use cases:**\n- Track internal team usage without charging\n- Pilot programs where you want visibility before billing\n- Usage tracking before customer has on-chain wallet setup\n\nThis endpoint:\n- Does NOT create a Charge record\n- Does NOT require customer balance\n- Does NOT require blockchain/wallet setup for internal customers\n- Works with both internal and regular customers\n\nFor billing customers, use `POST /v1/usage` or `POST /v1/usage/async` instead.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Drip customer ID (cus_*). One of customerId, externalCustomerId, or stripeCustomerId is required.", "example": "cus_abc123def456" }, "externalCustomerId": { "type": "string", "maxLength": 255, "description": "Your own database's customer ID. If no Drip customer exists yet for (business, externalCustomerId), one is auto-provisioned as an internal customer on first use.", "example": "user_42" }, "stripeCustomerId": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$", "maxLength": 255, "description": "Stripe customer ID (`cus_…`) from your connected Stripe account. If no Drip customer exists yet for (business, stripeCustomerId), one is auto-provisioned and usage is forwarded to Stripe's Billing Meter Events. Intended for merchants who just finished Stripe OAuth, so you can start sending usage against Stripe IDs immediately without waiting for the background customer import.", "example": "cus_NffrFeUfNV2Hib" }, "usageType": { "type": "string", "description": "Usage type matching a pricing plan (defaults to \"generic\" if omitted)", "example": "api_call", "default": "generic" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Quantity of usage (defaults to 1 if omitted)", "example": 100, "default": 1 }, "units": { "type": "string", "maxLength": 50, "description": "Human-readable unit label for display (e.g., \"tokens\", \"API calls\", \"seconds\")", "example": "API calls" }, "description": { "type": "string", "maxLength": 500, "description": "Human-readable description for support/finance teams (e.g., \"Chat completion for Customer XYZ\")", "example": "Eligibility check for Pharmacy ABC (workflow: insurance_verify)" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique key to prevent duplicate charges. Required. Use a stable identifier like `{customerId}_{action}_{timestamp}` so retries produce the same key.", "example": "req_20240115_abc123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata", "example": { "endpoint": "/v1/chat", "model": "gpt-4" } }, "workflowId": { "type": "string", "description": "Link this usage to a workflow" }, "runId": { "type": "string", "description": "Link this usage to an agent run" }, "eventType": { "type": "string", "enum": [ "USAGE", "INFERENCE", "TOOL_CALL", "DELEGATION", "RETRIEVAL", "CUSTOM" ], "description": "Classify the type of usage event" }, "actionName": { "type": "string", "maxLength": 255, "description": "Name of the action performed (e.g., \"chat_completion\", \"image_generation\")" }, "outcome": { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "PENDING", "SKIPPED", "CANCELLED" ], "description": "Outcome of the action" }, "explanation": { "type": "string", "maxLength": 1000, "description": "Human-readable explanation of what happened" }, "parentEventId": { "type": "string", "description": "ID of the parent event (for building causality trees)" }, "retryOfEventId": { "type": "string", "description": "ID of the event this is retrying (for retry chain tracking)" }, "attemptNumber": { "type": "integer", "minimum": 1, "description": "Attempt number (1 = first try, 2 = first retry, etc.)" }, "inputHash": { "type": "string", "maxLength": 64, "description": "SHA-256 hash of the input for verification" }, "outputHash": { "type": "string", "maxLength": 64, "description": "SHA-256 hash of the output for verification" }, "input": { "type": "object", "additionalProperties": true, "description": "Raw input data (will be hashed for verification)" }, "output": { "type": "object", "additionalProperties": true, "description": "Raw output data (will be hashed for verification)" } }, "required": [ "idempotencyKey" ] } } } }, "responses": { "201": { "description": "Internal usage recorded", "content": { "application/json": { "schema": { "description": "Internal usage recorded", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "usageEventId": { "type": "string", "description": "Usage event ID" }, "customerId": { "type": "string", "description": "Customer ID" }, "usageType": { "type": "string", "description": "Type of usage" }, "quantity": { "type": "number", "description": "Quantity recorded" }, "units": { "type": "string", "nullable": true, "description": "Human-readable unit label" }, "description": { "type": "string", "nullable": true, "description": "Human-readable event description" }, "isInternal": { "type": "boolean", "description": "Whether customer is internal-only" }, "message": { "type": "string", "example": "Usage recorded for internal visibility (no charge created)" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.", "content": { "application/json": { "schema": { "description": "Rate limit exceeded. Retry after the duration specified in the Retry-After header.", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Billing temporarily paused or dependency unavailable", "content": { "application/json": { "schema": { "description": "Billing temporarily paused or dependency unavailable", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/usage/internal/batch": { "post": { "operationId": "recordInternalUsageBatch", "summary": "Record internal usage (batched, high throughput)", "tags": [ "Usage" ], "description": "\nBatch-optimized variant of `POST /v1/usage/internal`.\n\nEvents are buffered in memory and flushed to the database every ~2 seconds\nusing a single bulk INSERT. This reduces per-event DB overhead by ~99% and\nis designed for customers sending 1M+ events/day.\n\nReturns 202 immediately. The event will be persisted within 2 seconds.\nIdempotency is still enforced via `idempotencyKey` — duplicates are\nsilently skipped during the bulk insert.\n\n> **Requires a secret key (`sk_*`) with at least the `OPERATOR` role.**\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Drip customer ID (cus_*). One of customerId, externalCustomerId, or stripeCustomerId is required.", "example": "cus_abc123def456" }, "externalCustomerId": { "type": "string", "maxLength": 255, "description": "Your own database's customer ID. If no Drip customer exists yet for (business, externalCustomerId), one is auto-provisioned as an internal customer on first use.", "example": "user_42" }, "stripeCustomerId": { "type": "string", "pattern": "^cus_[A-Za-z0-9]+$", "maxLength": 255, "description": "Stripe customer ID (`cus_…`) from your connected Stripe account. If no Drip customer exists yet for (business, stripeCustomerId), one is auto-provisioned and usage is forwarded to Stripe's Billing Meter Events. Intended for merchants who just finished Stripe OAuth, so you can start sending usage against Stripe IDs immediately without waiting for the background customer import.", "example": "cus_NffrFeUfNV2Hib" }, "usageType": { "type": "string", "description": "Usage type matching a pricing plan (defaults to \"generic\" if omitted)", "example": "api_call", "default": "generic" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Quantity of usage (defaults to 1 if omitted)", "example": 100, "default": 1 }, "units": { "type": "string", "maxLength": 50, "description": "Human-readable unit label for display (e.g., \"tokens\", \"API calls\", \"seconds\")", "example": "API calls" }, "description": { "type": "string", "maxLength": 500, "description": "Human-readable description for support/finance teams (e.g., \"Chat completion for Customer XYZ\")", "example": "Eligibility check for Pharmacy ABC (workflow: insurance_verify)" }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Unique key to prevent duplicate charges. Required. Use a stable identifier like `{customerId}_{action}_{timestamp}` so retries produce the same key.", "example": "req_20240115_abc123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata", "example": { "endpoint": "/v1/chat", "model": "gpt-4" } }, "workflowId": { "type": "string", "description": "Link this usage to a workflow" }, "runId": { "type": "string", "description": "Link this usage to an agent run" }, "eventType": { "type": "string", "enum": [ "USAGE", "INFERENCE", "TOOL_CALL", "DELEGATION", "RETRIEVAL", "CUSTOM" ], "description": "Classify the type of usage event" }, "actionName": { "type": "string", "maxLength": 255, "description": "Name of the action performed (e.g., \"chat_completion\", \"image_generation\")" }, "outcome": { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "PENDING", "SKIPPED", "CANCELLED" ], "description": "Outcome of the action" }, "explanation": { "type": "string", "maxLength": 1000, "description": "Human-readable explanation of what happened" }, "parentEventId": { "type": "string", "description": "ID of the parent event (for building causality trees)" }, "retryOfEventId": { "type": "string", "description": "ID of the event this is retrying (for retry chain tracking)" }, "attemptNumber": { "type": "integer", "minimum": 1, "description": "Attempt number (1 = first try, 2 = first retry, etc.)" }, "inputHash": { "type": "string", "maxLength": 64, "description": "SHA-256 hash of the input for verification" }, "outputHash": { "type": "string", "maxLength": 64, "description": "SHA-256 hash of the output for verification" }, "input": { "type": "object", "additionalProperties": true, "description": "Raw input data (will be hashed for verification)" }, "output": { "type": "object", "additionalProperties": true, "description": "Raw output data (will be hashed for verification)" } }, "required": [ "idempotencyKey" ] } } } }, "responses": { "202": { "description": "Usage accepted for batched insert", "content": { "application/json": { "schema": { "description": "Usage accepted for batched insert", "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "customerId": { "type": "string" }, "usageType": { "type": "string" }, "quantity": { "type": "number" }, "idempotencyKey": { "type": "string" }, "pendingEvents": { "type": "integer", "description": "Number of events waiting to be flushed" }, "message": { "type": "string", "example": "Event queued for batched insert (~2s)" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/usage/quota": { "get": { "operationId": "getUsageQuota", "summary": "Get current-month event usage vs plan quota (API-key auth)", "tags": [ "Usage" ], "description": "Safe to poll every few seconds — the underlying count is cached 30s per business. Response includes `resetAt` (ISO) and `overagePerEventUsd`; use `exceeded` as the gate signal.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/balance": { "get": { "operationId": "getCustomerBalance", "summary": "Get customer balance", "tags": [ "Customers" ], "description": "\nRetrieve the current balance for a customer. Returns the latest cached\nbalance from the database (synced periodically from on-chain).\n\nFor real-time balance, call `POST /v1/customers/:id/sync-balance` first.\n ", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Customer ID" } ], "responses": { "200": { "description": "Customer balance", "content": { "application/json": { "schema": { "description": "Customer balance", "type": "object", "properties": { "customerId": { "type": "string" }, "onchainAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "balanceUsdc": { "type": "string", "description": "Available USDC balance" }, "pendingChargesUsdc": { "type": "string", "description": "USDC in pending charges" }, "availableUsdc": { "type": "string", "description": "Balance minus pending charges" }, "lastSyncedAt": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/charges": { "get": { "operationId": "listCharges", "summary": "List charges", "tags": [ "Charges" ], "description": "Retrieve all charges for your business, sorted by creation date (newest first).", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum number of charges to return" }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false, "description": "Number of charges to skip (for pagination)" }, { "schema": { "type": "string", "enum": [ "PENDING", "PENDING_SETTLEMENT", "CONFIRMED", "FAILED", "REFUNDED", "REFUND_PENDING" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by status" }, { "schema": { "type": "string" }, "in": "query", "name": "customerId", "required": false, "description": "Filter by customer ID" } ], "responses": { "200": { "description": "List of charges", "content": { "application/json": { "schema": { "description": "List of charges", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique charge identifier", "example": "chg_abc123def456" }, "usageId": { "type": "string", "description": "Associated usage event ID", "example": "usg_xyz789" }, "customerId": { "type": "string", "description": "Customer ID", "example": "cus_abc123" }, "customer": { "type": "object", "description": "Customer details", "properties": { "id": { "type": "string", "example": "cus_abc123" }, "onchainAddress": { "type": "string", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f00000" }, "externalCustomerId": { "type": "string", "nullable": true, "example": "user_123" } } }, "usageEvent": { "type": "object", "description": "Usage event that triggered this charge", "properties": { "id": { "type": "string", "example": "usg_xyz789" }, "type": { "type": "string", "description": "Usage type", "example": "api_call" }, "quantity": { "type": "string", "description": "Quantity consumed", "example": "100" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "example": { "endpoint": "/v1/chat" } } } }, "amountUsdc": { "type": "string", "description": "Amount charged in USDC", "example": "0.100000" }, "amountToken": { "type": "string", "description": "Amount in token units (6 decimals)", "example": "100000" }, "txHash": { "type": "string", "nullable": true, "description": "On-chain transaction hash", "example": "0x1234567890abcdef..." }, "blockNumber": { "type": "string", "nullable": true, "description": "Block number when confirmed", "example": "12345678" }, "status": { "type": "string", "enum": [ "PENDING", "PENDING_SETTLEMENT", "CONFIRMED", "FAILED", "REFUNDED", "REFUND_PENDING" ], "description": "Current charge status", "example": "CONFIRMED" }, "failureReason": { "type": "string", "nullable": true, "description": "Reason if charge failed" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the charge was created", "example": "2024-01-15T10:30:00.000Z" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the charge was confirmed on-chain", "example": "2024-01-15T10:30:05.000Z" } } } }, "count": { "type": "integer", "description": "Total number of charges returned", "example": 42 } } } } } }, "400": { "description": "Invalid parameter", "content": { "application/json": { "schema": { "description": "Invalid parameter", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden (secret key required)", "content": { "application/json": { "schema": { "description": "Forbidden (secret key required)", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "description": "Service temporarily unavailable", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/charges/{id}": { "get": { "operationId": "getCharge", "summary": "Get a charge", "tags": [ "Charges" ], "description": "Retrieve details for a specific charge by ID.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Charge ID" } ], "responses": { "200": { "description": "Charge details", "content": { "application/json": { "schema": { "description": "Charge details", "type": "object", "properties": { "id": { "type": "string", "description": "Unique charge identifier", "example": "chg_abc123def456" }, "customerId": { "type": "string", "description": "Customer ID", "example": "cus_abc123" }, "customer": { "type": "object", "description": "Customer who was charged", "properties": { "id": { "type": "string", "example": "cus_abc123" }, "onchainAddress": { "type": "string", "description": "Smart account address", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f00000" }, "externalCustomerId": { "type": "string", "nullable": true, "description": "Your system customer ID", "example": "user_123" } } }, "usageId": { "type": "string", "description": "Associated usage event ID", "example": "usg_xyz789" }, "usageEvent": { "type": "object", "description": "Usage event that triggered this charge", "properties": { "id": { "type": "string", "example": "usg_xyz789" }, "type": { "type": "string", "description": "Usage type from pricing plan", "example": "api_call" }, "quantity": { "type": "string", "description": "Quantity consumed", "example": "100" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Custom metadata attached to usage event", "example": { "endpoint": "/v1/chat", "model": "gpt-4" } }, "createdAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" } } }, "amountUsdc": { "type": "string", "description": "Amount charged in USDC", "example": "0.100000" }, "amountToken": { "type": "string", "description": "Amount in token units (6 decimals)", "example": "100000" }, "txHash": { "type": "string", "nullable": true, "description": "On-chain transaction hash when confirmed", "example": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" }, "blockNumber": { "type": "string", "nullable": true, "description": "Block number when charge was confirmed", "example": "12345678" }, "status": { "type": "string", "enum": [ "PENDING", "PENDING_SETTLEMENT", "CONFIRMED", "FAILED", "REFUNDED", "REFUND_PENDING" ], "description": "Current charge status: PENDING (processing), PENDING_SETTLEMENT (in batch), CONFIRMED (settled), FAILED (error), REFUNDED (returned)", "example": "CONFIRMED" }, "failureReason": { "type": "string", "nullable": true, "description": "Error message if charge failed", "example": null }, "createdAt": { "type": "string", "format": "date-time", "description": "When the charge was created", "example": "2024-01-15T10:30:00.000Z" }, "confirmedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the charge was confirmed on-chain", "example": "2024-01-15T10:30:05.000Z" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden (secret key required)", "content": { "application/json": { "schema": { "description": "Forbidden (secret key required)", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Charge not found", "content": { "application/json": { "schema": { "description": "Charge not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/charges/export": { "get": { "operationId": "exportCharges", "summary": "Export charges", "tags": [ "Charges" ], "description": "\nExport all charges for your business in JSON or CSV format.\n\nCSV format is useful for importing into spreadsheets or accounting software.\n ", "parameters": [ { "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" }, "in": "query", "name": "format", "required": false, "description": "Export format" } ], "responses": { "200": { "description": "Exported charges (JSON or CSV)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" } } } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden (secret key required)", "content": { "application/json": { "schema": { "description": "Forbidden (secret key required)", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/charges/{id}/refund": { "post": { "operationId": "refundCharge", "summary": "Refund a charge", "tags": [ "Charges" ], "description": "\nRefund a charge back to the customer. Only escrow-based charges can be refunded,\nand only before the escrow has been settled or expired.\n\n**Refund reasons:**\n- `customer_request` - Customer requested a refund\n- `merchant_error` - Charge was made in error\n- `fraud_reversal` - Fraudulent transaction reversal\n\nThe refund is processed on-chain and the funds are returned to the customer's account.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "customer_request", "merchant_error", "fraud_reversal" ], "description": "Reason for the refund" }, "note": { "type": "string", "maxLength": 1000, "description": "Optional internal note about the refund" } }, "required": [ "reason" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Charge ID" } ], "responses": { "200": { "description": "Charge refunded successfully", "content": { "application/json": { "schema": { "description": "Charge refunded successfully", "type": "object", "properties": { "id": { "type": "string", "description": "Charge ID" }, "customerId": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "onchainAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Ethereum address (checksummed or lowercase)" }, "externalCustomerId": { "type": "string", "nullable": true } } }, "usageId": { "type": "string" }, "amountUsdc": { "type": "string", "pattern": "^\\d+\\.\\d{1,6}$", "description": "USDC amount with up to 6 decimal places" }, "amountToken": { "type": "string" }, "status": { "type": "string", "enum": [ "REFUNDED", "REFUND_PENDING" ], "description": "REFUNDED when on-chain confirmation succeeded, REFUND_PENDING when tx submitted but confirmation failed" }, "refundReason": { "type": "string", "enum": [ "customer_request", "merchant_error", "fraud_reversal" ] }, "refundNote": { "type": "string", "nullable": true }, "refundTxHash": { "type": "string", "description": "Transaction hash for the refund" }, "refundedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Set when refund is confirmed on-chain; null when REFUND_PENDING" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "customerId", "amountUsdc", "status", "refundReason", "refundTxHash" ] } } } }, "400": { "description": "Refund not allowed", "content": { "application/json": { "schema": { "description": "Refund not allowed", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "NO_ESCROW", "ALREADY_REFUNDED", "ESCROW_ALREADY_SETTLED", "ESCROW_EXPIRED" ] } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "403": { "description": "Forbidden (secret key required)", "content": { "application/json": { "schema": { "description": "Forbidden (secret key required)", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Charge not found", "content": { "application/json": { "schema": { "description": "Charge not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "500": { "description": "Blockchain error", "content": { "application/json": { "schema": { "description": "Blockchain error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Lock unavailable", "content": { "application/json": { "schema": { "description": "Lock unavailable", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/workflows": { "post": { "operationId": "createWorkflow", "summary": "Create a workflow", "tags": [ "Workflows" ], "description": "Create a new workflow definition for tracking agent runs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body for creating a new workflow.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable name for the workflow (required)" }, "slug": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-z0-9_-]+$", "description": "URL-safe identifier - must be lowercase alphanumeric with underscores or hyphens (required)" }, "productSurface": { "type": "string", "enum": [ "API", "RPC", "WEBHOOK", "AGENT", "PIPELINE", "CUSTOM" ], "description": "Product category for dashboard grouping. Use API for REST APIs, RPC for blockchain calls, WEBHOOK for webhooks, AGENT for AI agents, PIPELINE for data pipelines, CUSTOM for other use cases.", "default": "CUSTOM" }, "chain": { "type": "string", "enum": [ "ETHEREUM", "SOLANA", "POLYGON", "ARBITRUM", "OPTIMISM", "BASE", "AVALANCHE", "BSC" ], "description": "Blockchain network (optional, for RPC workflows only)" }, "description": { "type": "string", "maxLength": 1000, "description": "Optional description of what this workflow does" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata for custom tracking" } }, "required": [ "name", "slug" ] } } }, "description": "Request body for creating a new workflow." }, "responses": { "201": { "description": "Workflow created", "content": { "application/json": { "schema": { "description": "Workflow created", "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the workflow" }, "name": { "type": "string", "description": "Human-readable name for the workflow" }, "slug": { "type": "string", "description": "URL-safe identifier (lowercase, alphanumeric, hyphens, underscores)" }, "productSurface": { "type": "string", "enum": [ "API", "RPC", "WEBHOOK", "AGENT", "PIPELINE", "CUSTOM" ], "description": "Product category for dashboard grouping. API = REST API calls, RPC = Blockchain RPC calls, WEBHOOK = Webhook deliveries, AGENT = AI agent executions, PIPELINE = Data pipelines, CUSTOM = Custom workflows" }, "chain": { "type": "string", "enum": [ "ETHEREUM", "SOLANA", "POLYGON", "ARBITRUM", "OPTIMISM", "BASE", "AVALANCHE", "BSC" ], "nullable": true, "description": "Blockchain network for RPC workflows (optional)" }, "description": { "type": "string", "nullable": true, "description": "Optional description of what this workflow does" }, "metadata": { "type": "object", "additionalProperties": true, "nullable": true, "description": "Optional metadata for custom tracking" }, "isActive": { "type": "boolean", "description": "Whether this workflow is currently active" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the workflow was created" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the workflow was last updated" } }, "required": [ "id", "name", "slug", "productSurface", "isActive" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "409": { "description": "Workflow with this slug already exists", "content": { "application/json": { "schema": { "description": "Workflow with this slug already exists", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "get": { "operationId": "listWorkflows", "summary": "List workflows", "tags": [ "Workflows" ], "description": "List all workflows for your business.", "parameters": [ { "schema": { "type": "string", "enum": [ "API", "RPC", "WEBHOOK", "AGENT", "PIPELINE", "CUSTOM" ] }, "in": "query", "name": "productSurface", "required": false }, { "schema": { "type": "boolean" }, "in": "query", "name": "isActive", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "List of workflows", "content": { "application/json": { "schema": { "description": "List of workflows", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "productSurface": { "type": "string" }, "description": { "type": "string", "nullable": true }, "isActive": { "type": "boolean" }, "runCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/workflows/{id}": { "get": { "operationId": "getWorkflow", "summary": "Get workflow", "tags": [ "Workflows" ], "description": "Get a workflow by ID with usage statistics.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Workflow details", "content": { "application/json": { "schema": { "description": "Workflow details", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "productSurface": { "type": "string" }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "isActive": { "type": "boolean" }, "stats": { "type": "object", "properties": { "totalRuns": { "type": "integer" }, "completedRuns": { "type": "integer" }, "failedRuns": { "type": "integer" }, "totalEvents": { "type": "integer" }, "totalCostUnits": { "type": "string" } } }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "description": "Workflow not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "patch": { "operationId": "updateWorkflow", "summary": "Update workflow", "tags": [ "Workflows" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Workflow updated", "content": { "application/json": { "schema": { "description": "Workflow updated" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Workflow not found", "content": { "application/json": { "schema": { "description": "Workflow not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/runs": { "post": { "operationId": "startRun", "summary": "Start a new agent run", "tags": [ "Runs" ], "description": "\nStart tracking a new agent run for a customer workflow.\n\nReturns a run ID that can be used to emit events and track execution.\nThe run starts in PENDING status and transitions to RUNNING when the first event is emitted.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customerId", "workflowId" ], "properties": { "customerId": { "type": "string", "description": "Customer ID (must exist)", "example": "cus_abc123" }, "workflowId": { "type": "string", "description": "Workflow ID (must exist)", "example": "wf_abc123" }, "externalRunId": { "type": "string", "maxLength": 255, "description": "Your system run ID (must be unique per business)" }, "correlationId": { "type": "string", "maxLength": 255, "description": "Cross-service tracing ID for linking runs across services" }, "parentRunId": { "type": "string", "description": "Parent run ID for nested/sub-runs" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Arbitrary metadata to attach to the run" } } } } } }, "responses": { "201": { "description": "Run started", "content": { "application/json": { "schema": { "description": "Run started", "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "workflowId": { "type": "string" }, "workflowName": { "type": "string" }, "status": { "type": "string" }, "correlationId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer or workflow not found", "content": { "application/json": { "schema": { "description": "Customer or workflow not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "409": { "description": "Run with externalRunId already exists", "content": { "application/json": { "schema": { "description": "Run with externalRunId already exists", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Service temporarily unavailable", "content": { "application/json": { "schema": { "description": "Service temporarily unavailable", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "get": { "operationId": "listRuns", "summary": "List runs", "tags": [ "Runs" ], "description": "List agent runs with optional filters.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "customerId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "workflowId", "required": false }, { "schema": { "type": "string", "enum": [ "PENDING", "RUNNING", "COMPLETED", "FAILED", "CANCELLED", "TIMEOUT" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false } ], "responses": { "200": { "description": "List of runs", "content": { "application/json": { "schema": { "description": "List of runs", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "customerName": { "type": "string", "nullable": true }, "workflowId": { "type": "string" }, "workflowName": { "type": "string" }, "workflowSurface": { "type": "string", "nullable": true }, "workflowChain": { "type": "string", "nullable": true }, "status": { "type": "string" }, "eventCount": { "type": "integer" }, "totalCostUnits": { "type": "string", "nullable": true }, "durationMs": { "type": "integer", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "endedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "errorMessage": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true } } } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/runs/{id}": { "patch": { "operationId": "updateRun", "summary": "Update or end a run", "tags": [ "Runs" ], "description": "\nUpdate a run's status or end it.\n\nWhen transitioning to COMPLETED, FAILED, CANCELLED, or TIMEOUT, the run's\nendedAt timestamp is automatically set and duration is computed.\n ", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Run updated", "content": { "application/json": { "schema": { "description": "Run updated", "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "endedAt": { "type": "string", "format": "date-time", "nullable": true }, "durationMs": { "type": "integer", "nullable": true }, "eventCount": { "type": "integer" }, "totalCostUnits": { "type": "string", "nullable": true } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "description": "Run not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "get": { "operationId": "getRun", "summary": "Get run details", "tags": [ "Runs" ], "description": "\nGet run metadata and summary totals.\n\nFor full event history with retry chains, anomalies, and debugging details,\nuse GET /runs/:id/timeline instead.\n ", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Run details with totals", "content": { "application/json": { "schema": { "description": "Run details with totals", "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string" }, "customerName": { "type": "string", "nullable": true }, "workflowId": { "type": "string" }, "workflowName": { "type": "string" }, "status": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "endedAt": { "type": "string", "format": "date-time", "nullable": true }, "durationMs": { "type": "integer", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "correlationId": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "totals": { "type": "object", "properties": { "eventCount": { "type": "integer" }, "totalQuantity": { "type": "string" }, "totalCostUnits": { "type": "string" } } }, "_links": { "type": "object", "properties": { "timeline": { "type": "string", "description": "URL to get full event timeline" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "description": "Run not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/runs/{id}/timeline": { "get": { "operationId": "getRunTimelineV2", "summary": "Get run timeline", "tags": [ "Runs" ], "description": "\nGet a comprehensive timeline view of an agent run including:\n- Full event history with retry chain tracking\n- Anomaly detection and alerts\n- Human-readable explanations\n- Summary statistics\n- Pagination for large runs\n\nThis is THE killer feature for debugging what happened in an agent execution.\n ", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false, "description": "Cursor for pagination" }, { "schema": { "type": "boolean", "default": true }, "in": "query", "name": "includeAnomalies", "required": false }, { "schema": { "type": "boolean", "default": true }, "in": "query", "name": "collapseRetries", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Run timeline with events, anomalies, and summary", "content": { "application/json": { "schema": { "description": "Run timeline with events, anomalies, and summary", "type": "object", "properties": { "runId": { "type": "string" }, "workflowId": { "type": "string", "nullable": true }, "workflowName": { "type": "string", "nullable": true }, "customerId": { "type": "string" }, "status": { "type": "string" }, "correlationId": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "endedAt": { "type": "string", "format": "date-time", "nullable": true }, "durationMs": { "type": "integer", "nullable": true }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "actionName": { "type": "string", "nullable": true }, "outcome": { "type": "string", "enum": [ "SUCCESS", "FAILED", "PENDING", "TIMEOUT", "RETRYING" ] }, "explanation": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" }, "durationMs": { "type": "integer", "nullable": true }, "parentEventId": { "type": "string", "nullable": true }, "retryOfEventId": { "type": "string", "nullable": true }, "attemptNumber": { "type": "integer" }, "retriedByEventId": { "type": "string", "nullable": true }, "costUsdc": { "type": "string", "nullable": true }, "isRetry": { "type": "boolean" }, "retryChain": { "type": "object", "nullable": true, "properties": { "totalAttempts": { "type": "integer" }, "finalOutcome": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } } }, "metadata": { "type": "object", "nullable": true, "properties": { "usageType": { "type": "string" }, "quantity": { "type": "number" }, "units": { "type": "string", "nullable": true } } } } } }, "anomalies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "severity": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "title": { "type": "string" }, "explanation": { "type": "string" }, "relatedEventIds": { "type": "array", "items": { "type": "string" } }, "detectedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "OPEN", "INVESTIGATING", "RESOLVED", "FALSE_POSITIVE", "IGNORED" ] } } } }, "summary": { "type": "object", "properties": { "totalEvents": { "type": "integer" }, "byType": { "type": "object", "additionalProperties": { "type": "integer" } }, "byOutcome": { "type": "object", "additionalProperties": { "type": "integer" } }, "retriedEvents": { "type": "integer" }, "failedEvents": { "type": "integer" }, "totalCostUsdc": { "type": "string", "nullable": true } } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "description": "Run not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/run-events": { "post": { "operationId": "emitRunEvent", "summary": "Emit an event to a run (legacy)", "tags": [ "Runs" ], "description": "\nEmit a single usage event to a run. The event is stored idempotently using the idempotencyKey.\n\n**Note:** This is the legacy endpoint. For the newer execution-first API with richer metadata,\nuse POST /v1/events instead.\n\nThis endpoint records the event for visibility/debugging. For events that should also create a charge,\nuse POST /v1/usage instead.\n ", "responses": { "201": { "description": "Event emitted", "content": { "application/json": { "schema": { "description": "Event emitted", "type": "object", "properties": { "id": { "type": "string" }, "runId": { "type": "string" }, "eventType": { "type": "string" }, "quantity": { "type": "number" }, "costUnits": { "type": "number", "nullable": true }, "isDuplicate": { "type": "boolean" }, "timestamp": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "description": "Run not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Service temporarily unavailable — retry with backoff", "content": { "application/json": { "schema": { "description": "Service temporarily unavailable — retry with backoff", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/run-events/batch": { "post": { "operationId": "batchEmitRunEvents", "summary": "Batch emit events to runs (legacy)", "tags": [ "Runs" ], "description": "\nEmit multiple events in a single request. All events are stored idempotently.\n\n**Note:** This is the legacy endpoint. For the newer execution-first API with richer metadata,\nuse POST /v1/events instead.\n\nEach event can specify its own runId, customerId, and workflowId. If runId is provided,\nthe event is attached to that run. Otherwise, it's a standalone event.\n ", "responses": { "201": { "description": "Events emitted", "content": { "application/json": { "schema": { "description": "Events emitted", "type": "object", "properties": { "success": { "type": "boolean" }, "created": { "type": "integer" }, "duplicates": { "type": "integer" }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "isDuplicate": { "type": "boolean" } } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Service temporarily unavailable — retry with backoff", "content": { "application/json": { "schema": { "description": "Service temporarily unavailable — retry with backoff", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/runs/record": { "post": { "operationId": "recordRun", "summary": "Record a complete run in one call", "tags": [ "Runs" ], "description": "\nOne-call convenience endpoint that atomically creates a workflow (if needed),\nstarts a run, emits events, and ends the run.\n\nThis replaces the 4-step SDK orchestration:\n1. GET /workflows (resolve slug)\n2. POST /runs (start)\n3. POST /run-events/batch (emit events)\n4. PATCH /runs/:id (end)\n\nThe `workflow` field can be a workflow ID or a slug. If a slug is provided\nand no matching workflow exists, one is auto-created.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Drip customer ID (cus_*)", "example": "cus_abc123" }, "workflow": { "type": "string", "description": "Workflow slug/name or workflow ID (wf_*)", "example": "research-agent" }, "events": { "type": "array", "maxItems": 100, "description": "Ordered list of events to attach to the run", "items": { "type": "object", "properties": { "eventType": { "type": "string", "description": "Event name for this step (for example llm.call, tool.call, agent.plan)", "example": "llm.call" }, "quantity": { "type": "number", "description": "Optional numeric quantity for the event", "example": 1700 }, "units": { "type": "string", "description": "Optional unit label for quantity", "example": "tokens" }, "description": { "type": "string", "description": "Optional human-readable label or summary", "example": "web-search" }, "costUnits": { "type": "number", "description": "Optional cost attributed to this event", "example": 0.35 }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional structured metadata such as model, token breakdown, latency, or tool details", "example": { "model": "gpt-4", "inputTokens": 500, "outputTokens": 1200 } } }, "required": [ "eventType" ] }, "default": [] }, "status": { "type": "string", "enum": [ "COMPLETED", "FAILED", "CANCELLED", "TIMEOUT" ], "description": "Final run status", "example": "COMPLETED" }, "errorMessage": { "type": "string", "description": "Optional failure message when status is FAILED", "example": "Provider returned rate_limited" }, "errorCode": { "type": "string", "description": "Optional machine-readable failure code", "example": "rate_limited" }, "externalRunId": { "type": "string", "description": "Optional idempotent run identifier from your system", "example": "job_123" }, "correlationId": { "type": "string", "description": "Optional trace or request ID for cross-system correlation", "example": "trace_abc123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata stored on the run itself", "example": { "tenant": "acme", "environment": "production" } } }, "required": [ "customerId", "workflow", "status" ] } } } }, "responses": { "201": { "description": "Run recorded", "content": { "application/json": { "schema": { "description": "Run recorded", "type": "object", "properties": { "run": { "type": "object", "properties": { "id": { "type": "string" }, "workflowId": { "type": "string" }, "workflowName": { "type": "string" }, "status": { "type": "string" }, "durationMs": { "type": "integer", "nullable": true } } }, "events": { "type": "object", "properties": { "created": { "type": "integer" }, "duplicates": { "type": "integer" } } }, "totalCostUnits": { "type": "string", "nullable": true }, "summary": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer or workflow not found", "content": { "application/json": { "schema": { "description": "Customer or workflow not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "409": { "description": "Run with externalRunId already exists", "content": { "application/json": { "schema": { "description": "Run with externalRunId already exists", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/customers/{customerId}/events": { "get": { "operationId": "getCustomerEvents", "summary": "Get customer events", "tags": [ "Events" ], "description": "Get events for a customer with optional filters.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "workflowId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "eventType", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "customerId", "required": true } ], "responses": { "200": { "description": "Customer events", "content": { "application/json": { "schema": { "description": "Customer events", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "quantity": { "type": "number" }, "units": { "type": "string", "nullable": true }, "costUnits": { "type": "number", "nullable": true }, "runId": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" } } } }, "totals": { "type": "object", "properties": { "eventCount": { "type": "integer" }, "totalQuantity": { "type": "string" }, "totalCostUnits": { "type": "string" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/events": { "post": { "operationId": "createEvent", "summary": "Record an execution event", "tags": [ "Events" ], "description": "Record what happened. Only 2 fields required: `customerId` and `idempotencyKey`.\n\nAll other fields are optional with smart defaults. If you provide `input` or `output` payloads, they are automatically stored for later retrieval via `GET /events/:id/payload` (no need to set `storePayloads: true`).\n\n> **Requires a secret key (`sk_*`) with at least the `OPERATOR` role.**", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "idempotencyKey" ], "properties": { "customerId": { "type": "string", "description": "Drip customer ID (cus_*). Either customerId or externalCustomerId is required.", "example": "cus_abc123" }, "externalCustomerId": { "type": "string", "maxLength": 255, "description": "Your own database's customer ID. If no Drip customer exists yet for (business, externalCustomerId), one is auto-provisioned as an internal customer. Either customerId or externalCustomerId is required.", "example": "user_42" }, "idempotencyKey": { "type": "string", "description": "Unique key (same key = same result)", "example": "req_123" }, "actionName": { "type": "string", "description": "What action was performed (defaults to eventType name if omitted)", "example": "api_call" }, "outcome": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "SKIPPED", "RETRIED", "TIMEOUT", "CANCELLED" ], "description": "SUCCEEDED, FAILED, PENDING, SKIPPED, RETRIED, TIMEOUT, CANCELLED", "example": "SUCCEEDED" }, "explanation": { "type": "string", "maxLength": 2000, "description": "Human-readable note", "example": "Processed request successfully" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Any extra data you want to attach" }, "quantity": { "type": "number", "description": "For billing: how many units", "example": 100 }, "usageType": { "type": "string", "maxLength": 100, "description": "Usage type for billing (matches pricing plan)" }, "units": { "type": "string", "maxLength": 50, "description": "Human-readable unit label (e.g., \"tokens\", \"API calls\")" }, "description": { "type": "string", "maxLength": 500, "description": "Description for support/finance" }, "eventType": { "type": "string", "enum": [ "USAGE", "API_CALL", "LLM_INFERENCE", "TOOL_CALL", "DATABASE", "FILE_IO", "NETWORK", "DECISION", "HUMAN_IN_LOOP", "MEMORY", "CUSTOM", "TOOL_CALL_START", "TOOL_CALL_END", "TOOL_CALL_ERROR", "TOOL_CALL_RETRY", "TRAINING", "FINE_TUNING" ], "description": "Event category", "example": "API_CALL" }, "runId": { "type": "string", "description": "Group events into a run" }, "parentEventId": { "type": "string", "description": "Link to parent event" }, "correlationId": { "type": "string", "maxLength": 255, "description": "Cross-service tracing ID" }, "inputHash": { "type": "string", "maxLength": 128, "description": "SHA-256 hash of input" }, "outputHash": { "type": "string", "maxLength": 128, "description": "SHA-256 hash of output" }, "input": { "type": "object", "additionalProperties": true, "description": "Raw input (will be hashed)" }, "output": { "type": "object", "additionalProperties": true, "description": "Raw output (will be hashed)" }, "workflowId": { "type": "string", "description": "Link to a workflow" }, "retryOfEventId": { "type": "string", "description": "ID of event being retried" }, "attemptNumber": { "type": "integer", "minimum": 1, "description": "Attempt number (1 = first try)" }, "spanId": { "type": "string", "maxLength": 64, "description": "Span ID for distributed tracing" }, "spanKind": { "type": "string", "enum": [ "TOOL", "LLM", "CHAIN", "AGENT", "RETRIEVER", "EMBEDDING", "INTERNAL" ], "description": "OpenTelemetry-inspired span classification" }, "inputBytes": { "type": "integer", "minimum": 0, "description": "Input size in bytes" }, "outputBytes": { "type": "integer", "minimum": 0, "description": "Output size in bytes" }, "queueDurationMs": { "type": "integer", "minimum": 0, "description": "Time spent in queue (ms)" }, "executionDurationMs": { "type": "integer", "minimum": 0, "description": "Execution time (ms)" }, "startedAt": { "type": "string", "format": "date-time", "description": "When execution started" }, "endedAt": { "type": "string", "format": "date-time", "description": "When execution ended" }, "errorType": { "type": "string", "maxLength": 100, "description": "Error class/type" }, "errorMessage": { "type": "string", "maxLength": 2000, "description": "Error message" }, "errorStack": { "type": "string", "maxLength": 10000, "description": "Stack trace" }, "retryCount": { "type": "integer", "minimum": 0, "description": "Number of retries so far" }, "retryBackoffMs": { "type": "integer", "minimum": 0, "description": "Backoff time before next retry (ms)" }, "retryReason": { "type": "string", "maxLength": 500, "description": "Why the retry was triggered" }, "storePayloads": { "type": "boolean", "description": "Controls payload storage. Defaults to true when input/output are provided. Set to false to explicitly disable.", "default": true }, "payloadTtlSeconds": { "type": "integer", "minimum": 1, "description": "TTL for stored payloads in seconds (default: 90 days)" } } } } } }, "responses": { "201": { "description": "Event created successfully", "content": { "application/json": { "schema": { "description": "Event created successfully", "type": "object", "properties": { "id": { "type": "string", "description": "Event ID" }, "eventType": { "type": "string", "enum": [ "USAGE", "API_CALL", "LLM_INFERENCE", "TOOL_CALL", "DATABASE", "FILE_IO", "NETWORK", "DECISION", "HUMAN_IN_LOOP", "MEMORY", "CUSTOM", "TOOL_CALL_START", "TOOL_CALL_END", "TOOL_CALL_ERROR", "TOOL_CALL_RETRY", "TRAINING", "FINE_TUNING" ] }, "actionName": { "type": "string" }, "outcome": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "SKIPPED", "RETRIED", "TIMEOUT", "CANCELLED" ] }, "idempotencyKey": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "wasIdempotentReplay": { "type": "boolean", "description": "True if this was a duplicate request" }, "receipt": { "type": "object", "description": "Signed receipt proving Drip acknowledged this event", "properties": { "batchId": { "type": "string", "description": "Idempotency key for this submission" }, "eventCount": { "type": "integer", "description": "Number of events (1 for single event)" }, "batchHash": { "type": "string", "description": "SHA-256 hash of the event data" }, "receivedAt": { "type": "string", "format": "date-time", "description": "When Drip received the event" }, "signature": { "type": "string", "description": "Server signature of the receipt" }, "signerAddress": { "type": "string", "description": "Address that signed the receipt" } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer or referenced event not found", "content": { "application/json": { "schema": { "description": "Customer or referenced event not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "503": { "description": "Service temporarily unavailable — retry with backoff", "content": { "application/json": { "schema": { "description": "Service temporarily unavailable — retry with backoff", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "get": { "operationId": "listEvents", "summary": "List events", "tags": [ "Events" ], "description": "\nList execution events with optional filters.\n\nSupports filtering by:\n- `customerId`: Events for a specific customer\n- `runId`: Events in a specific agent run\n- `workflowId`: Events in a specific workflow\n- `eventType`: Filter by event type (e.g., LLM_INFERENCE)\n- `outcome`: Filter by outcome (e.g., SUCCESS, FAILURE)\n- `actionName`: Filter by action name\n- `parentEventId`: Get child events\n- `idempotencyKey`: Exact match on idempotency key\n- Time range: `from` and `to` (ISO 8601)\n ", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "customerId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "runId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "workflowId", "required": false }, { "schema": { "type": "string", "enum": [ "USAGE", "API_CALL", "LLM_INFERENCE", "TOOL_CALL", "DATABASE", "FILE_IO", "NETWORK", "DECISION", "HUMAN_IN_LOOP", "MEMORY", "CUSTOM", "TOOL_CALL_START", "TOOL_CALL_END", "TOOL_CALL_ERROR", "TOOL_CALL_RETRY", "TRAINING", "FINE_TUNING" ] }, "in": "query", "name": "eventType", "required": false }, { "schema": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "SKIPPED", "RETRIED", "TIMEOUT", "CANCELLED" ] }, "in": "query", "name": "outcome", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "actionName", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "parentEventId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "idempotencyKey", "required": false, "description": "Filter by idempotency key" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "List of events with pagination", "content": { "application/json": { "schema": { "description": "List of events with pagination", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "actionName": { "type": "string" }, "outcome": { "type": "string" }, "explanation": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true, "description": "Client-provided idempotency key" }, "customerId": { "type": "string" }, "runId": { "type": "string", "nullable": true }, "workflowId": { "type": "string", "nullable": true }, "parentEventId": { "type": "string", "nullable": true }, "retryOfEventId": { "type": "string", "nullable": true }, "attemptNumber": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "chargeId": { "type": "string", "nullable": true }, "costUsdc": { "type": "string", "nullable": true }, "usageType": { "type": "string", "nullable": true }, "quantity": { "type": "string", "nullable": true }, "units": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/events/{id}": { "get": { "operationId": "getEvent", "summary": "Get event details", "tags": [ "Events" ], "description": "\nRetrieve a single event with full details including:\n- Execution metadata (eventType, outcome, explanation)\n- Input/output hashes\n- Causality links (parent, children, retry chain)\n- Billing information (if applicable)\n ", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Event ID" } ], "responses": { "200": { "description": "Event details", "content": { "application/json": { "schema": { "description": "Event details", "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string", "enum": [ "USAGE", "API_CALL", "LLM_INFERENCE", "TOOL_CALL", "DATABASE", "FILE_IO", "NETWORK", "DECISION", "HUMAN_IN_LOOP", "MEMORY", "CUSTOM", "TOOL_CALL_START", "TOOL_CALL_END", "TOOL_CALL_ERROR", "TOOL_CALL_RETRY", "TRAINING", "FINE_TUNING" ] }, "actionName": { "type": "string" }, "outcome": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "SKIPPED", "RETRIED", "TIMEOUT", "CANCELLED" ] }, "explanation": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true, "description": "Client-provided idempotency key" }, "customerId": { "type": "string" }, "runId": { "type": "string", "nullable": true }, "workflowId": { "type": "string", "nullable": true }, "parentEventId": { "type": "string", "nullable": true }, "retryOfEventId": { "type": "string", "nullable": true }, "attemptNumber": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "inputHash": { "type": "string", "nullable": true }, "outputHash": { "type": "string", "nullable": true }, "childEvents": { "type": "array", "items": { "type": "string" }, "description": "IDs of events caused by this one" }, "retriedBy": { "type": "string", "nullable": true, "description": "ID of retry event if this failed" }, "chargeId": { "type": "string", "nullable": true }, "costUsdc": { "type": "string", "nullable": true }, "usageType": { "type": "string", "nullable": true }, "quantity": { "type": "string", "nullable": true }, "units": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Event not found", "content": { "application/json": { "schema": { "description": "Event not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/events/{id}/payload": { "get": { "operationId": "getEventPayload", "summary": "Get stored payloads for an event", "tags": [ "Events" ], "description": "\nRetrieve raw input/output payloads that were stored when the event was created\nwith `storePayloads: true`.\n\nReturns the full JSON payloads along with integrity hashes and size information.\nReturns 404 if no payloads were stored or if they have expired.\n\n**Use case**: Historical data replay, audit trails, debugging.\n ", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Event ID" } ], "responses": { "200": { "description": "Stored payloads", "content": { "application/json": { "schema": { "description": "Stored payloads", "type": "object", "properties": { "id": { "type": "string" }, "usageEventId": { "type": "string" }, "inputPayload": { "type": "object", "nullable": true, "additionalProperties": true }, "outputPayload": { "type": "object", "nullable": true, "additionalProperties": true }, "inputHash": { "type": "string", "nullable": true }, "outputHash": { "type": "string", "nullable": true }, "inputSizeBytes": { "type": "integer", "nullable": true }, "outputSizeBytes": { "type": "integer", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "No payload stored for this event", "content": { "application/json": { "schema": { "description": "No payload stored for this event", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/events/{id}/trace": { "get": { "operationId": "traceEvent", "summary": "Trace event causality", "tags": [ "Events" ], "description": "\nGet the full causality context for an event in a single API call.\n\nReturns:\n- **ancestors**: Parent chain from root to this event's parent\n- **children**: Direct child events caused by this event\n- **retryChain**: Original event and all retry attempts\n- **anomalies**: Detected anomalies linked to this event\n- **summary**: Quick stats (counts, hasFailures flag)\n\n**Query Parameters:**\n- `format=tree` - Returns ASCII tree output for CLI/support tickets\n\nThis is the primary debugging endpoint for tracing errors through the ledger.\n\n**Example use case**: Customer reports \"my run failed at step 5\"\n```\nGET /v1/events/{failingEventId}/trace\nGET /v1/events/{failingEventId}/trace?format=tree\n```\nReturns the complete context: what led to this event, what it triggered,\nwhether it was retried, and any anomalies detected.\n ", "parameters": [ { "schema": { "type": "string", "enum": [ "json", "tree" ] }, "in": "query", "name": "format", "required": false, "description": "Output format (default: json)" }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Event ID to trace" } ], "responses": { "200": { "description": "Full event trace with causality context", "content": { "application/json": { "schema": { "description": "Full event trace with causality context", "type": "object", "properties": { "event": { "type": "object", "description": "The event being traced (full details)", "properties": { "id": { "type": "string" }, "eventType": { "type": "string", "enum": [ "USAGE", "API_CALL", "LLM_INFERENCE", "TOOL_CALL", "DATABASE", "FILE_IO", "NETWORK", "DECISION", "HUMAN_IN_LOOP", "MEMORY", "CUSTOM", "TOOL_CALL_START", "TOOL_CALL_END", "TOOL_CALL_ERROR", "TOOL_CALL_RETRY", "TRAINING", "FINE_TUNING" ] }, "actionName": { "type": "string" }, "outcome": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "SKIPPED", "RETRIED", "TIMEOUT", "CANCELLED" ] }, "explanation": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string", "nullable": true }, "customerId": { "type": "string" }, "runId": { "type": "string", "nullable": true }, "workflowId": { "type": "string", "nullable": true }, "parentEventId": { "type": "string", "nullable": true }, "retryOfEventId": { "type": "string", "nullable": true }, "attemptNumber": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "inputHash": { "type": "string", "nullable": true }, "outputHash": { "type": "string", "nullable": true }, "childEvents": { "type": "array", "items": { "type": "string" } }, "retriedBy": { "type": "string", "nullable": true }, "chargeId": { "type": "string", "nullable": true }, "costUsdc": { "type": "string", "nullable": true }, "usageType": { "type": "string", "nullable": true }, "quantity": { "type": "string", "nullable": true }, "units": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "spanKind": { "type": "string", "nullable": true }, "inputBytes": { "type": "integer", "nullable": true }, "outputBytes": { "type": "integer", "nullable": true }, "queueDurationMs": { "type": "integer", "nullable": true }, "executionDurationMs": { "type": "integer", "nullable": true }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "endedAt": { "type": "string", "format": "date-time", "nullable": true }, "errorType": { "type": "string", "nullable": true }, "errorMessage": { "type": "string", "nullable": true }, "errorStack": { "type": "string", "nullable": true }, "retryCount": { "type": "integer", "nullable": true }, "retryBackoffMs": { "type": "integer", "nullable": true }, "retryReason": { "type": "string", "nullable": true } } }, "ancestors": { "type": "array", "description": "Parent chain from root to parent (ordered root → parent)", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "actionName": { "type": "string" }, "outcome": { "type": "string" }, "explanation": { "type": "string", "nullable": true }, "attemptNumber": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "costUsdc": { "type": "string", "nullable": true } } } }, "children": { "type": "array", "description": "Direct child events", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "actionName": { "type": "string" }, "outcome": { "type": "string" }, "explanation": { "type": "string", "nullable": true }, "attemptNumber": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "costUsdc": { "type": "string", "nullable": true } } } }, "retryChain": { "type": "object", "description": "Retry chain if this event was retried or is a retry", "properties": { "originalEvent": { "type": "object", "nullable": true, "additionalProperties": true, "description": "The original event that was retried" }, "retries": { "type": "array", "description": "All retry attempts ordered by attemptNumber", "items": { "type": "object", "additionalProperties": true } } } }, "anomalies": { "type": "array", "description": "Anomalies linked to this event or its retry chain", "items": { "type": "object", "properties": { "id": { "type": "string" }, "anomalyType": { "type": "string" }, "severity": { "type": "string" }, "detectedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "metric": { "type": "string", "nullable": true }, "expectedValue": { "type": "string", "nullable": true }, "actualValue": { "type": "string", "nullable": true } } } }, "summary": { "type": "object", "description": "Quick summary statistics", "properties": { "totalAncestors": { "type": "integer" }, "totalChildren": { "type": "integer" }, "totalRetries": { "type": "integer" }, "totalAnomalies": { "type": "integer" }, "hasFailures": { "type": "boolean", "description": "True if any event in trace has FAILURE outcome" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Event not found", "content": { "application/json": { "schema": { "description": "Event not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/trace/{correlationId}": { "get": { "operationId": "traceByCorrelationId", "summary": "Trace by correlation ID", "tags": [ "Events" ], "description": "\nTrace events across multiple runs and services using a correlation ID.\n\nReturns all events that share the same correlation ID, grouped by run.\nUseful for debugging distributed agent workflows.\n\n**Example use case**: Tracing a request across multiple microservices\n```\nGET /v1/trace/{correlationId}\n```\n ", "parameters": [ { "schema": { "type": "string", "enum": [ "json", "tree" ] }, "in": "query", "name": "format", "required": false, "description": "Output format (default: json)" }, { "schema": { "type": "string" }, "in": "path", "name": "correlationId", "required": true, "description": "Correlation ID to trace" } ], "responses": { "200": { "description": "Events grouped by run with trace context", "content": { "application/json": { "schema": { "description": "Events grouped by run with trace context", "type": "object", "properties": { "correlationId": { "type": "string" }, "totalEvents": { "type": "integer" }, "totalRuns": { "type": "integer" }, "runs": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string", "nullable": true }, "workflowName": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "actionName": { "type": "string" }, "outcome": { "type": "string" }, "explanation": { "type": "string", "nullable": true }, "timestamp": { "type": "string", "format": "date-time" } } } } } } }, "anomalies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "severity": { "type": "string" }, "detectedAt": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "No events found with this correlation ID", "content": { "application/json": { "schema": { "description": "No events found with this correlation ID", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/events/payloads": { "get": { "operationId": "listEventPayloads", "summary": "List events with payloads (flat format)", "tags": [ "Events" ], "description": "\nReturns events joined with their stored payloads in a flat, tabular format\ndesigned for data engineers and SQL-based workflows.\n\nEach row is a single event with its input/output payloads inlined.\nOnly events that have stored payloads are returned (i.e., events created\nwith `input` or `output` fields).\n\n**Filters:** `customerId`, `actionName`, `from`/`to` (ISO 8601 date range),\n`hasInput`, `hasOutput` (boolean).\n\n**Use cases:**\n- Export to data warehouses (BigQuery, Snowflake, Redshift)\n- Ad-hoc SQL analysis of event payloads\n- Training data extraction for ML pipelines\n- Compliance audits requiring full payload history\n ", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "customerId", "required": false, "description": "Filter by customer" }, { "schema": { "type": "string" }, "in": "query", "name": "actionName", "required": false, "description": "Filter by action name" }, { "schema": { "type": "string", "enum": [ "USAGE", "API_CALL", "LLM_INFERENCE", "TOOL_CALL", "DATABASE", "FILE_IO", "NETWORK", "DECISION", "HUMAN_IN_LOOP", "MEMORY", "CUSTOM", "TOOL_CALL_START", "TOOL_CALL_END", "TOOL_CALL_ERROR", "TOOL_CALL_RETRY", "TRAINING", "FINE_TUNING" ] }, "in": "query", "name": "eventType", "required": false, "description": "Filter by event type" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "from", "required": false, "description": "Start of time range (inclusive)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "to", "required": false, "description": "End of time range (inclusive)" }, { "schema": { "type": "boolean" }, "in": "query", "name": "hasInput", "required": false, "description": "Only events with input payloads" }, { "schema": { "type": "boolean" }, "in": "query", "name": "hasOutput", "required": false, "description": "Only events with output payloads" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "Flat list of events with inlined payloads", "content": { "application/json": { "schema": { "description": "Flat list of events with inlined payloads", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string" }, "customerId": { "type": "string" }, "actionName": { "type": "string" }, "eventType": { "type": "string" }, "outcome": { "type": "string", "nullable": true }, "quantity": { "type": "string" }, "units": { "type": "string", "nullable": true }, "idempotencyKey": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "inputPayload": { "type": "object", "nullable": true, "additionalProperties": true }, "outputPayload": { "type": "object", "nullable": true, "additionalProperties": true }, "inputHash": { "type": "string", "nullable": true }, "outputHash": { "type": "string", "nullable": true }, "inputSizeBytes": { "type": "integer", "nullable": true }, "outputSizeBytes": { "type": "integer", "nullable": true }, "payloadExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "runId": { "type": "string", "nullable": true }, "workflowId": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" } } }, "sql_hint": { "type": "string", "description": "Example SQL query for this data set" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/billable-metrics": { "get": { "operationId": "listBillableMetrics", "summary": "List billable metrics", "tags": [ "BillableMetrics" ], "description": "List every billable metric defined for the business.", "responses": { "200": { "description": "Default Response" } } }, "post": { "operationId": "createBillableMetric", "summary": "Create a billable metric", "tags": [ "BillableMetrics" ], "description": "Creates a new billable metric. Name must be unique per business. Supply one or more event types — the metric will union events across all of them.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/billable-metrics/{id}": { "get": { "operationId": "getBillableMetric", "summary": "Get a billable metric by id", "tags": [ "BillableMetrics" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "operationId": "updateBillableMetric", "summary": "Update a billable metric", "tags": [ "BillableMetrics" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "deleteBillableMetric", "summary": "Delete (soft-delete) a billable metric", "tags": [ "BillableMetrics" ], "description": "Sets isActive=false. Rate cards that reference the metric keep working for historical charges because the row stays in the DB.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/billable-metrics/{id}/evaluate": { "post": { "operationId": "evaluateBillableMetric", "summary": "Evaluate a billable metric over a period (no side effects)", "tags": [ "BillableMetrics" ], "description": "Executes the metric's SQL expression (or, if not set, the declarative aggregation) against the merchant's usage events for [periodStart, periodEnd) and returns the result. Read-only — no charges, invoices, or counters change.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/billable-metrics/preview": { "post": { "operationId": "previewBillableMetricSql", "summary": "Preview an unsaved sqlExpression", "tags": [ "BillableMetrics" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/subscriptions": { "post": { "operationId": "createSubscription", "summary": "Create a subscription", "tags": [ "Subscriptions" ], "description": "Create a recurring billing subscription for a customer.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customerId", "name", "interval", "priceUsdc" ], "properties": { "customerId": { "type": "string", "description": "Customer ID" }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Subscription name" }, "description": { "type": "string", "maxLength": 1000, "description": "Optional description" }, "interval": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "ANNUAL" ], "description": "Billing interval" }, "priceUsdc": { "type": "number", "exclusiveMinimum": 0, "description": "Price per interval in USDC" }, "metadata": { "type": "object", "description": "Custom metadata" }, "trialDays": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Trial period in days (1-365)" }, "includedUsage": { "type": "integer", "description": "Included usage units per period" }, "overageUnitType": { "type": "string", "description": "Usage type for overage metering" } } } } } }, "responses": { "201": { "description": "Subscription created", "content": { "application/json": { "schema": { "description": "Subscription created", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "get": { "operationId": "listSubscriptions", "summary": "List subscriptions", "tags": [ "Subscriptions" ], "description": "List all subscriptions for your business.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "customerId", "required": false, "description": "Filter by customer ID" }, { "schema": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "CANCELLED", "EXPIRED", "PAST_DUE", "TRIALING" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by status" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "in": "query", "name": "limit", "required": false, "description": "Maximum results" } ], "responses": { "200": { "description": "List of subscriptions", "content": { "application/json": { "schema": { "description": "List of subscriptions", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/subscriptions/{id}": { "get": { "operationId": "getSubscription", "summary": "Get a subscription", "tags": [ "Subscriptions" ], "description": "Get details for a specific subscription.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Subscription ID" } ], "responses": { "200": { "description": "Subscription details", "content": { "application/json": { "schema": { "description": "Subscription details", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "description": "Subscription not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "patch": { "operationId": "updateSubscription", "summary": "Update a subscription", "tags": [ "Subscriptions" ], "description": "Update a subscription. Price changes take effect at the next billing period.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "priceUsdc": { "type": "number" }, "metadata": { "type": "object" }, "includedUsage": { "type": "integer" }, "overageUnitType": { "type": "string" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Subscription ID" } ], "responses": { "200": { "description": "Updated subscription", "content": { "application/json": { "schema": { "description": "Updated subscription", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "description": "Subscription not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/subscriptions/{id}/cancel": { "post": { "operationId": "cancelSubscription", "summary": "Cancel a subscription", "tags": [ "Subscriptions" ], "description": "Cancel a subscription. By default, cancels at the end of the current billing period.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "immediate": { "type": "boolean", "default": false, "description": "Cancel immediately instead of at period end" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Subscription ID" } ], "responses": { "200": { "description": "Subscription cancelled", "content": { "application/json": { "schema": { "description": "Subscription cancelled", "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid state", "content": { "application/json": { "schema": { "description": "Invalid state", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "description": "Subscription not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/subscriptions/{id}/pause": { "post": { "operationId": "pauseSubscription", "summary": "Pause a subscription", "tags": [ "Subscriptions" ], "description": "Pause an active subscription. No charges will be created while paused.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resumeDate": { "type": "string", "format": "date-time", "description": "Auto-resume date (optional)" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Subscription ID" } ], "responses": { "200": { "description": "Subscription paused", "content": { "application/json": { "schema": { "description": "Subscription paused", "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid state", "content": { "application/json": { "schema": { "description": "Invalid state", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "description": "Subscription not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/subscriptions/{id}/resume": { "post": { "operationId": "resumeSubscription", "summary": "Resume a subscription", "tags": [ "Subscriptions" ], "description": "Resume a paused subscription. Starts a new billing period.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Subscription ID" } ], "responses": { "200": { "description": "Subscription resumed", "content": { "application/json": { "schema": { "description": "Subscription resumed", "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid state", "content": { "application/json": { "schema": { "description": "Invalid state", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Subscription not found", "content": { "application/json": { "schema": { "description": "Subscription not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/contracts": { "post": { "operationId": "createContract", "summary": "Create a contract", "tags": [ "Contracts" ], "description": "Create a per-customer commercial agreement with custom pricing, prepaid commits, and spend caps.\n\nContracts override default pricing plans for a specific customer. Use them for:\n- **Enterprise deals** with negotiated rates (via price overrides)\n- **Prepaid commits** where the customer pays upfront and draws down a balance\n- **Spend caps** to enforce maximum billing per period\n- **Minimum commits** to guarantee a revenue floor\n- **Volume discounts** applied as a percentage across all usage\n- **Free-tier allocations** with included units per usage type\n\nThe `customerId` must reference a customer created via `POST /customers`. If `prepaidAmountUsdc` is provided, the contract is initialized with that amount as `prepaidBalanceUsdc`.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Create a per-customer commercial agreement. Use contracts to offer enterprise customers custom pricing, prepaid commits, spend caps, and volume discounts. The customer must already exist (created via `POST /customers`).", "properties": { "customerId": { "type": "string", "minLength": 1, "description": "ID of the customer this contract applies to. Must be a valid customer ID returned from `POST /customers`.", "example": "cus_abc123def456" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable name for the contract (e.g., \"Acme Corp Enterprise Q1 2024\")", "example": "Acme Corp Enterprise Agreement" }, "startDate": { "type": "string", "format": "date-time", "description": "When the contract takes effect (ISO 8601). Can be in the future for scheduled activations.", "example": "2024-01-01T00:00:00.000Z" }, "endDate": { "type": "string", "format": "date-time", "description": "When the contract expires (ISO 8601). Omit for a perpetual contract with no end date.", "example": "2024-12-31T23:59:59.000Z" }, "minimumUsdc": { "type": "string", "description": "Minimum committed spend in USDC. The customer is billed for at least this amount regardless of actual usage. Use for minimum-commit deals.", "example": "500.00" }, "maximumUsdc": { "type": "string", "description": "Maximum spend cap in USDC. Charges that would exceed this cap are blocked. Use for budget-capped agreements.", "example": "10000.00" }, "discountPct": { "type": "string", "description": "Percentage discount applied to all charges (0-100). For example, \"15\" means 15% off all usage charges under this contract.", "example": "15" }, "prepaidAmountUsdc": { "type": "string", "description": "Prepaid commit amount in USDC. This amount is pre-loaded as a credit balance. Charges draw down from this balance first before falling back to normal billing.", "example": "1000.00" }, "prepaidRollover": { "type": "boolean", "description": "Whether unused prepaid balance rolls over to the next billing period. Defaults to false (unused balance expires).", "default": false }, "includedUnits": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Free unit allocations per usage type. Keys are unit types (must match pricing plan `unitType`), values are the number of free units per billing period. Usage within these limits is not charged.", "example": { "api_call": 10000, "token": 1000000 } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Arbitrary key-value metadata. Useful for storing external references (CRM deal IDs, internal tags, etc.).", "example": { "salesforceId": "OPP-12345", "tier": "enterprise" } } }, "required": [ "customerId", "name", "startDate" ] } } }, "description": "Create a per-customer commercial agreement. Use contracts to offer enterprise customers custom pricing, prepaid commits, spend caps, and volume discounts. The customer must already exist (created via `POST /customers`)." }, "responses": { "201": { "description": "Contract created successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Contract created successfully", "properties": { "id": { "type": "string", "description": "Unique identifier for the contract", "example": "ctr_abc123def456" }, "businessId": { "type": "string", "description": "Business that owns this contract", "example": "biz_789xyz" }, "customerId": { "type": "string", "description": "Customer this contract applies to (must be created via POST /customers first)", "example": "cus_abc123def456" }, "name": { "type": "string", "description": "Human-readable name for the contract", "example": "Acme Corp Enterprise Agreement" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "EXPIRED", "CANCELLED" ], "description": "Current contract status. Only ACTIVE contracts affect billing. Transitions: ACTIVE → PAUSED, EXPIRED, or CANCELLED.", "example": "ACTIVE" }, "startDate": { "type": "string", "format": "date-time", "description": "When the contract takes effect (ISO 8601)", "example": "2024-01-01T00:00:00.000Z" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "When the contract expires (ISO 8601). Null means the contract is perpetual.", "example": "2024-12-31T23:59:59.000Z" }, "minimumUsdc": { "type": "string", "nullable": true, "description": "Minimum committed spend in USDC for the contract period. If the customer spends less, they are still billed for the minimum.", "example": "500.000000" }, "maximumUsdc": { "type": "string", "nullable": true, "description": "Maximum spend cap in USDC for the contract period. Charges that would exceed this cap are blocked.", "example": "10000.000000" }, "discountPct": { "type": "string", "nullable": true, "description": "Percentage discount applied to all charges under this contract (0-100, up to 2 decimal places)", "example": "15.00" }, "prepaidAmountUsdc": { "type": "string", "nullable": true, "description": "Total prepaid commit amount in USDC. This is the initial balance loaded into the contract.", "example": "1000.000000" }, "prepaidBalanceUsdc": { "type": "string", "nullable": true, "description": "Remaining prepaid balance in USDC. Decreases as charges are applied. When depleted, charges fall back to normal billing.", "example": "750.000000" }, "prepaidRollover": { "type": "boolean", "description": "Whether unused prepaid balance rolls over to the next billing period", "example": false }, "includedUnits": { "type": "object", "nullable": true, "additionalProperties": { "type": "number" }, "description": "Free unit allocations per usage type per billing period. Usage within these limits is not charged. Keys are unit types, values are quantities.", "example": { "api_call": 10000, "token": 1000000 } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Arbitrary key-value metadata for your own tracking (e.g., Salesforce deal ID, internal notes)", "example": { "salesforceId": "OPP-12345", "tier": "enterprise" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the contract was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the contract was last updated", "example": "2024-01-15T10:30:00.000Z" }, "priceOverrides": { "type": "array", "description": "Custom per-unit-type pricing that overrides default pricing plans for this customer", "items": { "type": "object", "description": "A per-unit-type price override within a contract. Overrides the default pricing plan rate for this customer.", "properties": { "id": { "type": "string", "description": "Unique identifier for the price override", "example": "cpo_abc123def456" }, "unitType": { "type": "string", "description": "The usage type this override applies to (must match a pricing plan `unitType`)", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Custom price per unit in USD (string for decimal precision, up to 6 decimal places)", "example": "0.000800" } }, "required": [ "id", "unitType", "unitPriceUsd" ] } } }, "required": [ "id", "businessId", "customerId", "name", "status", "startDate", "prepaidRollover", "createdAt", "updatedAt", "priceOverrides" ] } } } }, "400": { "description": "Validation error (missing required fields, invalid format)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Validation error (missing required fields, invalid format)" } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized — missing or invalid API key" } } } }, "403": { "description": "Forbidden — API key does not have ADMIN role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Forbidden — API key does not have ADMIN role" } } } }, "404": { "description": "Customer not found — the `customerId` does not exist or does not belong to your business", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Customer not found — the `customerId` does not exist or does not belong to your business" } } } } } }, "get": { "operationId": "listContracts", "summary": "List contracts", "tags": [ "Contracts" ], "description": "List all contracts for your business, optionally filtered by customer or status. Results are ordered by creation date (newest first).\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "parameters": [ { "schema": { "type": "string", "example": "cus_abc123def456" }, "in": "query", "name": "customerId", "required": false, "description": "Filter contracts by customer ID" }, { "schema": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "EXPIRED", "CANCELLED" ], "example": "ACTIVE" }, "in": "query", "name": "status", "required": false, "description": "Filter contracts by status" } ], "responses": { "200": { "description": "List of contracts", "content": { "application/json": { "schema": { "type": "object", "description": "List of contracts", "properties": { "contracts": { "type": "array", "items": { "type": "object", "description": "A per-customer commercial agreement. Contracts allow custom pricing, prepaid commits, spend caps, volume discounts, and included unit allocations that override default pricing plans for a specific customer.", "properties": { "id": { "type": "string", "description": "Unique identifier for the contract", "example": "ctr_abc123def456" }, "businessId": { "type": "string", "description": "Business that owns this contract", "example": "biz_789xyz" }, "customerId": { "type": "string", "description": "Customer this contract applies to (must be created via POST /customers first)", "example": "cus_abc123def456" }, "name": { "type": "string", "description": "Human-readable name for the contract", "example": "Acme Corp Enterprise Agreement" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "EXPIRED", "CANCELLED" ], "description": "Current contract status. Only ACTIVE contracts affect billing. Transitions: ACTIVE → PAUSED, EXPIRED, or CANCELLED.", "example": "ACTIVE" }, "startDate": { "type": "string", "format": "date-time", "description": "When the contract takes effect (ISO 8601)", "example": "2024-01-01T00:00:00.000Z" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "When the contract expires (ISO 8601). Null means the contract is perpetual.", "example": "2024-12-31T23:59:59.000Z" }, "minimumUsdc": { "type": "string", "nullable": true, "description": "Minimum committed spend in USDC for the contract period. If the customer spends less, they are still billed for the minimum.", "example": "500.000000" }, "maximumUsdc": { "type": "string", "nullable": true, "description": "Maximum spend cap in USDC for the contract period. Charges that would exceed this cap are blocked.", "example": "10000.000000" }, "discountPct": { "type": "string", "nullable": true, "description": "Percentage discount applied to all charges under this contract (0-100, up to 2 decimal places)", "example": "15.00" }, "prepaidAmountUsdc": { "type": "string", "nullable": true, "description": "Total prepaid commit amount in USDC. This is the initial balance loaded into the contract.", "example": "1000.000000" }, "prepaidBalanceUsdc": { "type": "string", "nullable": true, "description": "Remaining prepaid balance in USDC. Decreases as charges are applied. When depleted, charges fall back to normal billing.", "example": "750.000000" }, "prepaidRollover": { "type": "boolean", "description": "Whether unused prepaid balance rolls over to the next billing period", "example": false }, "includedUnits": { "type": "object", "nullable": true, "additionalProperties": { "type": "number" }, "description": "Free unit allocations per usage type per billing period. Usage within these limits is not charged. Keys are unit types, values are quantities.", "example": { "api_call": 10000, "token": 1000000 } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Arbitrary key-value metadata for your own tracking (e.g., Salesforce deal ID, internal notes)", "example": { "salesforceId": "OPP-12345", "tier": "enterprise" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the contract was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the contract was last updated", "example": "2024-01-15T10:30:00.000Z" }, "priceOverrides": { "type": "array", "description": "Custom per-unit-type pricing that overrides default pricing plans for this customer", "items": { "type": "object", "description": "A per-unit-type price override within a contract. Overrides the default pricing plan rate for this customer.", "properties": { "id": { "type": "string", "description": "Unique identifier for the price override", "example": "cpo_abc123def456" }, "unitType": { "type": "string", "description": "The usage type this override applies to (must match a pricing plan `unitType`)", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Custom price per unit in USD (string for decimal precision, up to 6 decimal places)", "example": "0.000800" } }, "required": [ "id", "unitType", "unitPriceUsd" ] } } }, "required": [ "id", "businessId", "customerId", "name", "status", "startDate", "prepaidRollover", "createdAt", "updatedAt", "priceOverrides" ] }, "description": "List of contracts ordered by creation date (newest first)" } }, "required": [ "contracts" ] } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized — missing or invalid API key" } } } }, "403": { "description": "Forbidden — API key does not have ADMIN role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Forbidden — API key does not have ADMIN role" } } } } } } }, "/v1/contracts/{id}": { "get": { "operationId": "getContract", "summary": "Get a contract", "tags": [ "Contracts" ], "description": "Retrieve a specific contract by ID, including its current prepaid balance and all price overrides.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Contract ID" } ], "responses": { "200": { "description": "Contract details", "content": { "application/json": { "schema": { "type": "object", "description": "Contract details", "properties": { "id": { "type": "string", "description": "Unique identifier for the contract", "example": "ctr_abc123def456" }, "businessId": { "type": "string", "description": "Business that owns this contract", "example": "biz_789xyz" }, "customerId": { "type": "string", "description": "Customer this contract applies to (must be created via POST /customers first)", "example": "cus_abc123def456" }, "name": { "type": "string", "description": "Human-readable name for the contract", "example": "Acme Corp Enterprise Agreement" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "EXPIRED", "CANCELLED" ], "description": "Current contract status. Only ACTIVE contracts affect billing. Transitions: ACTIVE → PAUSED, EXPIRED, or CANCELLED.", "example": "ACTIVE" }, "startDate": { "type": "string", "format": "date-time", "description": "When the contract takes effect (ISO 8601)", "example": "2024-01-01T00:00:00.000Z" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "When the contract expires (ISO 8601). Null means the contract is perpetual.", "example": "2024-12-31T23:59:59.000Z" }, "minimumUsdc": { "type": "string", "nullable": true, "description": "Minimum committed spend in USDC for the contract period. If the customer spends less, they are still billed for the minimum.", "example": "500.000000" }, "maximumUsdc": { "type": "string", "nullable": true, "description": "Maximum spend cap in USDC for the contract period. Charges that would exceed this cap are blocked.", "example": "10000.000000" }, "discountPct": { "type": "string", "nullable": true, "description": "Percentage discount applied to all charges under this contract (0-100, up to 2 decimal places)", "example": "15.00" }, "prepaidAmountUsdc": { "type": "string", "nullable": true, "description": "Total prepaid commit amount in USDC. This is the initial balance loaded into the contract.", "example": "1000.000000" }, "prepaidBalanceUsdc": { "type": "string", "nullable": true, "description": "Remaining prepaid balance in USDC. Decreases as charges are applied. When depleted, charges fall back to normal billing.", "example": "750.000000" }, "prepaidRollover": { "type": "boolean", "description": "Whether unused prepaid balance rolls over to the next billing period", "example": false }, "includedUnits": { "type": "object", "nullable": true, "additionalProperties": { "type": "number" }, "description": "Free unit allocations per usage type per billing period. Usage within these limits is not charged. Keys are unit types, values are quantities.", "example": { "api_call": 10000, "token": 1000000 } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Arbitrary key-value metadata for your own tracking (e.g., Salesforce deal ID, internal notes)", "example": { "salesforceId": "OPP-12345", "tier": "enterprise" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the contract was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the contract was last updated", "example": "2024-01-15T10:30:00.000Z" }, "priceOverrides": { "type": "array", "description": "Custom per-unit-type pricing that overrides default pricing plans for this customer", "items": { "type": "object", "description": "A per-unit-type price override within a contract. Overrides the default pricing plan rate for this customer.", "properties": { "id": { "type": "string", "description": "Unique identifier for the price override", "example": "cpo_abc123def456" }, "unitType": { "type": "string", "description": "The usage type this override applies to (must match a pricing plan `unitType`)", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Custom price per unit in USD (string for decimal precision, up to 6 decimal places)", "example": "0.000800" } }, "required": [ "id", "unitType", "unitPriceUsd" ] } } }, "required": [ "id", "businessId", "customerId", "name", "status", "startDate", "prepaidRollover", "createdAt", "updatedAt", "priceOverrides" ] } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized — missing or invalid API key" } } } }, "403": { "description": "Forbidden — API key does not have ADMIN role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Forbidden — API key does not have ADMIN role" } } } }, "404": { "description": "Contract not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Contract not found" } } } } } }, "patch": { "operationId": "amendContract", "summary": "Amend a contract", "tags": [ "Contracts" ], "description": "Update an active contract's terms. Only ACTIVE contracts can be amended.\n\nProvide only the fields you want to change — unspecified fields remain unchanged. Note that `includedUnits` and `metadata` are replaced entirely (not merged) when provided.\n\nCannot change: `customerId`, `startDate`, `prepaidAmountUsdc`, or `status` (use `DELETE` to cancel).\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Update an existing contract. Only ACTIVE contracts can be amended. All fields are optional: only provided fields are updated. Cannot change `customerId` or `startDate` after creation.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Updated contract name", "example": "Acme Corp Enterprise Agreement (Amended)" }, "endDate": { "type": "string", "format": "date-time", "description": "Updated expiration date (ISO 8601). Set to extend or shorten the contract.", "example": "2025-06-30T23:59:59.000Z" }, "minimumUsdc": { "type": "string", "description": "Updated minimum committed spend in USDC", "example": "750.00" }, "maximumUsdc": { "type": "string", "description": "Updated maximum spend cap in USDC", "example": "15000.00" }, "discountPct": { "type": "string", "description": "Updated percentage discount (0-100)", "example": "20" }, "includedUnits": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Updated free unit allocations. Replaces the entire `includedUnits` object (not merged).", "example": { "api_call": 20000, "token": 2000000 } }, "metadata": { "type": "object", "additionalProperties": true, "description": "Updated metadata. Replaces the entire `metadata` object (not merged).", "example": { "salesforceId": "OPP-12345", "tier": "enterprise", "amended": true } } } } } }, "description": "Update an existing contract. Only ACTIVE contracts can be amended. All fields are optional: only provided fields are updated. Cannot change `customerId` or `startDate` after creation." }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Contract ID" } ], "responses": { "200": { "description": "Contract amended successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Contract amended successfully", "properties": { "id": { "type": "string", "description": "Unique identifier for the contract", "example": "ctr_abc123def456" }, "businessId": { "type": "string", "description": "Business that owns this contract", "example": "biz_789xyz" }, "customerId": { "type": "string", "description": "Customer this contract applies to (must be created via POST /customers first)", "example": "cus_abc123def456" }, "name": { "type": "string", "description": "Human-readable name for the contract", "example": "Acme Corp Enterprise Agreement" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "EXPIRED", "CANCELLED" ], "description": "Current contract status. Only ACTIVE contracts affect billing. Transitions: ACTIVE → PAUSED, EXPIRED, or CANCELLED.", "example": "ACTIVE" }, "startDate": { "type": "string", "format": "date-time", "description": "When the contract takes effect (ISO 8601)", "example": "2024-01-01T00:00:00.000Z" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "When the contract expires (ISO 8601). Null means the contract is perpetual.", "example": "2024-12-31T23:59:59.000Z" }, "minimumUsdc": { "type": "string", "nullable": true, "description": "Minimum committed spend in USDC for the contract period. If the customer spends less, they are still billed for the minimum.", "example": "500.000000" }, "maximumUsdc": { "type": "string", "nullable": true, "description": "Maximum spend cap in USDC for the contract period. Charges that would exceed this cap are blocked.", "example": "10000.000000" }, "discountPct": { "type": "string", "nullable": true, "description": "Percentage discount applied to all charges under this contract (0-100, up to 2 decimal places)", "example": "15.00" }, "prepaidAmountUsdc": { "type": "string", "nullable": true, "description": "Total prepaid commit amount in USDC. This is the initial balance loaded into the contract.", "example": "1000.000000" }, "prepaidBalanceUsdc": { "type": "string", "nullable": true, "description": "Remaining prepaid balance in USDC. Decreases as charges are applied. When depleted, charges fall back to normal billing.", "example": "750.000000" }, "prepaidRollover": { "type": "boolean", "description": "Whether unused prepaid balance rolls over to the next billing period", "example": false }, "includedUnits": { "type": "object", "nullable": true, "additionalProperties": { "type": "number" }, "description": "Free unit allocations per usage type per billing period. Usage within these limits is not charged. Keys are unit types, values are quantities.", "example": { "api_call": 10000, "token": 1000000 } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Arbitrary key-value metadata for your own tracking (e.g., Salesforce deal ID, internal notes)", "example": { "salesforceId": "OPP-12345", "tier": "enterprise" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the contract was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the contract was last updated", "example": "2024-01-15T10:30:00.000Z" }, "priceOverrides": { "type": "array", "description": "Custom per-unit-type pricing that overrides default pricing plans for this customer", "items": { "type": "object", "description": "A per-unit-type price override within a contract. Overrides the default pricing plan rate for this customer.", "properties": { "id": { "type": "string", "description": "Unique identifier for the price override", "example": "cpo_abc123def456" }, "unitType": { "type": "string", "description": "The usage type this override applies to (must match a pricing plan `unitType`)", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Custom price per unit in USD (string for decimal precision, up to 6 decimal places)", "example": "0.000800" } }, "required": [ "id", "unitType", "unitPriceUsd" ] } } }, "required": [ "id", "businessId", "customerId", "name", "status", "startDate", "prepaidRollover", "createdAt", "updatedAt", "priceOverrides" ] } } } }, "400": { "description": "Contract is not in ACTIVE state, or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Contract is not in ACTIVE state, or validation error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized — missing or invalid API key" } } } }, "403": { "description": "Forbidden — API key does not have ADMIN role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Forbidden — API key does not have ADMIN role" } } } }, "404": { "description": "Contract not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Contract not found" } } } } } }, "delete": { "operationId": "cancelContract", "summary": "Cancel a contract", "tags": [ "Contracts" ], "description": "Cancel an active contract. Sets status to `CANCELLED`.\n\nCancellation is permanent — cancelled contracts cannot be reactivated. Any remaining prepaid balance is frozen. Price overrides from this contract stop applying to new charges immediately.\n\nAlready-cancelled contracts return a 400 error.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Contract ID" } ], "responses": { "200": { "description": "Contract cancelled successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Contract cancelled successfully", "properties": { "id": { "type": "string", "description": "Unique identifier for the contract", "example": "ctr_abc123def456" }, "businessId": { "type": "string", "description": "Business that owns this contract", "example": "biz_789xyz" }, "customerId": { "type": "string", "description": "Customer this contract applies to (must be created via POST /customers first)", "example": "cus_abc123def456" }, "name": { "type": "string", "description": "Human-readable name for the contract", "example": "Acme Corp Enterprise Agreement" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "EXPIRED", "CANCELLED" ], "description": "Current contract status. Only ACTIVE contracts affect billing. Transitions: ACTIVE → PAUSED, EXPIRED, or CANCELLED.", "example": "ACTIVE" }, "startDate": { "type": "string", "format": "date-time", "description": "When the contract takes effect (ISO 8601)", "example": "2024-01-01T00:00:00.000Z" }, "endDate": { "type": "string", "format": "date-time", "nullable": true, "description": "When the contract expires (ISO 8601). Null means the contract is perpetual.", "example": "2024-12-31T23:59:59.000Z" }, "minimumUsdc": { "type": "string", "nullable": true, "description": "Minimum committed spend in USDC for the contract period. If the customer spends less, they are still billed for the minimum.", "example": "500.000000" }, "maximumUsdc": { "type": "string", "nullable": true, "description": "Maximum spend cap in USDC for the contract period. Charges that would exceed this cap are blocked.", "example": "10000.000000" }, "discountPct": { "type": "string", "nullable": true, "description": "Percentage discount applied to all charges under this contract (0-100, up to 2 decimal places)", "example": "15.00" }, "prepaidAmountUsdc": { "type": "string", "nullable": true, "description": "Total prepaid commit amount in USDC. This is the initial balance loaded into the contract.", "example": "1000.000000" }, "prepaidBalanceUsdc": { "type": "string", "nullable": true, "description": "Remaining prepaid balance in USDC. Decreases as charges are applied. When depleted, charges fall back to normal billing.", "example": "750.000000" }, "prepaidRollover": { "type": "boolean", "description": "Whether unused prepaid balance rolls over to the next billing period", "example": false }, "includedUnits": { "type": "object", "nullable": true, "additionalProperties": { "type": "number" }, "description": "Free unit allocations per usage type per billing period. Usage within these limits is not charged. Keys are unit types, values are quantities.", "example": { "api_call": 10000, "token": 1000000 } }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Arbitrary key-value metadata for your own tracking (e.g., Salesforce deal ID, internal notes)", "example": { "salesforceId": "OPP-12345", "tier": "enterprise" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the contract was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the contract was last updated", "example": "2024-01-15T10:30:00.000Z" }, "priceOverrides": { "type": "array", "description": "Custom per-unit-type pricing that overrides default pricing plans for this customer", "items": { "type": "object", "description": "A per-unit-type price override within a contract. Overrides the default pricing plan rate for this customer.", "properties": { "id": { "type": "string", "description": "Unique identifier for the price override", "example": "cpo_abc123def456" }, "unitType": { "type": "string", "description": "The usage type this override applies to (must match a pricing plan `unitType`)", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Custom price per unit in USD (string for decimal precision, up to 6 decimal places)", "example": "0.000800" } }, "required": [ "id", "unitType", "unitPriceUsd" ] } } }, "required": [ "id", "businessId", "customerId", "name", "status", "startDate", "prepaidRollover", "createdAt", "updatedAt", "priceOverrides" ] } } } }, "400": { "description": "Contract is already cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Contract is already cancelled" } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized — missing or invalid API key" } } } }, "403": { "description": "Forbidden — API key does not have ADMIN role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Forbidden — API key does not have ADMIN role" } } } }, "404": { "description": "Contract not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Contract not found" } } } } } } }, "/v1/contracts/{id}/overrides": { "post": { "operationId": "addContractPriceOverride", "summary": "Add a price override", "tags": [ "Contracts" ], "description": "Add or update a per-unit-type price override on a contract.\n\nPrice overrides replace the default pricing plan rate for a specific usage type. For example, if your default `api_call` plan charges $0.001/call, a contract override of $0.0008/call gives this customer a negotiated enterprise rate.\n\nIf an override for the given `unitType` already exists, it is updated (upsert behavior). Only ACTIVE contracts accept new overrides.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Add or update a per-unit-type price override on a contract. If an override already exists for the given `unitType`, it is updated (upsert). Only ACTIVE contracts accept overrides.", "properties": { "unitType": { "type": "string", "minLength": 1, "description": "The usage type to override pricing for. Must match a `unitType` in your pricing plans (e.g., \"api_call\", \"token\").", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Custom price per unit in USD. Must be a non-negative number as a string (for decimal precision). Use \"0\" for free-tier overrides.", "example": "0.000800" } }, "required": [ "unitType", "unitPriceUsd" ] } } }, "description": "Add or update a per-unit-type price override on a contract. If an override already exists for the given `unitType`, it is updated (upsert). Only ACTIVE contracts accept overrides." }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Contract ID" } ], "responses": { "201": { "description": "Price override created or updated", "content": { "application/json": { "schema": { "type": "object", "description": "Price override created or updated", "properties": { "id": { "type": "string", "description": "Unique identifier for the price override", "example": "cpo_abc123def456" }, "unitType": { "type": "string", "description": "The usage type this override applies to (must match a pricing plan `unitType`)", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Custom price per unit in USD (string for decimal precision, up to 6 decimal places)", "example": "0.000800" } }, "required": [ "id", "unitType", "unitPriceUsd" ] } } } }, "400": { "description": "Contract is not in ACTIVE state, or validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Contract is not in ACTIVE state, or validation error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized — missing or invalid API key" } } } }, "403": { "description": "Forbidden — API key does not have ADMIN role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Forbidden — API key does not have ADMIN role" } } } }, "404": { "description": "Contract not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Contract not found" } } } } } } }, "/v1/contracts/{id}/overrides/{unitType}": { "delete": { "operationId": "removeContractPriceOverride", "summary": "Remove a price override", "tags": [ "Contracts" ], "description": "Remove a per-unit-type price override from a contract. After removal, the customer reverts to the default pricing plan rate for that usage type.\n\nThe `unitType` path parameter must exactly match the override's unit type (e.g., `api_call`).\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Contract ID" }, { "schema": { "type": "string" }, "in": "path", "name": "unitType", "required": true, "description": "Unit type to remove the override for (e.g., \"api_call\", \"token\")" } ], "responses": { "204": { "description": "Price override removed successfully" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Validation error" } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized — missing or invalid API key" } } } }, "403": { "description": "Forbidden — API key does not have ADMIN role", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Forbidden — API key does not have ADMIN role" } } } }, "404": { "description": "Contract or override not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Contract or override not found" } } } } } } }, "/v1/entitlement-plans": { "get": { "operationId": "listEntitlementPlans", "summary": "List entitlement plans", "tags": [ "Entitlements" ], "description": "Get all entitlement plans (tiers) for your business.", "responses": { "200": { "description": "List of entitlement plans", "content": { "application/json": { "schema": { "description": "List of entitlement plans", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } } } }, "post": { "operationId": "createEntitlementPlan", "summary": "Create an entitlement plan", "tags": [ "Entitlements" ], "description": "Create a new entitlement plan (tier) with feature rules.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_-]+$", "description": "URL-safe slug (lowercase alphanumeric, hyphens, underscores)" }, "description": { "type": "string" }, "isDefault": { "type": "boolean" } }, "required": [ "name", "slug" ] } } } }, "responses": { "201": { "description": "Plan created", "content": { "application/json": { "schema": { "description": "Plan created", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "409": { "description": "Slug already exists", "content": { "application/json": { "schema": { "description": "Slug already exists", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/v1/entitlement-plans/{id}": { "get": { "operationId": "getEntitlementPlan", "summary": "Get an entitlement plan", "tags": [ "Entitlements" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Entitlement plan", "content": { "application/json": { "schema": { "description": "Entitlement plan", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Not found" } } } } } }, "patch": { "operationId": "updateEntitlementPlan", "summary": "Update an entitlement plan", "tags": [ "Entitlements" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "isDefault": { "type": "boolean" }, "isActive": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Plan updated", "content": { "application/json": { "schema": { "description": "Plan updated", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Not found" } } } } } }, "delete": { "operationId": "deleteEntitlementPlan", "summary": "Delete an entitlement plan", "tags": [ "Entitlements" ], "description": "Soft-delete an entitlement plan by deactivating it.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "204": { "description": "Plan deleted", "content": { "application/json": { "schema": { "description": "Plan deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Not found" } } } } } } }, "/v1/entitlement-plans/{id}/versions": { "get": { "operationId": "listEntitlementPlanVersions", "summary": "List versions of an entitlement plan", "tags": [ "Entitlements" ], "description": "Return every row in the same `versionGroupId` as the given plan, ordered oldest → newest. Each version includes the rule set that was live at that version.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Version history", "content": { "application/json": { "schema": { "description": "Version history", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" }, "versionGroupId": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Not found" } } } } } } }, "/v1/entitlement-plans/{id}/rules": { "post": { "operationId": "createEntitlementRule", "summary": "Add a rule to a plan", "tags": [ "Entitlements" ], "description": "Add a feature limit rule to an entitlement plan.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "featureKey": { "type": "string", "minLength": 1 }, "limitType": { "type": "string", "enum": [ "COUNT", "AMOUNT" ] }, "period": { "type": "string", "enum": [ "DAILY", "MONTHLY" ] }, "limitValue": { "type": "number", "minimum": 0, "description": "Limit value (must be non-negative)" }, "unlimited": { "type": "boolean" } }, "required": [ "featureKey", "limitType", "period", "limitValue" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "201": { "description": "Rule created", "content": { "application/json": { "schema": { "description": "Rule created", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Plan not found" } } } }, "409": { "description": "Rule already exists", "content": { "application/json": { "schema": { "description": "Rule already exists", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } }, "get": { "operationId": "listEntitlementRules", "summary": "List rules for a plan", "tags": [ "Entitlements" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "List of rules", "content": { "application/json": { "schema": { "description": "List of rules", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Plan not found" } } } } } } }, "/v1/entitlement-rules/{ruleId}": { "patch": { "operationId": "updateEntitlementRule", "summary": "Update an entitlement rule", "tags": [ "Entitlements" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limitValue": { "type": "number" }, "unlimited": { "type": "boolean" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "ruleId", "required": true } ], "responses": { "200": { "description": "Rule updated", "content": { "application/json": { "schema": { "description": "Rule updated", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Not found" } } } } } }, "delete": { "operationId": "deleteEntitlementRule", "summary": "Delete an entitlement rule", "tags": [ "Entitlements" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "ruleId", "required": true } ], "responses": { "204": { "description": "Rule deleted", "content": { "application/json": { "schema": { "description": "Rule deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Not found" } } } } } } }, "/v1/customers/{customerId}/entitlement": { "get": { "operationId": "getCustomerEntitlement", "summary": "Get customer entitlement", "tags": [ "Entitlements" ], "description": "Get a customer's assigned plan and current usage.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "customerId", "required": true } ], "responses": { "200": { "description": "Customer entitlement with usage", "content": { "application/json": { "schema": { "description": "Customer entitlement with usage", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Customer not found" } } } } } }, "put": { "operationId": "assignCustomerEntitlement", "summary": "Assign entitlement plan to customer", "tags": [ "Entitlements" ], "description": "Assign or change a customer's entitlement plan.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "planId": { "type": "string" }, "overrides": { "type": "object" } }, "required": [ "planId" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "customerId", "required": true } ], "responses": { "200": { "description": "Entitlement assigned", "content": { "application/json": { "schema": { "description": "Entitlement assigned", "type": "object", "additionalProperties": true } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Customer or plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Customer or plan not found" } } } } } } }, "/v1/entitlements/check": { "post": { "operationId": "checkEntitlement", "summary": "Check entitlement", "tags": [ "Entitlements" ], "description": "\nFast pre-request check: is this customer allowed to use this feature?\n\nReturns `allowed: true/false` with remaining quota. Use this before processing\nexpensive requests to avoid wasting compute on customers who are over quota.\n\nRedis-backed hot-path with DB fallback for persisted usage events.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Customer ID" }, "featureKey": { "type": "string", "description": "Feature/meter key (e.g., \"search\", \"api_calls\")" }, "quantity": { "type": "number", "description": "Quantity to check (default: 1)" } }, "required": [ "customerId", "featureKey" ] } } } }, "responses": { "200": { "description": "Entitlement check result", "content": { "application/json": { "schema": { "description": "Entitlement check result", "type": "object", "properties": { "allowed": { "type": "boolean" }, "featureKey": { "type": "string" }, "remaining": { "type": "number" }, "limit": { "type": "number" }, "unlimited": { "type": "boolean" }, "period": { "type": "string", "enum": [ "DAILY", "MONTHLY" ] }, "periodResetsAt": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Customer not found" } } } } } } }, "/v1/customers/{customerId}/entitlement/usage": { "get": { "operationId": "getCustomerEntitlementUsage", "summary": "Get customer entitlement usage", "tags": [ "Entitlements" ], "description": "Get current period usage vs limits for all features in a customer's plan.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "customerId", "required": true } ], "responses": { "200": { "description": "Usage summary per feature", "content": { "application/json": { "schema": { "description": "Usage summary per feature", "type": "object", "properties": { "customerId": { "type": "string" }, "usage": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Customer not found" } } } } } } }, "/v1/cost-estimate/from-usage": { "post": { "operationId": "estimateCostsFromUsage", "summary": "Estimate costs from existing usage", "tags": [ "Charges" ], "description": "\nEstimate costs from existing usage events without creating charges.\n\nQueries usage events in the specified period and calculates what they would cost\nbased on pricing plans. Supports custom pricing overrides for \"what-if\" scenarios.\n\n**Use cases:**\n- Budget planning and forecasting\n- Cost allocation previews\n- Retroactive pricing analysis\n- Comparing pricing strategies\n\nThe response includes per-usage-type line items with quantity, unit price,\nand estimated cost. Notes indicate which usage types used custom pricing,\ndefault pricing, or had no pricing plan available.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "periodStart", "periodEnd" ], "properties": { "customerId": { "type": "string", "description": "Filter to a specific customer. Omit to estimate across all customers." }, "periodStart": { "type": "string", "format": "date-time", "description": "Start of the estimation period (ISO 8601)", "example": "2024-01-01T00:00:00.000Z" }, "periodEnd": { "type": "string", "format": "date-time", "description": "End of the estimation period (ISO 8601)", "example": "2024-01-31T23:59:59.999Z" }, "defaultUnitPrice": { "type": "string", "description": "Default unit price (USDC) for usage types without a pricing plan", "example": "0.001" }, "includeChargedEvents": { "type": "boolean", "description": "Include events that already have charges (default: true)", "default": true }, "usageTypes": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific usage types" }, "customPricing": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom pricing overrides: usageType → unitPrice. Takes precedence over DB pricing plans.", "example": { "api_call": "0.005", "token": "0.0001" } } } } } } }, "responses": { "200": { "description": "Cost estimate with line item breakdown", "content": { "application/json": { "schema": { "type": "object", "description": "Cost estimate with line item breakdown", "properties": { "businessId": { "type": "string" }, "customerId": { "type": "string" }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "usageType": { "type": "string" }, "quantity": { "type": "string" }, "unitPrice": { "type": "string" }, "estimatedCostUsdc": { "type": "string" }, "eventCount": { "type": "integer" }, "hasPricingPlan": { "type": "boolean" } } } }, "subtotalUsdc": { "type": "string" }, "estimatedTotalUsdc": { "type": "string" }, "currency": { "type": "string", "enum": [ "USDC" ] }, "isEstimate": { "type": "boolean", "enum": [ true ] }, "generatedAt": { "type": "string", "format": "date-time" }, "notes": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "description": "Invalid request parameters", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Missing or invalid API key", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/cost-estimate/hypothetical": { "post": { "operationId": "estimateCostsFromHypothetical", "summary": "Estimate costs from hypothetical usage", "tags": [ "Charges" ], "description": "\nEstimate costs from hypothetical usage without creating charges.\n\nTakes a list of usage items (type + quantity) and calculates what they would\ncost based on your pricing plans. Useful for \"what-if\" scenarios, budget\nplanning, or previewing costs before usage occurs.\n\n**Use cases:**\n- Pre-execution cost preview for AI agents\n- Budget planning with different pricing scenarios\n- Customer-facing cost calculators\n- Comparing pricing strategies side by side\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "description": "Hypothetical usage items to estimate", "items": { "type": "object", "required": [ "usageType", "quantity" ], "properties": { "usageType": { "type": "string", "minLength": 1, "description": "Usage type (must match a pricing plan for accurate estimates)", "example": "api_call" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Hypothetical quantity", "example": 10000 }, "unitPriceOverride": { "type": "string", "description": "Override unit price for this item (USDC)", "example": "0.005" } } } }, "defaultUnitPrice": { "type": "string", "description": "Default unit price (USDC) for usage types without a pricing plan", "example": "0.001" }, "customPricing": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom pricing overrides: usageType → unitPrice. Takes precedence over DB pricing plans.", "example": { "api_call": "0.005", "token": "0.0001" } } } } } } }, "responses": { "200": { "description": "Cost estimate with line item breakdown", "content": { "application/json": { "schema": { "type": "object", "description": "Cost estimate with line item breakdown", "properties": { "businessId": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "usageType": { "type": "string" }, "quantity": { "type": "string" }, "unitPrice": { "type": "string" }, "estimatedCostUsdc": { "type": "string" }, "hasPricingPlan": { "type": "boolean" } } } }, "subtotalUsdc": { "type": "string" }, "estimatedTotalUsdc": { "type": "string" }, "currency": { "type": "string", "enum": [ "USDC" ] }, "isEstimate": { "type": "boolean", "enum": [ true ] }, "generatedAt": { "type": "string", "format": "date-time" }, "notes": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "description": "Invalid request parameters", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "description": "Missing or invalid API key", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "description": "Rate limit exceeded", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/invoices/generate": { "post": { "operationId": "generateInvoice", "summary": "Generate invoice from charges", "tags": [ "Invoices" ], "description": "\nGenerate an invoice from charges within a billing period.\nAutomatically aggregates charges by usage type into line items.\n\nThe invoice is created in DRAFT status. Use the issue endpoint to finalize it.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customerId", "periodStart", "periodEnd" ], "properties": { "customerId": { "type": "string", "description": "Customer ID to generate invoice for" }, "periodStart": { "type": "string", "format": "date-time", "description": "Start of billing period (ISO 8601)" }, "periodEnd": { "type": "string", "format": "date-time", "description": "End of billing period (ISO 8601)" }, "dueDate": { "type": "string", "format": "date-time", "description": "Payment due date (ISO 8601)" }, "includeSettledOnly": { "type": "boolean", "default": false, "description": "Only include settled (confirmed) charges" }, "notes": { "type": "string", "maxLength": 2000, "description": "Internal notes (not visible to customer)" }, "customerNotes": { "type": "string", "maxLength": 2000, "description": "Notes visible to customer on invoice" } } } } } }, "responses": { "201": { "description": "Invoice generated successfully", "content": { "application/json": { "schema": { "description": "Invoice generated successfully", "type": "object", "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": "string" }, "customerId": { "type": "string" }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "totalUsdc": { "type": "string" }, "status": { "type": "string" }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "description": { "type": "string" }, "usageType": { "type": "string" }, "quantity": { "type": "string" }, "unitPrice": { "type": "string" }, "amountUsdc": { "type": "string" } } } }, "createdAt": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Customer not found", "content": { "application/json": { "schema": { "description": "Customer not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/invoices/generate-from-subscription": { "post": { "operationId": "generateInvoiceFromSubscription", "summary": "Generate invoice from subscription", "tags": [ "Invoices" ], "description": "\nGenerate an invoice for a subscription billing period.\nSupports prorated amounts for partial periods (mid-cycle starts, cancellations, upgrades/downgrades).\nOptionally includes usage charges from the same period.\n\nThe invoice is created in DRAFT status. Use the issue endpoint to finalize it.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customerId", "subscriptionId" ], "properties": { "customerId": { "type": "string", "description": "Customer ID" }, "subscriptionId": { "type": "string", "description": "Subscription ID" }, "periodStart": { "type": "string", "format": "date-time", "description": "Override period start (ISO 8601)" }, "periodEnd": { "type": "string", "format": "date-time", "description": "Override period end (ISO 8601)" }, "dueDate": { "type": "string", "format": "date-time", "description": "Payment due date (ISO 8601)" }, "notes": { "type": "string", "maxLength": 2000 }, "customerNotes": { "type": "string", "maxLength": 2000 }, "includeUsageCharges": { "type": "boolean", "default": false, "description": "Bundle usage charges in the same invoice" } } } } } }, "responses": { "201": { "description": "Invoice generated", "content": { "application/json": { "schema": { "description": "Invoice generated", "type": "object", "additionalProperties": true } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "description": "Validation error", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "description": "Not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/invoices": { "get": { "operationId": "listInvoices", "summary": "List invoices", "tags": [ "Invoices" ], "description": "Retrieve all invoices for your business with optional filtering.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "customerId", "required": false, "description": "Filter by customer ID" }, { "schema": { "type": "string", "enum": [ "DRAFT", "PENDING", "PAID", "PARTIALLY_PAID", "VOIDED", "OVERDUE" ] }, "in": "query", "name": "status", "required": false, "description": "Filter by status" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "startDate", "required": false, "description": "Filter by created date (from)" }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "endDate", "required": false, "description": "Filter by created date (to)" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "integer", "minimum": 0, "default": 0 }, "in": "query", "name": "offset", "required": false } ], "responses": { "200": { "description": "List of invoices", "content": { "application/json": { "schema": { "description": "List of invoices", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/invoices/{id}": { "get": { "operationId": "getInvoice", "summary": "Get invoice", "tags": [ "Invoices" ], "description": "Retrieve a specific invoice by ID.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Invoice ID" } ], "responses": { "200": { "description": "Invoice details", "content": { "application/json": { "schema": { "description": "Invoice details", "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "description": "Invoice not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "patch": { "operationId": "updateInvoice", "summary": "Update mutable invoice fields (DRAFT only)", "tags": [ "Invoices" ], "description": "Update NET terms, PO number, payment terms label, internal notes, or customer notes on a DRAFT invoice. Once issued, these fields are frozen.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/invoices/{id}/line-items": { "post": { "operationId": "addInvoiceLineItem", "summary": "Add an ad-hoc line item to a draft invoice", "tags": [ "Invoices" ], "description": "Append a one-off line item (setup fee, services rendered, manual adjustment) to a DRAFT invoice. Only allowed on DRAFT invoices — once issued, line items are immutable; use credit notes for corrections.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/invoices/{id}/issue": { "post": { "operationId": "issueInvoice", "summary": "Issue invoice", "tags": [ "Invoices" ], "description": "Finalize a draft invoice and mark it as pending payment.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Invoice ID" } ], "responses": { "200": { "description": "Invoice issued", "content": { "application/json": { "schema": { "description": "Invoice issued", "type": "object" } } } }, "400": { "description": "Invalid status", "content": { "application/json": { "schema": { "description": "Invalid status", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "description": "Invoice not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/invoices/{id}/paid": { "post": { "operationId": "markInvoicePaid", "summary": "Mark invoice as paid", "tags": [ "Invoices" ], "description": "\nMark an invoice as paid. If amount is not provided, the full remaining balance is marked as paid.\nPartial payments can be recorded by specifying an amount.\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "description": "Amount paid in USDC (optional, defaults to full balance)" }, "force": { "type": "boolean", "description": "Override payment terms enforcement (requires OWNER role)" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Invoice ID" } ], "responses": { "200": { "description": "Invoice marked as paid", "content": { "application/json": { "schema": { "description": "Invoice marked as paid", "type": "object" } } } }, "400": { "description": "Invalid status or amount", "content": { "application/json": { "schema": { "description": "Invalid status or amount", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "description": "Invoice not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "422": { "description": "Payment terms not yet elapsed", "content": { "application/json": { "schema": { "description": "Payment terms not yet elapsed", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/invoices/{id}/void": { "post": { "operationId": "voidInvoice", "summary": "Void invoice", "tags": [ "Invoices" ], "description": "Cancel an invoice. Cannot void invoices that have been paid.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "minLength": 10, "maxLength": 1000, "description": "Reason for voiding the invoice" } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Invoice ID" } ], "responses": { "200": { "description": "Invoice voided", "content": { "application/json": { "schema": { "description": "Invoice voided", "type": "object" } } } }, "400": { "description": "Invalid status", "content": { "application/json": { "schema": { "description": "Invalid status", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "description": "Invoice not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/invoices/summary": { "get": { "operationId": "getInvoiceSummary", "summary": "Get invoice summary", "tags": [ "Invoices" ], "description": "Get aggregated invoice statistics for your business.", "responses": { "200": { "description": "Invoice summary", "content": { "application/json": { "schema": { "description": "Invoice summary", "type": "object", "properties": { "totalInvoices": { "type": "integer" }, "totalAmountUsdc": { "type": "string" }, "paidAmountUsdc": { "type": "string" }, "pendingAmountUsdc": { "type": "string" }, "overdueAmountUsdc": { "type": "string" }, "byStatus": { "type": "object", "properties": { "DRAFT": { "type": "integer" }, "PENDING": { "type": "integer" }, "PAID": { "type": "integer" }, "PARTIALLY_PAID": { "type": "integer" }, "VOIDED": { "type": "integer" }, "OVERDUE": { "type": "integer" } } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/invoices/{id}/pdf": { "get": { "operationId": "getInvoicePdf", "summary": "Download invoice PDF", "tags": [ "Invoices" ], "description": "Generate and download a PDF version of the invoice.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Invoice ID" } ], "responses": { "200": { "description": "PDF file", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "description": "Invoice not found", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } } }, "/v1/credit-notes": { "post": { "operationId": "createCreditNote", "summary": "Create a draft credit note", "tags": [ "Credit Notes" ], "description": "\nCreate a credit note in DRAFT status against an existing invoice. The credit\nnote is not applied to the invoice until you call POST /credit-notes/:id/issue.\n\nRequired for refunds, corrections, and post-issuance adjustments — especially\nin EU/LATAM jurisdictions where simply voiding an invoice is not legally\nsufficient.\n\nValidates that:\n- the invoice exists and belongs to the business\n- the invoice is not in DRAFT or VOIDED status\n- the credit note total does not exceed the remaining invoice value\n ", "responses": { "200": { "description": "Default Response" } } }, "get": { "operationId": "listCreditNotes", "summary": "List credit notes", "tags": [ "Credit Notes" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/credit-notes/{id}": { "get": { "operationId": "getCreditNote", "summary": "Get a credit note", "tags": [ "Credit Notes" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/credit-notes/{id}/issue": { "post": { "operationId": "issueCreditNote", "summary": "Issue a draft credit note", "tags": [ "Credit Notes" ], "description": "Apply a DRAFT credit note to its invoice. Increments invoice.adjustmentsUsdc and recomputes invoice status. Idempotent: returns 409 if the credit note is not in DRAFT status.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/credit-notes/{id}/void": { "post": { "operationId": "voidCreditNote", "summary": "Void a credit note", "tags": [ "Credit Notes" ], "description": "Voiding an ISSUED credit note reverses its application to the invoice. Voiding a DRAFT credit note is a no-op cleanup. Requires a reason of at least 5 characters.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/coupons": { "post": { "operationId": "createCoupon", "summary": "Create a coupon", "tags": [ "Coupons" ], "responses": { "200": { "description": "Default Response" } } }, "get": { "operationId": "listCoupons", "summary": "List coupons", "tags": [ "Coupons" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/coupons/{id}": { "get": { "operationId": "getCoupon", "summary": "Get a coupon", "tags": [ "Coupons" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "deactivateCoupon", "summary": "Deactivate a coupon (soft delete)", "tags": [ "Coupons" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/promotion-codes": { "post": { "operationId": "createPromotionCode", "summary": "Create a promotion code", "tags": [ "Coupons" ], "responses": { "200": { "description": "Default Response" } } }, "get": { "operationId": "listPromotionCodes", "summary": "List promotion codes", "tags": [ "Coupons" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/promotion-codes/redeem": { "post": { "operationId": "redeemPromotionCode", "summary": "Redeem a promotion code against a charge or invoice", "tags": [ "Coupons" ], "description": "\nApply a promotion code to a gross amount. Returns the discount amount, the\nnew net amount, and the redemption record. Increments the redeem counters\non both the coupon and the promotion code atomically.\n\nValidates: code exists, coupon active, within validity window, not at\nredemption cap (global, per-code, per-customer), and (if restricted)\nmatches the redeeming customer.\n ", "responses": { "200": { "description": "Default Response" } } } }, "/v1/subscriptions/{id}/upcoming-invoice": { "get": { "operationId": "getUpcomingInvoice", "summary": "Preview the upcoming invoice for a subscription", "tags": [ "Invoices" ], "description": "\nComputes what the customer's next invoice will look like, including any\nusage charges accumulated so far in the current billing period. Read-only —\nno charges, invoices, or line items are persisted.\n\nTax is computed using the same pipeline as the real invoice generator, so\nSTRIPE_TAX merchants get accurate previews (at the cost of a tiny Stripe\nTax usage call).\n\nReturns 409 NOT_BILLABLE when the subscription is paused, cancelled, or\nalready past its period end.\n ", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/invoices/preview": { "post": { "operationId": "previewInvoice", "summary": "Preview an invoice for a customer over an arbitrary period", "tags": [ "Invoices" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/dunning/schedule": { "get": { "operationId": "getDunningSchedule", "summary": "Get the active dunning schedule", "tags": [ "Dunning" ], "description": "Returns the per-business retry schedule. Falls back to the system default when no custom schedule is configured.", "responses": { "200": { "description": "Default Response" } } }, "put": { "operationId": "upsertDunningSchedule", "summary": "Upsert the dunning schedule for this business", "tags": [ "Dunning" ], "description": "Create or replace the retry schedule. `retries` is an ordered list of steps, each with a `dayOffset` (days after `firstFailedAt`), a `retryPayment` flag, and an optional `emailTemplate` (`dunning_first_notice` | `dunning_second_notice` | `dunning_final_notice`). Steps must be strictly increasing by `dayOffset`. Set `isActive: false` to disable automatic retries without losing the schedule — manual retries via `POST /collections/{id}/retry` still work.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/collections": { "get": { "operationId": "listCollections", "summary": "List failed payments in collections", "tags": [ "Dunning" ], "description": "Returns failed charges currently in the dunning pipeline. Filter by `status` (`OPEN`, `RETRYING`, `RESOLVED`, `ABANDONED`, `CANCELLED`) and/or `customerId`. Each row includes `retryAttempts`, `nextRetryAt`, and `lastRetryError` so you can surface collections state in your own UI.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/collections/{id}": { "get": { "operationId": "getCollection", "summary": "Get a single failed payment", "tags": [ "Dunning" ], "description": "Returns full detail for one failed payment, including the underlying charge, customer, retry history, schedule snapshot, and resolution metadata.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/collections/{id}/retry": { "post": { "operationId": "retryCollection", "summary": "Manually retry a failed payment", "tags": [ "Dunning" ], "description": "Shares the same logic as the scheduled dunning worker. Manual retries work even when the scheduler is disabled (isActive=false).", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/address": { "put": { "operationId": "setCustomerAddress", "summary": "Set a customer's billing address", "tags": [ "Tax" ], "description": "Set or replace the customer's billing address. Triggers address validation via the configured provider (default: format-only). Requires an ADMIN secret key.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "get": { "operationId": "getCustomerAddress", "summary": "Get the customer's stored address", "tags": [ "Tax" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "removeCustomerAddress", "summary": "Remove the customer's address", "tags": [ "Tax" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/tax-exemption": { "post": { "operationId": "createCustomerTaxExemption", "summary": "Create a customer tax exemption", "tags": [ "Tax" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/tax-exemptions": { "get": { "operationId": "listCustomerTaxExemptions", "summary": "List active tax exemptions for a customer", "tags": [ "Tax" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/tax-exemptions/{eid}": { "delete": { "operationId": "removeCustomerTaxExemption", "summary": "Deactivate a customer tax exemption", "tags": [ "Tax" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "eid", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/customers/{id}/tax-preview": { "post": { "operationId": "previewCustomerTax", "summary": "Preview tax for a hypothetical charge amount", "tags": [ "Tax" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/tax-registrations": { "post": { "operationId": "createTaxRegistration", "summary": "Create a tax registration for the business", "tags": [ "Tax" ], "responses": { "200": { "description": "Default Response" } } }, "get": { "operationId": "listTaxRegistrations", "summary": "List active tax registrations for the business", "tags": [ "Tax" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/tax-registrations/{id}": { "delete": { "operationId": "removeTaxRegistration", "summary": "Deactivate a tax registration", "tags": [ "Tax" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/tax-rates": { "get": { "operationId": "listTaxRates", "summary": "List the seeded global tax rate catalogue", "tags": [ "Tax" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/tax-config/readiness": { "get": { "operationId": "getTaxConfigReadiness", "summary": "Check whether the merchant's tax configuration is production-ready", "tags": [ "Tax" ], "description": "Returns a structured report of the merchant's tax setup: active registrations, customer address coverage, uncovered jurisdictions, and actionable warnings with stable codes. Non-enforcing — merchants can always bill; this is a configuration quality check, not a gate.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/product-categories": { "get": { "operationId": "listProductCategories", "summary": "List product categories", "tags": [ "Product Categories" ], "description": "Return the controlled taxonomy used for strict-products governance. Includes archived categories by default so dashboards can render historical tags.", "parameters": [ { "schema": { "type": "boolean" }, "in": "query", "name": "includeArchived", "required": false, "description": "Include soft-archived categories. Defaults to true." } ], "responses": { "200": { "description": "Default Response" } } }, "post": { "operationId": "createProductCategory", "summary": "Create a product category", "tags": [ "Product Categories" ], "description": "Create a new product category. `key` must be unique per business and is immutable once created — downstream reporting rolls up by key.", "responses": { "200": { "description": "Default Response" } } } }, "/v1/product-categories/{id}": { "patch": { "operationId": "updateProductCategory", "summary": "Update a product category", "tags": [ "Product Categories" ], "description": "Update the name, description, GL code, or revenue class of a product category. The `key` is immutable — create a new category if the taxonomy needs to split.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "operationId": "archiveProductCategory", "summary": "Archive a product category", "tags": [ "Product Categories" ], "description": "Soft-archive the category. Archived categories cannot be attached to new pricing plans but stay linked to historical ones so reporting is stable. To restore, PATCH `archivedAt` back to null via the un-archive endpoint is NOT exposed — recreate a new category or use PATCH if un-archive support is added later.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/pricing-plans": { "get": { "operationId": "listPricingPlans", "summary": "List pricing plans", "tags": [ "Pricing Plans" ], "description": "Get all pricing plans for your business.", "responses": { "200": { "description": "List of pricing plans", "content": { "application/json": { "schema": { "description": "List of pricing plans", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A pricing plan defines how much to charge per unit of usage.", "properties": { "id": { "type": "string", "description": "Unique identifier for the pricing plan", "example": "plan_abc123def456" }, "businessId": { "type": "string", "description": "Business this plan belongs to", "example": "biz_789xyz" }, "name": { "type": "string", "description": "Human-readable name for the plan", "example": "API Calls" }, "unitType": { "type": "string", "description": "The usage type this plan prices (e.g., \"api_call\", \"token\", \"compute_second\", \"gb_storage\")", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Default (FLAT) price per unit in USD. For TIERED/VOLUME/PACKAGE plans, consult `tiers`. For PER_SEAT plans, this is the price per seat per billing period.", "example": "0.001000" }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth: the billing engine reads it directly and converts to USD via FxRate at charge time.", "example": "0.000920" }, "currency": { "type": "string", "enum": [ "USD", "USDC", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "SGD", "HKD", "ILS", "NZD", "SEK", "NOK", "DKK", "MXN", "BRL", "INR", "ZAR", "PLN" ], "description": "Billing currency for the plan. Defaults to USD. For non-USD currencies, supply `unitPrice` (and tier `unitPrice`/`flatFee`); the billing engine uses those as the source of truth and converts to USD via FxRate at charge time.", "example": "USD" }, "pricingModel": { "type": "string", "enum": [ "FLAT", "TIERED", "VOLUME", "PACKAGE", "PER_SEAT" ], "description": "How quantity maps to charge amount:\n- `FLAT`: quantity × unitPrice (default)\n- `TIERED`: graduated, first N at price A, next M at price B, etc.\n- `VOLUME`: total quantity determines a single rate applied to all units\n- `PACKAGE`: charge per package of N units (rounds up partial packages)\n- `PER_SEAT`: per-seat/user licensing. quantity is the seat count, charged at unitPrice per seat per billing period (no tiers)", "example": "FLAT" }, "tiers": { "type": "array", "description": "Tier definitions. Empty for FLAT and PER_SEAT plans; required for TIERED/VOLUME/PACKAGE.", "items": { "type": "object", "description": "A tier defines a price bracket for TIERED, VOLUME, or PACKAGE pricing.", "properties": { "id": { "type": "string", "description": "Tier ID (present on existing tiers)" }, "minQuantity": { "type": "string", "description": "Tier starts at this quantity (inclusive). First tier must be 0.", "example": "0" }, "maxQuantity": { "type": [ "null", "string" ], "description": "Tier ends at this quantity (exclusive). Null on the final unbounded tier.", "example": "1000" }, "unitPriceUsd": { "type": "string", "description": "Price per unit in this tier (USD)", "example": "0.001000" }, "flatFeeUsd": { "type": [ "null", "string" ], "description": "Optional flat fee added when this tier is reached", "example": null }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth and the legacy unitPriceUsd is ignored by the billing engine.", "example": "0.000920" }, "flatFee": { "type": [ "null", "string" ], "description": "Native-currency flat fee. Populated only for non-USD plans (mirror of flatFeeUsd).", "example": null }, "packageSize": { "type": [ "null", "integer" ], "description": "For PACKAGE model: number of units in one billable package", "example": 1000 } }, "required": [ "minQuantity", "unitPriceUsd" ] } }, "creditsPerUnit": { "type": [ "null", "string" ], "description": "Credits consumed per unit of usage. When set, usage is deducted from the customer's credit wallet instead of charging USD.", "example": "10" }, "productCategoryId": { "type": [ "null", "string" ], "description": "Optional product category tag used by 'strict products' mode to roll up reporting by service line. Null when the plan is untagged. When `Business.strictProducts` is true, this must be populated via the category id or key.", "example": "cat_core" }, "isActive": { "type": "boolean", "description": "Whether this plan is active. Only active plans are used for new charges.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "description": "When the plan was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the plan was last updated", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "name", "unitType", "unitPriceUsd", "pricingModel", "tiers", "isActive" ] } }, "count": { "type": "integer" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "description": "Unauthorized", "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ] } } } } } }, "post": { "operationId": "createPricingPlan", "summary": "Create a pricing plan", "tags": [ "Pricing Plans" ], "description": "\nCreate a new pricing plan for a usage type.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.** Public keys and lower-role secret keys will receive `403 Forbidden`.\n\nEach `unitType` can only have one active pricing plan. If you need to\nchange prices, update the existing plan or deactivate it first.\n\n**Example unit types:**\n- `api_call` - Per API request\n- `token` - Per token processed\n- `compute_second` - Per second of compute\n- `gb_storage` - Per GB stored\n ", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Request body for creating a new pricing plan.", "properties": { "name": { "type": "string", "minLength": 1, "description": "Human-readable name for the plan (required)", "example": "API Calls" }, "unitType": { "type": "string", "minLength": 1, "description": "The usage type to price. Must be unique per business. Examples: \"api_call\", \"token\", \"compute_second\", \"gb_storage\"", "example": "api_call" }, "unitPriceUsd": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000, "description": "Default (FLAT) price per unit in USD. Required even for tiered plans as a fallback.", "example": 0.001 }, "unitPrice": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000, "description": "Native-currency price per unit. Required when `currency` is non-USD/USDC. The billing engine uses this as the source of truth and converts to USD via FxRate at charge time.", "example": 0.0037 }, "currency": { "type": "string", "enum": [ "USD", "USDC", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "SGD", "HKD", "ILS", "NZD", "SEK", "NOK", "DKK", "MXN", "BRL", "INR", "ZAR", "PLN" ], "description": "Billing currency for the plan (default: USD). Non-USD plans require `unitPrice`.", "example": "USD" }, "isActive": { "type": "boolean", "description": "Whether to activate the plan immediately (default: true)", "example": true }, "pricingModel": { "type": "string", "enum": [ "FLAT", "TIERED", "VOLUME", "PACKAGE", "PER_SEAT" ], "description": "How quantity maps to charge amount (default: FLAT)", "example": "FLAT" }, "creditsPerUnit": { "type": "number", "exclusiveMinimum": 0, "description": "Credits consumed per unit of usage. When set, usage is deducted from the customer's credit wallet instead of charging USD.", "example": 10 }, "productCategoryId": { "type": "string", "description": "Optional product category id. When `Business.strictProducts` is true, either this or `productCategoryKey` is required.", "example": "cat_core" }, "productCategoryKey": { "type": "string", "description": "Optional product category slug (e.g. 'core_api'). Resolved server-side to the matching id. Mutually exclusive with `productCategoryId`.", "example": "core_api" }, "tiers": { "type": "array", "description": "Tier definitions. Must be omitted/empty for FLAT and PER_SEAT. Required for TIERED/VOLUME/PACKAGE. Tiers must be contiguous (tier N.max == tier N+1.min) and the first tier must start at 0.", "items": { "type": "object", "properties": { "minQuantity": { "type": "number", "minimum": 0 }, "maxQuantity": { "type": [ "number", "null" ] }, "unitPriceUsd": { "type": "number", "minimum": 0, "maximum": 1000000 }, "flatFeeUsd": { "type": [ "number", "null" ] }, "unitPrice": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1000000 }, "flatFee": { "type": [ "number", "null" ], "minimum": 0 }, "packageSize": { "type": [ "integer", "null" ] } }, "required": [ "minQuantity", "unitPriceUsd" ] } } }, "required": [ "name", "unitType", "unitPriceUsd" ] } } }, "description": "Request body for creating a new pricing plan." }, "responses": { "201": { "description": "Pricing plan created", "content": { "application/json": { "schema": { "type": "object", "description": "Pricing plan created", "properties": { "id": { "type": "string", "description": "Unique identifier for the pricing plan", "example": "plan_abc123def456" }, "businessId": { "type": "string", "description": "Business this plan belongs to", "example": "biz_789xyz" }, "name": { "type": "string", "description": "Human-readable name for the plan", "example": "API Calls" }, "unitType": { "type": "string", "description": "The usage type this plan prices (e.g., \"api_call\", \"token\", \"compute_second\", \"gb_storage\")", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Default (FLAT) price per unit in USD. For TIERED/VOLUME/PACKAGE plans, consult `tiers`. For PER_SEAT plans, this is the price per seat per billing period.", "example": "0.001000" }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth: the billing engine reads it directly and converts to USD via FxRate at charge time.", "example": "0.000920" }, "currency": { "type": "string", "enum": [ "USD", "USDC", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "SGD", "HKD", "ILS", "NZD", "SEK", "NOK", "DKK", "MXN", "BRL", "INR", "ZAR", "PLN" ], "description": "Billing currency for the plan. Defaults to USD. For non-USD currencies, supply `unitPrice` (and tier `unitPrice`/`flatFee`); the billing engine uses those as the source of truth and converts to USD via FxRate at charge time.", "example": "USD" }, "pricingModel": { "type": "string", "enum": [ "FLAT", "TIERED", "VOLUME", "PACKAGE", "PER_SEAT" ], "description": "How quantity maps to charge amount:\n- `FLAT`: quantity × unitPrice (default)\n- `TIERED`: graduated, first N at price A, next M at price B, etc.\n- `VOLUME`: total quantity determines a single rate applied to all units\n- `PACKAGE`: charge per package of N units (rounds up partial packages)\n- `PER_SEAT`: per-seat/user licensing. quantity is the seat count, charged at unitPrice per seat per billing period (no tiers)", "example": "FLAT" }, "tiers": { "type": "array", "description": "Tier definitions. Empty for FLAT and PER_SEAT plans; required for TIERED/VOLUME/PACKAGE.", "items": { "type": "object", "description": "A tier defines a price bracket for TIERED, VOLUME, or PACKAGE pricing.", "properties": { "id": { "type": "string", "description": "Tier ID (present on existing tiers)" }, "minQuantity": { "type": "string", "description": "Tier starts at this quantity (inclusive). First tier must be 0.", "example": "0" }, "maxQuantity": { "type": [ "null", "string" ], "description": "Tier ends at this quantity (exclusive). Null on the final unbounded tier.", "example": "1000" }, "unitPriceUsd": { "type": "string", "description": "Price per unit in this tier (USD)", "example": "0.001000" }, "flatFeeUsd": { "type": [ "null", "string" ], "description": "Optional flat fee added when this tier is reached", "example": null }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth and the legacy unitPriceUsd is ignored by the billing engine.", "example": "0.000920" }, "flatFee": { "type": [ "null", "string" ], "description": "Native-currency flat fee. Populated only for non-USD plans (mirror of flatFeeUsd).", "example": null }, "packageSize": { "type": [ "null", "integer" ], "description": "For PACKAGE model: number of units in one billable package", "example": 1000 } }, "required": [ "minQuantity", "unitPriceUsd" ] } }, "creditsPerUnit": { "type": [ "null", "string" ], "description": "Credits consumed per unit of usage. When set, usage is deducted from the customer's credit wallet instead of charging USD.", "example": "10" }, "productCategoryId": { "type": [ "null", "string" ], "description": "Optional product category tag used by 'strict products' mode to roll up reporting by service line. Null when the plan is untagged. When `Business.strictProducts` is true, this must be populated via the category id or key.", "example": "cat_core" }, "isActive": { "type": "boolean", "description": "Whether this plan is active. Only active plans are used for new charges.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "description": "When the plan was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the plan was last updated", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "name", "unitType", "unitPriceUsd", "pricingModel", "tiers", "isActive" ] } } } }, "400": { "description": "Invalid tier configuration", "content": { "application/json": { "schema": { "description": "Invalid tier configuration", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "INVALID_TIERS" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "409": { "description": "Pricing plan for unit type already exists", "content": { "application/json": { "schema": { "description": "Pricing plan for unit type already exists", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "DUPLICATE_PRICING_PLAN" }, "existingPlanId": { "type": "string" } } } } } } } } }, "/v1/pricing-plans/{id}": { "get": { "operationId": "getPricingPlan", "summary": "Get a pricing plan", "tags": [ "Pricing Plans" ], "description": "Retrieve a pricing plan by ID.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Pricing plan ID" } ], "responses": { "200": { "description": "Pricing plan details", "content": { "application/json": { "schema": { "type": "object", "description": "Pricing plan details", "properties": { "id": { "type": "string", "description": "Unique identifier for the pricing plan", "example": "plan_abc123def456" }, "businessId": { "type": "string", "description": "Business this plan belongs to", "example": "biz_789xyz" }, "name": { "type": "string", "description": "Human-readable name for the plan", "example": "API Calls" }, "unitType": { "type": "string", "description": "The usage type this plan prices (e.g., \"api_call\", \"token\", \"compute_second\", \"gb_storage\")", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Default (FLAT) price per unit in USD. For TIERED/VOLUME/PACKAGE plans, consult `tiers`. For PER_SEAT plans, this is the price per seat per billing period.", "example": "0.001000" }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth: the billing engine reads it directly and converts to USD via FxRate at charge time.", "example": "0.000920" }, "currency": { "type": "string", "enum": [ "USD", "USDC", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "SGD", "HKD", "ILS", "NZD", "SEK", "NOK", "DKK", "MXN", "BRL", "INR", "ZAR", "PLN" ], "description": "Billing currency for the plan. Defaults to USD. For non-USD currencies, supply `unitPrice` (and tier `unitPrice`/`flatFee`); the billing engine uses those as the source of truth and converts to USD via FxRate at charge time.", "example": "USD" }, "pricingModel": { "type": "string", "enum": [ "FLAT", "TIERED", "VOLUME", "PACKAGE", "PER_SEAT" ], "description": "How quantity maps to charge amount:\n- `FLAT`: quantity × unitPrice (default)\n- `TIERED`: graduated, first N at price A, next M at price B, etc.\n- `VOLUME`: total quantity determines a single rate applied to all units\n- `PACKAGE`: charge per package of N units (rounds up partial packages)\n- `PER_SEAT`: per-seat/user licensing. quantity is the seat count, charged at unitPrice per seat per billing period (no tiers)", "example": "FLAT" }, "tiers": { "type": "array", "description": "Tier definitions. Empty for FLAT and PER_SEAT plans; required for TIERED/VOLUME/PACKAGE.", "items": { "type": "object", "description": "A tier defines a price bracket for TIERED, VOLUME, or PACKAGE pricing.", "properties": { "id": { "type": "string", "description": "Tier ID (present on existing tiers)" }, "minQuantity": { "type": "string", "description": "Tier starts at this quantity (inclusive). First tier must be 0.", "example": "0" }, "maxQuantity": { "type": [ "null", "string" ], "description": "Tier ends at this quantity (exclusive). Null on the final unbounded tier.", "example": "1000" }, "unitPriceUsd": { "type": "string", "description": "Price per unit in this tier (USD)", "example": "0.001000" }, "flatFeeUsd": { "type": [ "null", "string" ], "description": "Optional flat fee added when this tier is reached", "example": null }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth and the legacy unitPriceUsd is ignored by the billing engine.", "example": "0.000920" }, "flatFee": { "type": [ "null", "string" ], "description": "Native-currency flat fee. Populated only for non-USD plans (mirror of flatFeeUsd).", "example": null }, "packageSize": { "type": [ "null", "integer" ], "description": "For PACKAGE model: number of units in one billable package", "example": 1000 } }, "required": [ "minQuantity", "unitPriceUsd" ] } }, "creditsPerUnit": { "type": [ "null", "string" ], "description": "Credits consumed per unit of usage. When set, usage is deducted from the customer's credit wallet instead of charging USD.", "example": "10" }, "productCategoryId": { "type": [ "null", "string" ], "description": "Optional product category tag used by 'strict products' mode to roll up reporting by service line. Null when the plan is untagged. When `Business.strictProducts` is true, this must be populated via the category id or key.", "example": "cat_core" }, "isActive": { "type": "boolean", "description": "Whether this plan is active. Only active plans are used for new charges.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "description": "When the plan was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the plan was last updated", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "name", "unitType", "unitPriceUsd", "pricingModel", "tiers", "isActive" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Pricing plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Pricing plan not found" } } } } } }, "patch": { "operationId": "updatePricingPlan", "summary": "Update a pricing plan", "tags": [ "Pricing Plans" ], "description": "Update the name, price, or status of a pricing plan. Changes take effect immediately for new charges.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Plan name" }, "unitPriceUsd": { "type": "number", "description": "New price per unit in USD" }, "isActive": { "type": "boolean", "description": "Enable/disable the plan" }, "creditsPerUnit": { "type": "number", "exclusiveMinimum": 0, "description": "Credits consumed per unit of usage; null to disable credit billing", "nullable": true }, "pricingModel": { "type": "string", "enum": [ "FLAT", "TIERED", "VOLUME", "PACKAGE", "PER_SEAT" ], "description": "How quantity maps to charge" }, "tiers": { "type": "array", "description": "Replace the plan tiers (required for non-FLAT models)", "items": { "type": "object", "properties": { "minQuantity": { "type": "number" }, "maxQuantity": { "type": [ "number", "null" ] }, "unitPriceUsd": { "type": "number" }, "flatFeeUsd": { "type": [ "number", "null" ] }, "packageSize": { "type": [ "integer", "null" ] } }, "required": [ "minQuantity", "unitPriceUsd" ] } } } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Pricing plan ID" } ], "responses": { "200": { "description": "Pricing plan updated", "content": { "application/json": { "schema": { "type": "object", "description": "Pricing plan updated", "properties": { "id": { "type": "string", "description": "Unique identifier for the pricing plan", "example": "plan_abc123def456" }, "businessId": { "type": "string", "description": "Business this plan belongs to", "example": "biz_789xyz" }, "name": { "type": "string", "description": "Human-readable name for the plan", "example": "API Calls" }, "unitType": { "type": "string", "description": "The usage type this plan prices (e.g., \"api_call\", \"token\", \"compute_second\", \"gb_storage\")", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Default (FLAT) price per unit in USD. For TIERED/VOLUME/PACKAGE plans, consult `tiers`. For PER_SEAT plans, this is the price per seat per billing period.", "example": "0.001000" }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth: the billing engine reads it directly and converts to USD via FxRate at charge time.", "example": "0.000920" }, "currency": { "type": "string", "enum": [ "USD", "USDC", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "SGD", "HKD", "ILS", "NZD", "SEK", "NOK", "DKK", "MXN", "BRL", "INR", "ZAR", "PLN" ], "description": "Billing currency for the plan. Defaults to USD. For non-USD currencies, supply `unitPrice` (and tier `unitPrice`/`flatFee`); the billing engine uses those as the source of truth and converts to USD via FxRate at charge time.", "example": "USD" }, "pricingModel": { "type": "string", "enum": [ "FLAT", "TIERED", "VOLUME", "PACKAGE", "PER_SEAT" ], "description": "How quantity maps to charge amount:\n- `FLAT`: quantity × unitPrice (default)\n- `TIERED`: graduated, first N at price A, next M at price B, etc.\n- `VOLUME`: total quantity determines a single rate applied to all units\n- `PACKAGE`: charge per package of N units (rounds up partial packages)\n- `PER_SEAT`: per-seat/user licensing. quantity is the seat count, charged at unitPrice per seat per billing period (no tiers)", "example": "FLAT" }, "tiers": { "type": "array", "description": "Tier definitions. Empty for FLAT and PER_SEAT plans; required for TIERED/VOLUME/PACKAGE.", "items": { "type": "object", "description": "A tier defines a price bracket for TIERED, VOLUME, or PACKAGE pricing.", "properties": { "id": { "type": "string", "description": "Tier ID (present on existing tiers)" }, "minQuantity": { "type": "string", "description": "Tier starts at this quantity (inclusive). First tier must be 0.", "example": "0" }, "maxQuantity": { "type": [ "null", "string" ], "description": "Tier ends at this quantity (exclusive). Null on the final unbounded tier.", "example": "1000" }, "unitPriceUsd": { "type": "string", "description": "Price per unit in this tier (USD)", "example": "0.001000" }, "flatFeeUsd": { "type": [ "null", "string" ], "description": "Optional flat fee added when this tier is reached", "example": null }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth and the legacy unitPriceUsd is ignored by the billing engine.", "example": "0.000920" }, "flatFee": { "type": [ "null", "string" ], "description": "Native-currency flat fee. Populated only for non-USD plans (mirror of flatFeeUsd).", "example": null }, "packageSize": { "type": [ "null", "integer" ], "description": "For PACKAGE model: number of units in one billable package", "example": 1000 } }, "required": [ "minQuantity", "unitPriceUsd" ] } }, "creditsPerUnit": { "type": [ "null", "string" ], "description": "Credits consumed per unit of usage. When set, usage is deducted from the customer's credit wallet instead of charging USD.", "example": "10" }, "productCategoryId": { "type": [ "null", "string" ], "description": "Optional product category tag used by 'strict products' mode to roll up reporting by service line. Null when the plan is untagged. When `Business.strictProducts` is true, this must be populated via the category id or key.", "example": "cat_core" }, "isActive": { "type": "boolean", "description": "Whether this plan is active. Only active plans are used for new charges.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "description": "When the plan was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the plan was last updated", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "name", "unitType", "unitPriceUsd", "pricingModel", "tiers", "isActive" ] } } } }, "400": { "description": "Invalid tier configuration", "content": { "application/json": { "schema": { "description": "Invalid tier configuration", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "INVALID_TIERS" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Pricing plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Pricing plan not found" } } } } } }, "delete": { "operationId": "deletePricingPlan", "summary": "Delete a pricing plan", "tags": [ "Pricing Plans" ], "description": "\nSoft-delete a pricing plan by deactivating it.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**\n\nThe plan is preserved for historical charges but will no longer be used\nfor new usage events. You can reactivate it by updating `isActive` to `true`.\n ", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Pricing plan ID" } ], "responses": { "204": { "description": "Pricing plan deleted", "content": { "application/json": { "schema": { "description": "Pricing plan deleted" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Pricing plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Pricing plan not found" } } } } } } }, "/v1/pricing-plans/{id}/versions": { "get": { "operationId": "listPricingPlanVersions", "summary": "List versions of a pricing plan", "tags": [ "Pricing Plans" ], "description": "Return every version row in the same `versionGroupId` as the given plan, ordered oldest → newest. Pass the id of any version (active or archived) and you get the full history of that plan.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Pricing plan ID (any version)" } ], "responses": { "200": { "description": "Version history", "content": { "application/json": { "schema": { "description": "Version history", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A pricing plan defines how much to charge per unit of usage.", "properties": { "id": { "type": "string", "description": "Unique identifier for the pricing plan", "example": "plan_abc123def456" }, "businessId": { "type": "string", "description": "Business this plan belongs to", "example": "biz_789xyz" }, "name": { "type": "string", "description": "Human-readable name for the plan", "example": "API Calls" }, "unitType": { "type": "string", "description": "The usage type this plan prices (e.g., \"api_call\", \"token\", \"compute_second\", \"gb_storage\")", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Default (FLAT) price per unit in USD. For TIERED/VOLUME/PACKAGE plans, consult `tiers`. For PER_SEAT plans, this is the price per seat per billing period.", "example": "0.001000" }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth: the billing engine reads it directly and converts to USD via FxRate at charge time.", "example": "0.000920" }, "currency": { "type": "string", "enum": [ "USD", "USDC", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "SGD", "HKD", "ILS", "NZD", "SEK", "NOK", "DKK", "MXN", "BRL", "INR", "ZAR", "PLN" ], "description": "Billing currency for the plan. Defaults to USD. For non-USD currencies, supply `unitPrice` (and tier `unitPrice`/`flatFee`); the billing engine uses those as the source of truth and converts to USD via FxRate at charge time.", "example": "USD" }, "pricingModel": { "type": "string", "enum": [ "FLAT", "TIERED", "VOLUME", "PACKAGE", "PER_SEAT" ], "description": "How quantity maps to charge amount:\n- `FLAT`: quantity × unitPrice (default)\n- `TIERED`: graduated, first N at price A, next M at price B, etc.\n- `VOLUME`: total quantity determines a single rate applied to all units\n- `PACKAGE`: charge per package of N units (rounds up partial packages)\n- `PER_SEAT`: per-seat/user licensing. quantity is the seat count, charged at unitPrice per seat per billing period (no tiers)", "example": "FLAT" }, "tiers": { "type": "array", "description": "Tier definitions. Empty for FLAT and PER_SEAT plans; required for TIERED/VOLUME/PACKAGE.", "items": { "type": "object", "description": "A tier defines a price bracket for TIERED, VOLUME, or PACKAGE pricing.", "properties": { "id": { "type": "string", "description": "Tier ID (present on existing tiers)" }, "minQuantity": { "type": "string", "description": "Tier starts at this quantity (inclusive). First tier must be 0.", "example": "0" }, "maxQuantity": { "type": [ "null", "string" ], "description": "Tier ends at this quantity (exclusive). Null on the final unbounded tier.", "example": "1000" }, "unitPriceUsd": { "type": "string", "description": "Price per unit in this tier (USD)", "example": "0.001000" }, "flatFeeUsd": { "type": [ "null", "string" ], "description": "Optional flat fee added when this tier is reached", "example": null }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth and the legacy unitPriceUsd is ignored by the billing engine.", "example": "0.000920" }, "flatFee": { "type": [ "null", "string" ], "description": "Native-currency flat fee. Populated only for non-USD plans (mirror of flatFeeUsd).", "example": null }, "packageSize": { "type": [ "null", "integer" ], "description": "For PACKAGE model: number of units in one billable package", "example": 1000 } }, "required": [ "minQuantity", "unitPriceUsd" ] } }, "creditsPerUnit": { "type": [ "null", "string" ], "description": "Credits consumed per unit of usage. When set, usage is deducted from the customer's credit wallet instead of charging USD.", "example": "10" }, "productCategoryId": { "type": [ "null", "string" ], "description": "Optional product category tag used by 'strict products' mode to roll up reporting by service line. Null when the plan is untagged. When `Business.strictProducts` is true, this must be populated via the category id or key.", "example": "cat_core" }, "isActive": { "type": "boolean", "description": "Whether this plan is active. Only active plans are used for new charges.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "description": "When the plan was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the plan was last updated", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "name", "unitType", "unitPriceUsd", "pricingModel", "tiers", "isActive" ] } }, "count": { "type": "integer" }, "versionGroupId": { "type": "string" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "Pricing plan not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Pricing plan not found" } } } } } } }, "/v1/pricing-plans/by-type/{unitType}": { "get": { "operationId": "getPricingPlanByType", "summary": "Get pricing plan by unit type", "tags": [ "Pricing Plans" ], "description": "Look up the active pricing plan for a specific usage type.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "unitType", "required": true, "description": "Usage type (e.g., \"api_call\", \"token\")" } ], "responses": { "200": { "description": "Pricing plan for unit type", "content": { "application/json": { "schema": { "type": "object", "description": "Pricing plan for unit type", "properties": { "id": { "type": "string", "description": "Unique identifier for the pricing plan", "example": "plan_abc123def456" }, "businessId": { "type": "string", "description": "Business this plan belongs to", "example": "biz_789xyz" }, "name": { "type": "string", "description": "Human-readable name for the plan", "example": "API Calls" }, "unitType": { "type": "string", "description": "The usage type this plan prices (e.g., \"api_call\", \"token\", \"compute_second\", \"gb_storage\")", "example": "api_call" }, "unitPriceUsd": { "type": "string", "description": "Default (FLAT) price per unit in USD. For TIERED/VOLUME/PACKAGE plans, consult `tiers`. For PER_SEAT plans, this is the price per seat per billing period.", "example": "0.001000" }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth: the billing engine reads it directly and converts to USD via FxRate at charge time.", "example": "0.000920" }, "currency": { "type": "string", "enum": [ "USD", "USDC", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF", "SGD", "HKD", "ILS", "NZD", "SEK", "NOK", "DKK", "MXN", "BRL", "INR", "ZAR", "PLN" ], "description": "Billing currency for the plan. Defaults to USD. For non-USD currencies, supply `unitPrice` (and tier `unitPrice`/`flatFee`); the billing engine uses those as the source of truth and converts to USD via FxRate at charge time.", "example": "USD" }, "pricingModel": { "type": "string", "enum": [ "FLAT", "TIERED", "VOLUME", "PACKAGE", "PER_SEAT" ], "description": "How quantity maps to charge amount:\n- `FLAT`: quantity × unitPrice (default)\n- `TIERED`: graduated, first N at price A, next M at price B, etc.\n- `VOLUME`: total quantity determines a single rate applied to all units\n- `PACKAGE`: charge per package of N units (rounds up partial packages)\n- `PER_SEAT`: per-seat/user licensing. quantity is the seat count, charged at unitPrice per seat per billing period (no tiers)", "example": "FLAT" }, "tiers": { "type": "array", "description": "Tier definitions. Empty for FLAT and PER_SEAT plans; required for TIERED/VOLUME/PACKAGE.", "items": { "type": "object", "description": "A tier defines a price bracket for TIERED, VOLUME, or PACKAGE pricing.", "properties": { "id": { "type": "string", "description": "Tier ID (present on existing tiers)" }, "minQuantity": { "type": "string", "description": "Tier starts at this quantity (inclusive). First tier must be 0.", "example": "0" }, "maxQuantity": { "type": [ "null", "string" ], "description": "Tier ends at this quantity (exclusive). Null on the final unbounded tier.", "example": "1000" }, "unitPriceUsd": { "type": "string", "description": "Price per unit in this tier (USD)", "example": "0.001000" }, "flatFeeUsd": { "type": [ "null", "string" ], "description": "Optional flat fee added when this tier is reached", "example": null }, "unitPrice": { "type": [ "null", "string" ], "description": "Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth and the legacy unitPriceUsd is ignored by the billing engine.", "example": "0.000920" }, "flatFee": { "type": [ "null", "string" ], "description": "Native-currency flat fee. Populated only for non-USD plans (mirror of flatFeeUsd).", "example": null }, "packageSize": { "type": [ "null", "integer" ], "description": "For PACKAGE model: number of units in one billable package", "example": 1000 } }, "required": [ "minQuantity", "unitPriceUsd" ] } }, "creditsPerUnit": { "type": [ "null", "string" ], "description": "Credits consumed per unit of usage. When set, usage is deducted from the customer's credit wallet instead of charging USD.", "example": "10" }, "productCategoryId": { "type": [ "null", "string" ], "description": "Optional product category tag used by 'strict products' mode to roll up reporting by service line. Null when the plan is untagged. When `Business.strictProducts` is true, this must be populated via the category id or key.", "example": "cat_core" }, "isActive": { "type": "boolean", "description": "Whether this plan is active. Only active plans are used for new charges.", "example": true }, "createdAt": { "type": "string", "format": "date-time", "description": "When the plan was created", "example": "2024-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the plan was last updated", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "name", "unitType", "unitPriceUsd", "pricingModel", "tiers", "isActive" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "Unauthorized" } } } }, "404": { "description": "No active pricing plan found for unit type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "description": "Error code" }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } }, "description": "Validation error details" } }, "required": [ "error", "code" ], "description": "No active pricing plan found for unit type" } } } } } } }, "/v1/pricing-plans/{id}/reprovision-stripe": { "post": { "operationId": "reprovisionPricingPlanStripe", "summary": "Retry Stripe auto-provisioning for a plan", "tags": [ "Pricing Plans" ], "description": "Retries the Drip-managed Stripe Product / Meter / Price provisioning for a pricing plan. Useful after an initial transient failure on plan create. Idempotent: already-provisioned objects are skipped; only the missing Stripe calls are made.\n\n> **Requires a secret key (`sk_*`) with the `ADMIN` role.**", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true, "description": "Pricing plan ID" } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/portal/profile": { "get": { "operationId": "getPortalProfile", "summary": "Get customer profile", "tags": [ "Customer Portal" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/portal/profile/address": { "put": { "operationId": "updatePortalProfileAddress", "summary": "Update billing address", "tags": [ "Customer Portal" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/portal/subscriptions": { "get": { "operationId": "listPortalSubscriptions", "summary": "List subscriptions", "tags": [ "Customer Portal" ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/portal/subscriptions/{id}/cancel": { "post": { "operationId": "cancelPortalSubscription", "summary": "Cancel subscription", "tags": [ "Customer Portal" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } } }, "servers": [ { "url": "https://api.drippay.dev", "description": "Production" }, { "url": "http://localhost:3001", "description": "Development" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Customers", "description": "Create and manage billable customers." }, { "name": "Usage", "description": "Record metered usage. Creates charges when a pricing plan matches." }, { "name": "Events", "description": "Record execution events for observability." }, { "name": "Charges", "description": "View charge history and settlement status." }, { "name": "Pricing Plans", "description": "Define per-unit pricing for usage types. Creating, updating, and deleting plans requires a secret key (`sk_*`) with the `ADMIN` role." }, { "name": "Contracts", "description": "Per-customer commercial agreements with custom pricing, prepaid commits, and spend caps. All contract endpoints require a secret key (`sk_*`) with the `ADMIN` role." }, { "name": "Entitlements", "description": "Quota management and pre-request access checks." }, { "name": "Webhooks", "description": "Manage webhook endpoints for real-time event notifications." }, { "name": "Subscriptions", "description": "Recurring billing and subscription lifecycle management." }, { "name": "Workflows", "description": "Define workflow templates for agent execution." }, { "name": "Runs", "description": "Start, update, and inspect agent runs." }, { "name": "Dunning", "description": "Automatic retry + dunning email flow for failed payments. Configure a per-business retry schedule, list failed charges in collections, and manually re-trigger retries." }, { "name": "Invoices", "description": "Generate, issue, and manage invoices. Supports usage-based and subscription-based billing periods." }, { "name": "Tax", "description": "Sales tax configuration: customer tax addresses, exemptions, business registrations, and jurisdiction rates. Requires a secret key with ADMIN role and full mode (`SIMPLE_MODE=false`)." }, { "name": "Credit Notes", "description": "Create, issue, and void credit notes." }, { "name": "Coupons", "description": "Coupons and promotion codes for discounts." }, { "name": "Integrations", "description": "Manage billing, CRM, and marketplace integrations (Stripe, Xero, Salesforce)." }, { "name": "Business", "description": "Business-level settings and configuration." }, { "name": "BillableMetrics", "description": "Evaluate and preview billable metrics." }, { "name": "Customer Portal", "description": "Self-service customer portal for profile, subscriptions, and address management." }, { "name": "GL Exports", "description": "Generate general-ledger journal entry exports." }, { "name": "Product Categories", "description": "Controlled taxonomy for strict-products governance. Groups pricing plans into service-line categories for ARR rollups and revenue reporting." } ] }