{
  "openapi": "3.1.0",
  "info": {
    "title": "Bellwrit API",
    "version": "1.0.0",
    "summary": "Verified outbound calling, dashboard, and tokenized receipt endpoints.",
    "description": "Bellwrit is your outbound, receipted. POST /api/v1/calls can place a live outbound call through Retell. The authenticated dashboard sandbox records provider-free simulations. Signed lifecycle records appear in protected call detail when recorded; they are distinct from the separately tokenized public audit-receipt route. The call request endpoint does not issue a public receipt token for each call. Bellwrit supports outbound calling only."
  },
  "servers": [
    {
      "url": "https://www.bellwrit.com",
      "description": "Bellwrit production API"
    }
  ],
  "tags": [
    { "name": "Calls", "description": "Live outbound calls authenticated with a Bearer API key." },
    { "name": "Dashboard", "description": "Session-authenticated customer dashboard operations." },
    { "name": "Audit receipts", "description": "Public, sanitized receipts addressed by a separate receipt token." }
  ],
  "paths": {
    "/api/v1/calls": {
      "post": {
        "tags": ["Calls"],
        "operationId": "createOutboundCall",
        "summary": "Create or replay a live outbound call request",
        "description": "This is a live outbound endpoint. A valid request can place a real outbound call through Retell; it is not the provider-free dashboard sandbox. Repeating the same request returns the existing call response. The response does not include a public audit-receipt token.",
        "security": [{ "bearerApiKey": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CallRequest" },
              "example": {
                "requestId": "appointment-availability-001",
                "task": {
                  "purpose": "Confirm whether the clinic has an opening next Tuesday.",
                  "target": { "phoneNumber": "+14155550123", "name": "Front desk" },
                  "caller": { "name": "Bellwrit Example", "organization": "Example workflow" },
                  "constraints": {
                    "allowedTopics": ["availability", "booking requirements"],
                    "prohibitedTopics": ["medical advice", "payment details"],
                    "maxDurationSeconds": 300
                  },
                  "consent": { "basis": "pre_authorized", "reference": "example-consent" },
                  "escalation": { "enabled": false },
                  "result": {
                    "fields": [
                      { "name": "available", "type": "boolean", "required": true },
                      { "name": "details", "type": "string", "required": false }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "A new live call request was created.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } }
          },
          "200": {
            "description": "The matching request was replayed; no duplicate call was created.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } }
          },
          "400": { "$ref": "#/components/responses/InvalidRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "402": {
            "description": "A customer API key does not have an active billing entitlement.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionRequired" } } }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/dashboard/api-keys": {
      "get": {
        "tags": ["Dashboard"],
        "operationId": "getCustomerApiKey",
        "summary": "Read the signed-in customer's API key status",
        "security": [{ "sessionCookie": [] }],
        "responses": {
          "200": {
            "description": "Safe API-key metadata. Plaintext is never returned by this operation.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyStatus" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      },
      "post": {
        "tags": ["Dashboard"],
        "operationId": "createCustomerApiKey",
        "summary": "Create the signed-in customer's API key",
        "description": "The plaintext key is returned once in this response. Store it securely. Only one active customer key is allowed per account.",
        "security": [{ "sessionCookie": [] }],
        "responses": {
          "201": {
            "description": "Created key metadata and the one-time plaintext key.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "409": {
            "description": "An active API key already exists for this account.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } }
          },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      },
      "delete": {
        "tags": ["Dashboard"],
        "operationId": "revokeCustomerApiKey",
        "summary": "Revoke the signed-in customer's API key",
        "security": [{ "sessionCookie": [] }],
        "responses": {
          "204": { "description": "The customer's active key was revoked, or no active key remained." },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/dashboard/sandbox-call": {
      "get": {
        "tags": ["Dashboard"],
        "operationId": "getSandboxCallConfig",
        "summary": "Read the fixed provider-free sandbox request and scenarios",
        "description": "Requires a signed-in dashboard session. The returned request is server-owned and does not place a call.",
        "security": [{ "sessionCookie": [] }],
        "responses": {
          "200": {
            "description": "Fixed sandbox request, authorization description, and the completed, failed, and escalated scenarios.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardSandboxConfig" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "tags": ["Dashboard"],
        "operationId": "runSandboxCallScenario",
        "summary": "Record a provider-free sandbox scenario",
        "description": "Requires a signed-in dashboard session. This provider-free dashboard sandbox writes a simulated call record and signed local lifecycle events; it never contacts a telephony provider or places a live call.",
        "security": [{ "sessionCookie": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DashboardSandboxInput" },
              "examples": {
                "completed": { "value": { "scenario": "completed" } },
                "failed": { "value": { "scenario": "failed" } },
                "escalated": { "value": { "scenario": "escalated" } }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "A new simulated record was created.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } }
          },
          "200": {
            "description": "The idempotent scenario record already existed.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } }
          },
          "400": {
            "description": "Request JSON or the scenario value is invalid.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/dashboard/sandbox-call/status": {
      "get": {
        "tags": ["Dashboard"],
        "operationId": "getLatestSandboxCall",
        "summary": "Read the signed-in customer's latest sandbox call response",
        "security": [{ "sessionCookie": [] }],
        "responses": {
          "200": {
            "description": "The latest sandbox call response for the signed-in customer.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/dashboard/calls": {
      "get": {
        "tags": ["Dashboard"],
        "operationId": "listDashboardCalls",
        "summary": "List protected call history",
        "description": "Requires a signed-in dashboard session. Ordinary users see records scoped to their account; admins retain the existing all-record view. Each item includes outcomeKind from the stored outcome so sandbox simulations can be distinguished from Retell calls.",
        "security": [{ "sessionCookie": [] }],
        "responses": {
          "200": {
            "description": "Protected call history.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallHistoryResponse" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/dashboard/calls/{callId}": {
      "get": {
        "tags": ["Dashboard"],
        "operationId": "getDashboardCall",
        "summary": "Read protected call detail and stored lifecycle records",
        "description": "Requires a signed-in dashboard session. Ordinary users can read only their own call; admins retain the existing all-record access. Stored lifecycle deliveries include their HMAC-SHA256 signatures. This protected detail is not the tokenized public audit-receipt endpoint.",
        "security": [{ "sessionCookie": [] }],
        "parameters": [
          {
            "name": "callId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^call_v1_[a-f0-9]{64}$" }
          }
        ],
        "responses": {
          "200": {
            "description": "Protected call detail with task, transcript, audit events, and any signed lifecycle deliveries.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallDetail" } } }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/audit-receipts/{receiptToken}": {
      "get": {
        "tags": ["Audit receipts"],
        "operationId": "getPublicAuditReceipt",
        "summary": "Read a sanitized audit receipt addressed by a separate token",
        "description": "Public access requires an existing receiptToken. This route returns a sanitized pending/incomplete/failed state or a ready receipt. The live-call creation endpoint and dashboard sandbox do not issue a public receipt token for every call; the synthetic sample receipt is separate demo content.",
        "parameters": [
          {
            "name": "receiptToken",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1 }
          },
          {
            "name": "reconcile",
            "in": "query",
            "required": false,
            "description": "When true, asks the existing Retell reconciliation path to refresh eligible receipt data before returning it.",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "A sanitized receipt state. Only the ready variant contains the receipt detail.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditReceipt" } } }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Customer API key sent as Authorization: Bearer <key>. Keep it server-side."
      },
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "better-auth.session_token",
        "description": "Better Auth session cookie from a signed-in Bellwrit account. HTTPS deployments may apply the standard secure-cookie prefix; browser clients should use their same-origin authenticated session."
      }
    },
    "responses": {
      "InvalidRequest": {
        "description": "Request JSON or fields did not satisfy the endpoint contract.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidRequest" } }
        }
      },
      "Unauthorized": {
        "description": "A valid API key or signed-in session is required.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } }
      },
      "NotFound": {
        "description": "The receipt, sandbox call, or accessible call record was not found.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } }
      },
      "InternalError": {
        "description": "Unexpected server-side failure.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorMessage" } } }
      }
    },
    "schemas": {
      "ErrorMessage": {
        "type": "object",
        "required": ["error"],
        "properties": { "error": { "type": "string" } },
        "additionalProperties": false
      },
      "InvalidRequest": {
        "type": "object",
        "required": ["error", "errors"],
        "properties": {
          "error": { "const": "Invalid request" },
          "errors": { "type": "object", "additionalProperties": { "type": "string" } }
        },
        "additionalProperties": false
      },
      "SubscriptionRequired": {
        "type": "object",
        "required": ["error", "billing_url"],
        "properties": {
          "error": { "const": "subscription_required" },
          "billing_url": { "const": "/pricing" }
        },
        "additionalProperties": false
      },
      "CallRequest": {
        "type": "object",
        "required": ["requestId", "task"],
        "properties": {
          "requestId": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$" },
          "task": { "$ref": "#/components/schemas/CallTask" }
        },
        "additionalProperties": false
      },
      "CallTask": {
        "type": "object",
        "required": ["purpose", "target", "caller", "constraints", "consent", "escalation", "result"],
        "properties": {
          "purpose": { "type": "string", "minLength": 1, "maxLength": 500 },
          "target": {
            "type": "object",
            "required": ["phoneNumber"],
            "properties": {
              "phoneNumber": { "type": "string", "pattern": "^\\+[1-9]\\d{7,14}$" },
              "name": { "type": "string", "minLength": 1, "maxLength": 120 }
            },
            "additionalProperties": false
          },
          "caller": {
            "type": "object",
            "required": ["name"],
            "properties": {
              "name": { "type": "string", "minLength": 1, "maxLength": 120 },
              "organization": { "type": "string", "minLength": 1, "maxLength": 160 }
            },
            "additionalProperties": false
          },
          "constraints": {
            "type": "object",
            "required": ["allowedTopics", "maxDurationSeconds"],
            "properties": {
              "allowedTopics": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 120 } },
              "prohibitedTopics": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "default": [] },
              "maxDurationSeconds": { "type": "integer", "minimum": 30, "maximum": 3600 }
            },
            "additionalProperties": false
          },
          "consent": {
            "type": "object",
            "required": ["basis"],
            "properties": {
              "basis": { "type": "string", "enum": ["user_requested", "pre_authorized"] },
              "reference": { "type": "string", "minLength": 1, "maxLength": 160 }
            },
            "additionalProperties": false
          },
          "escalation": {
            "type": "object",
            "required": ["enabled"],
            "properties": {
              "enabled": { "type": "boolean" },
              "instructions": { "type": "string", "minLength": 1, "maxLength": 500 }
            },
            "additionalProperties": false
          },
          "result": {
            "type": "object",
            "required": ["fields"],
            "properties": {
              "fields": {
                "type": "array",
                "minItems": 1,
                "maxItems": 20,
                "items": {
                  "type": "object",
                  "required": ["name", "type"],
                  "properties": {
                    "name": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$" },
                    "type": { "type": "string", "enum": ["string", "number", "boolean"] },
                    "required": { "type": "boolean", "default": false }
                  },
                  "additionalProperties": false
                }
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "CallStatus": { "type": "string", "enum": ["queued", "in_progress", "completed", "failed"] },
      "CallResponse": {
        "type": "object",
        "required": ["callId", "requestId", "task", "status", "transcript", "outcome", "createdAt", "updatedAt"],
        "properties": {
          "callId": { "type": "string", "pattern": "^call_v1_[a-f0-9]{64}$" },
          "requestId": { "type": "string", "minLength": 1, "maxLength": 128 },
          "task": { "$ref": "#/components/schemas/CallTask" },
          "status": { "$ref": "#/components/schemas/CallStatus" },
          "transcript": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/TranscriptItem" } },
          "outcome": { "oneOf": [{ "$ref": "#/components/schemas/SandboxOutcome" }, { "$ref": "#/components/schemas/RetellOutcome" }] },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "SandboxOutcome": {
        "type": "object",
        "required": ["kind", "completed", "liveCallPlaced", "summary"],
        "properties": {
          "kind": { "const": "sandbox" },
          "completed": { "type": "boolean" },
          "liveCallPlaced": { "const": false },
          "summary": { "type": "string", "minLength": 1, "maxLength": 2000 }
        },
        "additionalProperties": false
      },
      "RetellOutcome": {
        "type": "object",
        "required": ["kind", "completed", "liveCallPlaced", "summary"],
        "properties": {
          "kind": { "const": "retell" },
          "completed": { "type": "boolean" },
          "liveCallPlaced": { "const": true },
          "summary": { "type": "string", "minLength": 1, "maxLength": 2000 },
          "disconnectionReason": { "type": "string", "minLength": 1, "maxLength": 120 },
          "analysis": { "type": "object", "additionalProperties": true },
          "failure": { "$ref": "#/components/schemas/RetellFailure" },
          "attempt": { "type": "integer", "minimum": 1 }
        },
        "additionalProperties": false
      },
      "RetellFailure": {
        "type": "object",
        "required": ["code", "message", "remediation", "retryable", "attempt"],
        "properties": {
          "code": { "type": "string", "enum": ["configuration", "provider_rejected", "network", "malformed_response"] },
          "message": { "type": "string", "minLength": 1, "maxLength": 400 },
          "remediation": { "type": "string", "minLength": 1, "maxLength": 500 },
          "retryable": { "type": "boolean" },
          "attempt": { "type": "integer", "minimum": 1 }
        },
        "additionalProperties": false
      },
      "TranscriptItem": {
        "type": "object",
        "required": ["role", "text"],
        "properties": {
          "role": { "type": "string", "enum": ["system", "caller", "callee", "assistant"] },
          "text": { "type": "string", "minLength": 1, "maxLength": 2000 }
        },
        "additionalProperties": false
      },
      "DashboardSandboxInput": {
        "type": "object",
        "required": ["scenario"],
        "properties": { "scenario": { "type": "string", "enum": ["completed", "failed", "escalated"] } },
        "additionalProperties": false
      },
      "DashboardSandboxConfig": {
        "type": "object",
        "required": ["request", "authorization", "scenarios"],
        "properties": {
          "request": { "$ref": "#/components/schemas/CallRequest" },
          "authorization": {
            "type": "object",
            "required": ["basis", "label", "description"],
            "properties": {
              "basis": { "const": "pre_authorized" },
              "label": { "type": "string", "minLength": 1, "maxLength": 160 },
              "description": { "type": "string", "minLength": 1, "maxLength": 300 }
            },
            "additionalProperties": false
          },
          "scenarios": {
            "type": "array",
            "minItems": 3,
            "maxItems": 3,
            "items": {
              "type": "object",
              "required": ["id", "label", "description"],
              "properties": {
                "id": { "type": "string", "enum": ["completed", "failed", "escalated"] },
                "label": { "type": "string", "minLength": 1, "maxLength": 80 },
                "description": { "type": "string", "minLength": 1, "maxLength": 200 }
              },
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      },
      "ApiKeyMetadata": {
        "type": "object",
        "required": ["id", "keyPrefix", "lastFour", "createdAt", "updatedAt", "revokedAt", "active"],
        "properties": {
          "id": { "type": "string", "minLength": 1 },
          "keyPrefix": { "type": "string", "minLength": 1, "maxLength": 32 },
          "lastFour": { "type": "string", "minLength": 4, "maxLength": 4 },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "revokedAt": { "type": ["string", "null"], "format": "date-time" },
          "active": { "type": "boolean" }
        },
        "additionalProperties": false
      },
      "ApiKeyStatus": {
        "type": "object",
        "required": ["key"],
        "properties": { "key": { "oneOf": [{ "$ref": "#/components/schemas/ApiKeyMetadata" }, { "type": "null" }] } },
        "additionalProperties": false
      },
      "CreateApiKeyResponse": {
        "type": "object",
        "required": ["key", "plaintext"],
        "properties": {
          "key": { "$ref": "#/components/schemas/ApiKeyMetadata" },
          "plaintext": { "type": "string", "minLength": 1, "description": "Returned once at creation; not included by GET." }
        },
        "additionalProperties": false
      },
      "CallHistoryResponse": {
        "type": "object",
        "required": ["items"],
        "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CallHistoryItem" } } },
        "additionalProperties": false
      },
      "CallHistoryItem": {
        "type": "object",
        "required": ["callId", "destination", "startedAt", "endedAt", "durationSeconds", "status", "outcomeKind", "outcomeLabel", "costMicros", "recordingAvailable", "purpose"],
        "properties": {
          "callId": { "type": "string", "pattern": "^call_v1_[a-f0-9]{64}$" },
          "destination": { "type": "string", "minLength": 1, "maxLength": 40 },
          "startedAt": { "type": "string", "format": "date-time" },
          "endedAt": { "type": ["string", "null"], "format": "date-time" },
          "durationSeconds": { "type": ["integer", "null"], "minimum": 0 },
          "status": { "$ref": "#/components/schemas/CallStatus" },
          "outcomeKind": { "type": "string", "enum": ["sandbox", "retell"] },
          "outcomeLabel": { "type": "string", "minLength": 1, "maxLength": 200 },
          "costMicros": { "type": ["integer", "null"], "minimum": 0 },
          "recordingAvailable": { "type": "boolean" },
          "purpose": { "type": "string", "minLength": 1, "maxLength": 500 }
        },
        "additionalProperties": false
      },
      "CallDetail": {
        "type": "object",
        "required": ["callId", "destination", "startedAt", "endedAt", "durationSeconds", "status", "outcomeKind", "outcomeLabel", "costMicros", "purpose", "task", "authorization", "consentCaptured", "aiSummary", "transcript", "recordingAvailable", "auditEvents", "lifecycleDeliveries"],
        "properties": {
          "callId": { "type": "string", "pattern": "^call_v1_[a-f0-9]{64}$" },
          "destination": { "type": "string", "minLength": 1, "maxLength": 40 },
          "startedAt": { "type": "string", "format": "date-time" },
          "endedAt": { "type": ["string", "null"], "format": "date-time" },
          "durationSeconds": { "type": ["integer", "null"], "minimum": 0 },
          "status": { "$ref": "#/components/schemas/CallStatus" },
          "outcomeKind": { "type": "string", "enum": ["sandbox", "retell"] },
          "outcomeLabel": { "type": "string", "minLength": 1, "maxLength": 200 },
          "costMicros": { "type": ["integer", "null"], "minimum": 0 },
          "recordingAvailable": { "type": "boolean" },
          "purpose": { "type": "string", "minLength": 1, "maxLength": 500 },
          "task": { "$ref": "#/components/schemas/CallTask" },
          "authorization": {
            "type": "object",
            "required": ["basis", "reference"],
            "properties": {
              "basis": { "type": "string", "enum": ["user_requested", "pre_authorized"] },
              "reference": { "type": ["string", "null"], "minLength": 1, "maxLength": 160 }
            },
            "additionalProperties": false
          },
          "consentCaptured": { "type": "boolean" },
          "aiSummary": { "type": "string", "minLength": 1, "maxLength": 2000 },
          "transcript": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/TranscriptItem" } },
          "auditEvents": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["eventType", "occurredAt", "details"],
              "properties": {
                "eventType": { "type": "string", "minLength": 1, "maxLength": 80 },
                "occurredAt": { "type": "string", "format": "date-time" },
                "details": { "type": "object", "additionalProperties": true }
              },
              "additionalProperties": false
            }
          },
          "lifecycleDeliveries": { "type": "array", "items": { "$ref": "#/components/schemas/CallLifecycleDelivery" } }
        },
        "additionalProperties": false
      },
      "CallLifecycleDelivery": {
        "type": "object",
        "required": ["id", "callId", "eventKey", "eventType", "payload", "status", "signatureAlgorithm", "signatureVersion", "occurredAt", "signedAt", "signature", "createdAt"],
        "properties": {
          "id": { "type": "string", "minLength": 1 },
          "callId": { "type": "string", "pattern": "^call_v1_[a-f0-9]{64}$" },
          "eventKey": { "type": "string", "minLength": 1, "maxLength": 500 },
          "eventType": { "type": "string", "enum": ["started", "completed", "failed", "escalated"] },
          "payload": {
            "type": "object",
            "required": ["version", "eventKey", "eventType", "callId", "occurredAt", "signedAt", "data"],
            "properties": {
              "version": { "const": 1 },
              "eventKey": { "type": "string", "minLength": 1, "maxLength": 500 },
              "eventType": { "type": "string", "enum": ["started", "completed", "failed", "escalated"] },
              "callId": { "type": "string", "pattern": "^call_v1_[a-f0-9]{64}$" },
              "occurredAt": { "type": "string", "format": "date-time" },
              "signedAt": { "type": "string", "format": "date-time" },
              "data": { "type": "object", "additionalProperties": true }
            },
            "additionalProperties": false
          },
          "status": { "const": "recorded" },
          "signatureAlgorithm": { "const": "HMAC-SHA256" },
          "signatureVersion": { "const": 1 },
          "occurredAt": { "type": "string", "format": "date-time" },
          "signedAt": { "type": "string", "format": "date-time" },
          "signature": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": false
      },
      "AuditReceipt": {
        "oneOf": [
          { "$ref": "#/components/schemas/PendingAuditReceipt" },
          { "$ref": "#/components/schemas/ReadyAuditReceipt" }
        ],
        "discriminator": { "propertyName": "status" }
      },
      "PendingAuditReceipt": {
        "type": "object",
        "required": ["status"],
        "properties": { "status": { "type": "string", "enum": ["pending", "incomplete", "failed"] } },
        "additionalProperties": false
      },
      "ReadyAuditReceipt": {
        "type": "object",
        "required": ["status", "purpose", "allowedScope", "prohibitedScope", "maxDurationSeconds", "targetPhoneMasked", "authorization", "timeline", "outcome", "signature"],
        "properties": {
          "status": { "const": "ready" },
          "purpose": { "type": "string", "minLength": 1, "maxLength": 500 },
          "allowedScope": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 120 } },
          "prohibitedScope": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 120 } },
          "maxDurationSeconds": { "type": "integer", "minimum": 30, "maximum": 3600 },
          "targetPhoneMasked": { "type": "string", "minLength": 1, "maxLength": 40 },
          "authorization": {
            "type": "object",
            "required": ["basis", "reference", "authorizedAt", "authorizedPurpose", "authorizedScope"],
            "properties": {
              "basis": { "type": "string", "enum": ["user_requested", "pre_authorized"] },
              "reference": { "type": ["string", "null"], "maxLength": 160 },
              "authorizedAt": { "type": "string", "format": "date-time" },
              "authorizedPurpose": { "type": "string", "minLength": 1, "maxLength": 500 },
              "authorizedScope": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 120 } }
            },
            "additionalProperties": false
          },
          "timeline": {
            "type": "array",
            "minItems": 1,
            "maxItems": 50,
            "items": {
              "type": "object",
              "required": ["id", "label", "occurredAt"],
              "properties": {
                "id": { "type": "string", "minLength": 1, "maxLength": 180 },
                "label": { "type": "string", "enum": ["Request queued", "Authorization recorded", "Call ringing", "Call connected", "Call ended", "Call outcome finalized", "Call activity recorded", "Outcome reconciled from Retell API"] },
                "occurredAt": { "type": "string", "format": "date-time" }
              },
              "additionalProperties": false
            }
          },
          "outcome": { "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "additionalProperties": { "oneOf": [{ "type": "boolean" }, { "type": "number" }, { "const": "Tuesday, 14:30 - confirmed" }] } },
          "signature": { "type": "string", "pattern": "^[A-Za-z0-9_-]{12,24}$" },
          "lifecycleTrace": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/CallLifecycleDelivery" } }
        },
        "additionalProperties": false
      }
    }
  }
}