{
  "openapi": "3.1.0",
  "info": {
    "title": "Crescendo Platform API",
    "version": "1.6.0",
    "description": "Public HTTP API for the Crescendo platform."
  },
  "servers": [
    {
      "url": "https://platform.crescendo.ai"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    },
    {
      "bearerTokenQuery": []
    }
  ],
  "tags": [
    {
      "name": "Service",
      "description": "Service metadata and health."
    },
    {
      "name": "Provisioning",
      "description": "Tenant-scoped provisioning resources."
    },
    {
      "name": "Assistants",
      "description": "Customer messages and assistant handoff results."
    },
    {
      "name": "Reporting",
      "description": "Reporting-friendly exports (cursor pagination)."
    },
    {
      "name": "VOC",
      "description": "Upload recordings for VOC processing."
    },
    {
      "name": "MCP",
      "description": "Model Context Protocol (MCP) endpoints."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["Service"],
        "summary": "Get service info",
        "description": "Returns basic service metadata (name and version).",
        "security": [],
        "responses": {
          "200": {
            "description": "Service info",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceInfo"
                },
                "examples": {
                  "example": {
                    "value": {
                      "name": "platform-api-service",
                      "version": "1.6.0"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": ["Service"],
        "summary": "Health check",
        "description": "Returns `ok` when the service is up.",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthStatus"
                },
                "examples": {
                  "example": {
                    "value": {
                      "status": "ok"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/provisioning/tenants/{tenantId}": {
      "get": {
        "tags": ["Provisioning"],
        "summary": "Get a provisioning document",
        "description": "Reads a single tenant-scoped provisioning document.",
        "operationId": "getProvisioningTenant",
        "parameters": [{ "$ref": "#/components/parameters/tenantId" }],
        "responses": {
          "200": {
            "description": "Provisioning document",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "post": {
        "tags": ["Provisioning"],
        "summary": "Create or replace a provisioning document (POST = replace)",
        "description": "Creates a document if it does not exist, otherwise replaces the existing document (POST = replace).",
        "operationId": "postProvisioningTenant",
        "parameters": [{ "$ref": "#/components/parameters/tenantId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replaced (existing document)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "201": {
            "description": "Created (new document)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" }
        }
      },
      "put": {
        "tags": ["Provisioning"],
        "summary": "Update a provisioning document (PUT = merge update)",
        "description": "Updates an existing document by merging fields (PUT = merge update). Returns 404 if the document does not exist.",
        "operationId": "putProvisioningTenant",
        "parameters": [{ "$ref": "#/components/parameters/tenantId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/provisioning/tenants/{tenantId}/{collection}": {
      "get": {
        "tags": ["Provisioning"],
        "summary": "List a provisioning collection",
        "description": "Reads a collection and returns an array of `{ id, data }` objects.",
        "operationId": "listProvisioningCollection",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/collection" }
        ],
        "responses": {
          "200": {
            "description": "Collection entries",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningCollectionResponse" },
                "examples": {
                  "example": {
                    "value": [
                      { "id": "user-001", "data": { "email": "owner@alpha.test", "role": "owner" } },
                      { "id": "user-002", "data": { "email": "viewer@alpha.test", "role": "viewer" } }
                    ]
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" }
        }
      }
    },
    "/api/v1/provisioning/tenants/{tenantId}/{collection}/{docId}": {
      "get": {
        "tags": ["Provisioning"],
        "summary": "Get a provisioning document by ID",
        "description": "Reads a single document at the provided path.",
        "operationId": "getProvisioningDocument",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/collection" },
          { "$ref": "#/components/parameters/docId" }
        ],
        "responses": {
          "200": {
            "description": "Provisioning document",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "post": {
        "tags": ["Provisioning"],
        "summary": "Create or replace a provisioning document (POST = replace)",
        "description": "Creates a document if it does not exist, otherwise replaces the existing document (POST = replace).",
        "operationId": "postProvisioningDocument",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/collection" },
          { "$ref": "#/components/parameters/docId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replaced (existing document)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "201": {
            "description": "Created (new document)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" }
        }
      },
      "put": {
        "tags": ["Provisioning"],
        "summary": "Update a provisioning document (PUT = merge update)",
        "description": "Updates an existing document by merging fields (PUT = merge update). Returns 404 if the document does not exist.",
        "operationId": "putProvisioningDocument",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/collection" },
          { "$ref": "#/components/parameters/docId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/provisioning/tenants/{tenantId}/{collection}/{docId}/versions/current": {
      "get": {
        "tags": ["Provisioning"],
        "summary": "Get the current version document",
        "description": "Reads the `versions/current` document for a versioned resource.",
        "operationId": "getProvisioningVersionCurrent",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/collection" },
          { "$ref": "#/components/parameters/docId" }
        ],
        "responses": {
          "200": {
            "description": "Current version document",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "post": {
        "tags": ["Provisioning"],
        "summary": "Create or replace the current version document (POST = replace)",
        "description": "Creates or replaces the `versions/current` document (POST = replace).",
        "operationId": "postProvisioningVersionCurrent",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/collection" },
          { "$ref": "#/components/parameters/docId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Replaced (existing document)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "201": {
            "description": "Created (new document)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" }
        }
      },
      "put": {
        "tags": ["Provisioning"],
        "summary": "Update the current version document (PUT = merge update)",
        "description": "Updates an existing `versions/current` document by merging fields (PUT = merge update). Returns 404 if the document does not exist.",
        "operationId": "putProvisioningVersionCurrent",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/collection" },
          { "$ref": "#/components/parameters/docId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProvisioningDocument" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/assistant/tenants/{tenantId}/bots/{botId}/messages": {
      "post": {
        "operationId": "sendAssistantMessage",
        "summary": "Send a customer message to an assistant",
        "description": "Send a customer message to an assistant using a tenant API key with assistant:write or an existing equivalent write scope. The complete JSON body is limited to 10 MiB. Each processing call has a default 55-second response budget; HTTP parsing and authentication occur before that budget starts. Timeout does not cancel conversation work. Retries can execute again, and concurrent calls may produce partial/empty replies.",
        "parameters": [
          {
            "name": "tenantId",
            "in": "path",
            "required": true,
            "schema": {"type": "string", "minLength": 1},
            "description": "Tenant-scoped path ID; must be nonempty, cannot contain slash, and cannot be . or .. ."
          },
          {
            "name": "botId",
            "in": "path",
            "required": true,
            "schema": {"type": "string", "minLength": 1},
            "description": "Tenant-scoped path ID; must be nonempty, cannot contain slash, and cannot be . or .. ."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/AssistantMessageRequest"},
              "example": {
                "conversationId": "customer-chat-42",
                "message": "Where is my order?",
                "messageId": "customer-message-8",
                "orderNumber": "ORDER-123",
                "context": {
                  "locale": "en",
                  "customer": {"loyaltyTier": "gold"}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Public assistant reply, tags and handoff outcome; partial/empty text and retained-handoff null text are valid.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AssistantMessageResult"},
                "examples": {
                  "active": {
                    "value": {
                      "conversationId": "customer-chat-42",
                      "messageId": "customer-message-8",
                      "state": "active",
                      "handoff": false,
                      "message": "I can help you check your order.",
                      "tags": ["c7o"]
                    }
                  },
                  "handoff": {
                    "value": {
                      "conversationId": "customer-chat-42",
                      "messageId": "customer-message-8",
                      "state": "handed_off",
                      "handoff": true,
                      "message": "A human will help.",
                      "tags": ["c7o", "help", "c7o_handoff"],
                      "screenPopComment": "Summary",
                      "scriptResult": {
                        "destination": "external",
                        "messages": [
                          {"id": "user", "role": "user", "content": "Question"}
                        ],
                        "enabled": false,
                        "count": 0,
                        "empty": null
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "BadRequest for malformed JSON, an invalid decoded path ID or invalid parsed request envelope, or invalid_request from assistant processing.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AssistantError"}
              }
            }
          },
          "401": {
            "description": "Unauthenticated: missing, invalid, expired or wrong-tenant API key.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AssistantError"}}}
          },
          "403": {
            "description": "PermissionDenied: insufficient write scope.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AssistantError"}}}
          },
          "404": {
            "description": "assistant_not_found: no current bot specification.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AssistantError"}
              }
            }
          },
          "409": {
            "description": "conversation_expired or the reserved conversation_conflict mapping.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AssistantError"}
              }
            }
          },
          "415": {
            "description": "UnsupportedMediaType: the handler receives a Content-Type other than application/json.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AssistantError"}
              }
            }
          },
          "422": {
            "description": "unsupported_assistant: unsupported implementation version or synchronous-text model.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AssistantError"}
              }
            }
          },
          "500": {
            "description": "Oversized JSON, unsupported charset/content encoding, or an unexpected host failure; message-only response without a code.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["message"],
                  "additionalProperties": false,
                  "properties": {
                    "message": {"type": "string", "enum": ["Internal Server Error"]}
                  }
                }
              }
            }
          },
          "502": {
            "description": "assistant_error or script_result_error; action is handoff.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AssistantError"}
              }
            }
          },
          "503": {
            "description": "service_unavailable: assistant storage or configuration is unavailable; action is handoff.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AssistantError"}
              }
            }
          },
          "504": {
            "description": "assistant_timeout: response deadline elapsed; underlying work is not canceled; action is handoff.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/AssistantError"}
              }
            }
          }
        },
        "tags": ["Assistants"]
      }
    },
    "/api/v1/reporting/tenants/{tenantId}/assistant/conversations": {
      "get": {
        "tags": ["Reporting"],
        "summary": "List assistant conversations (reporting format)",
        "description": "Returns assistant conversations in a reporting-friendly row format (no message content, cursor pagination).",
        "operationId": "listReportingBotConversations",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/reportingLimit" },
          { "$ref": "#/components/parameters/reportingCursor" },
          { "$ref": "#/components/parameters/reportingRange" },
          { "$ref": "#/components/parameters/reportingFrom" },
          { "$ref": "#/components/parameters/reportingTo" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BotConversationReportingResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/v1/reporting/tenants/{tenantId}/voc/conversations": {
      "get": {
        "tags": ["Reporting"],
        "summary": "List VOC conversations (reporting format)",
        "description": "Returns VOC conversations in a reporting-friendly row format (no transcript content, cursor pagination).",
        "operationId": "listReportingVocConversations",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/reportingLimit" },
          { "$ref": "#/components/parameters/reportingCursor" },
          { "$ref": "#/components/parameters/reportingRange" },
          { "$ref": "#/components/parameters/reportingFrom" },
          { "$ref": "#/components/parameters/reportingTo" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VocConversationReportingResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/v1/voc/tenants/{tenantId}/recording": {
      "post": {
        "tags": ["VOC"],
        "summary": "Upload a recording for VOC processing",
        "description": "Uploads an audio file and metadata, then starts an asynchronous VOC job.",
        "operationId": "uploadVocRecording",
        "parameters": [{ "$ref": "#/components/parameters/tenantId" }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": { "$ref": "#/components/schemas/VocUploadForm" }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VocUploadAcceptedResponse" },
                "examples": {
                  "example": { "value": { "id": "job-voc-001" } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    },
    "/api/v1/voc/tenants/{tenantId}/recording/{jobId}/status": {
      "get": {
        "tags": ["VOC"],
        "summary": "Get VOC job status",
        "description": "Returns the latest known status for a VOC recording job.",
        "operationId": "getVocJobStatus",
        "parameters": [
          { "$ref": "#/components/parameters/tenantId" },
          { "$ref": "#/components/parameters/jobId" }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VocJobStatus" },
                "examples": {
                  "started": {
                    "value": {
                      "id": "job-voc-001",
                      "status": "started",
                      "started": 1769557000000,
                      "file": "tenant-alpha/ingest/queue/uploads/call-123.mp3",
                      "recordingId": "call-123"
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/v1/mcp/tenants/{tenantId}/bots": {
      "post": {
        "tags": ["MCP"],
        "summary": "MCP bots endpoint (Streamable HTTP)",
        "description": "Streamable HTTP endpoint for the Bots MCP server. Requests and responses use JSON-RPC 2.0.",
        "operationId": "mcpBots",
        "parameters": [{ "$ref": "#/components/parameters/tenantId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" },
              "examples": {
                "toolsList": {
                  "value": {
                    "jsonrpc": "2.0",
                    "id": "tools",
                    "method": "tools/list"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/McpJsonRpcResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthenticated" },
          "403": { "$ref": "#/components/responses/PermissionDenied" },
          "500": { "$ref": "#/components/responses/InternalServerError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key"
      },
      "bearerTokenQuery": {
        "type": "apiKey",
        "in": "query",
        "name": "bearer_token",
        "description": "Alternative to the Authorization header. Prefer the Authorization header whenever possible."
      }
    },
    "parameters": {
      "tenantId": {
        "name": "tenantId",
        "in": "path",
        "required": true,
        "description": "Tenant identifier.",
        "schema": {
          "type": "string"
        }
      },
      "collection": {
        "name": "collection",
        "in": "path",
        "required": true,
        "description": "Collection name under the tenant (for example: `users`, `bots`, `jobs`).",
        "schema": {
          "type": "string"
        }
      },
      "docId": {
        "name": "docId",
        "in": "path",
        "required": true,
        "description": "Document identifier within the collection.",
        "schema": {
          "type": "string"
        }
      },
      "jobId": {
        "name": "jobId",
        "in": "path",
        "required": true,
        "description": "VOC job execution identifier returned by the upload endpoint.",
        "schema": {
          "type": "string"
        }
      },
      "reportingLimit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Max results per page. Default `1000`, max `5000`.",
        "schema": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 5000
        }
      },
      "reportingCursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "description": "Opaque cursor returned in `cursor.next`. When provided, do not also supply `range`, `from`, or `to`.",
        "schema": {
          "type": "string"
        }
      },
      "reportingRange": {
        "name": "range",
        "in": "query",
        "required": false,
        "description": "Convenience range selector. If omitted and `from` is omitted, defaults to `last_day`.",
        "schema": {
          "type": "string",
          "enum": ["last_day", "last_week", "last_month"]
        }
      },
      "reportingFrom": {
        "name": "from",
        "in": "query",
        "required": false,
        "description": "Range start. Accepts an ISO 8601 timestamp or epoch milliseconds.",
        "schema": {
          "oneOf": [
            { "type": "integer", "format": "int64", "description": "Epoch milliseconds." },
            { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp." }
          ]
        }
      },
      "reportingTo": {
        "name": "to",
        "in": "query",
        "required": false,
        "description": "Range end. Accepts an ISO 8601 timestamp or epoch milliseconds. Defaults to now.",
        "schema": {
          "oneOf": [
            { "type": "integer", "format": "int64", "description": "Epoch milliseconds." },
            { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp." }
          ]
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "example": {
                "value": { "code": "BadRequest", "message": "Invalid request parameters" }
              }
            }
          }
        }
      },
      "Unauthenticated": {
        "description": "Unauthenticated",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "example": {
                "value": { "code": "Unauthenticated", "message": "Authorization header with Bearer token is required" }
              }
            }
          }
        }
      },
      "PermissionDenied": {
        "description": "Permission denied",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "example": {
                "value": { "code": "PermissionDenied", "message": "API key does not allow this operation" }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "example": { "value": { "code": "NotFound", "message": "Resource not found" } }
            }
          }
        }
      },
      "Unavailable": {
        "description": "Upstream dependency unavailable",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "examples": {
              "example": { "value": { "code": "Unavailable", "message": "Elastic search failed" } }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": { "type": "string" }
              },
              "required": ["message"]
            },
            "examples": {
              "example": { "value": { "message": "Internal Server Error" } }
            }
          }
        }
      }
    },
    "schemas": {
      "AssistantMessageRequest": {
        "type": "object",
        "required": ["conversationId", "message"],
        "additionalProperties": true,
        "properties": {
          "conversationId": {"type": "string", "minLength": 1, "pattern": "\\S", "description": "Must contain non-whitespace text; original value is preserved."},
          "message": {"type": "string", "minLength": 1, "pattern": "\\S", "description": "Must contain non-whitespace text; original value is preserved."},
          "messageId": {
            "type": ["string", "null"],
            "minLength": 1,
            "pattern": "\\S",
            "description": "Nonempty caller message ID; omitted/null generates an ID."
          },
          "context": {
            "type": "object",
            "additionalProperties": true,
            "description": "Arbitrary business fields; context wins over duplicate business root keys. Null/arrays are invalid."
          }
        },
        "description": "All other root fields are arbitrary business input and are preserved. No business-key allowlist."
      },
      "AssistantMessageResult": {
        "type": "object",
        "required": ["conversationId", "messageId", "state", "handoff", "message", "tags"],
        "additionalProperties": true,
        "properties": {
          "conversationId": {"type": "string"},
          "messageId": {"type": "string"},
          "state": {
            "type": "string",
            "enum": ["active", "handed_off"]
          },
          "handoff": {"type": "boolean"},
          "message": {
            "type": ["string", "null"],
            "description": "Public plain text, possibly partial/empty; null for a retained completed handoff."
          },
          "tags": {
            "type": "array",
            "items": {"type": "string"},
            "uniqueItems": true,
            "description": "Includes c7o; completed handoff includes c7o_handoff."
          },
          "screenPopComment": {"type": "string", "description": "Present on a newly processed handoff."},
          "scriptResult": {"type": "object", "additionalProperties": true, "description": "Ticket Fields Script JSON result on a newly processed handoff."}
        }
      },
      "AssistantError": {
        "type": "object",
        "required": ["code", "message"],
        "additionalProperties": false,
        "properties": {
          "code": {"type": "string"},
          "message": {"type": "string", "description": "Sanitized public message."},
          "conversationId": {"type": "string"},
          "messageId": {"type": "string"},
          "action": {
            "type": "string",
            "enum": ["handoff"],
            "description": "Assistant fallback action on processing errors at HTTP 500 or above."
          }
        }
      },
      "ServiceInfo": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "version": { "type": "string" }
        },
        "required": ["name", "version"]
      },
      "HealthStatus": {
        "type": "object",
        "properties": {
          "status": { "type": "string" }
        },
        "required": ["status"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "code": { "type": "string" },
          "message": { "type": "string" }
        },
        "required": ["code", "message"]
      },
      "ProvisioningDocument": {
        "type": "object",
        "description": "Arbitrary JSON object representing the provisioning resource.",
        "additionalProperties": true
      },
      "ProvisioningCollectionEntry": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "required": ["id", "data"]
      },
      "ProvisioningCollectionResponse": {
        "type": "array",
        "items": { "$ref": "#/components/schemas/ProvisioningCollectionEntry" }
      },
      "ReportingCursor": {
        "type": "object",
        "properties": {
          "next": { "type": ["string", "null"] }
        },
        "required": ["next"]
      },
      "BotConversationRow": {
        "type": "object",
        "description": "Reporting row for a assistant conversation. Keys are optimized for reporting/exports.",
        "properties": {
          "ID": { "type": ["string", "null"] },
          "TenantID": { "type": ["string", "null"] },
          "BotID": { "type": ["string", "null"] },
          "BotName": { "type": ["string", "null"] },
          "Datetime": { "type": ["integer", "null"], "format": "int64", "description": "Epoch milliseconds." },
          "EndDatetime": { "type": ["integer", "null"], "format": "int64", "description": "Epoch milliseconds." },
          "DatetimeUTC": { "type": ["string", "null"], "format": "date-time" },
          "EndDatetimeUTC": { "type": ["string", "null"], "format": "date-time" },
          "Duration": { "type": "integer", "format": "int32", "description": "Duration in seconds." },
          "Escalated": { "type": ["boolean", "null"] },
          "escalatedAt": { "type": ["integer", "null"], "format": "int64", "description": "Epoch milliseconds from `state.escalatedAt`." },
          "CSat": { "type": ["number", "null"] },
          "AgentName": { "type": ["string", "null"] },
          "AgentId": { "type": ["string", "integer", "null"] },
          "AgentEmail": { "type": ["string", "null"] },
          "Category": { "type": ["string", "null"] },
          "Subcategory": { "type": ["string", "null"] },
          "Tertiary": { "type": ["string", "null"] },
          "RemoteIp": { "type": ["string", "null"] },
          "userAgent": { "type": ["string", "null"] },
          "Referrer": { "type": ["string", "null"] },
          "Media": {
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" } },
              { "type": "null" }
            ]
          },
          "Summary": { "type": ["string", "null"] },
          "Handoff Reason": { "type": ["string", "null"] },
          "ticketId": { "type": ["string", "integer", "null"] },
          "ticketUrl": { "type": ["string", "null"] },
          "ticketKind": { "type": ["string", "null"] },
          "Input": { "type": ["string", "null"] },
          "Contact Name": { "type": ["string", "null"] },
          "Contact Email": { "type": ["string", "null"] },
          "Contact Phone": { "type": ["string", "null"] }
        },
        "required": ["ID", "TenantID", "BotID", "BotName", "Datetime", "EndDatetime", "DatetimeUTC", "EndDatetimeUTC", "Duration"]
      },
      "BotConversationReportingResponse": {
        "type": "object",
        "properties": {
          "total": { "type": "integer", "format": "int64" },
          "cursor": { "$ref": "#/components/schemas/ReportingCursor" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/BotConversationRow" } }
        },
        "required": ["total", "cursor", "data"]
      },
      "VocConversationRow": {
        "type": "object",
        "description": "Reporting row for a VOC conversation. Keys are optimized for reporting/exports.",
        "properties": {
          "ID": { "type": ["string", "null"] },
          "TenantID": { "type": ["string", "null"] },
          "Datetime": { "type": ["string", "null"], "format": "date-time" },
          "DatetimeUTC": { "type": ["string", "null"], "format": "date-time" },
          "Duration": { "type": ["integer", "null"], "format": "int32" },
          "Direction": { "type": ["string", "null"] },
          "Media": { "type": ["string", "null"] },
          "AgentName": { "type": ["string", "null"] },
          "AgentId": { "type": ["string", "integer", "null"] },
          "AgentEmail": { "type": ["string", "null"] },
          "CustomerName": { "type": ["string", "null"] },
          "CustomerId": { "type": ["string", "integer", "null"] },
          "CustomerEmail": { "type": ["string", "null"] },
          "Groups": {
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" } },
              { "type": "null" }
            ]
          },
          "Tags": {
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" } },
              { "type": "null" }
            ]
          },
          "Category": { "type": ["string", "null"] },
          "Subcategory": { "type": ["string", "null"] },
          "Tertiary": { "type": ["string", "null"] },
          "CategoryExplanation": { "type": ["string", "null"] },
          "CategoriesId": { "type": ["string", "null"] },
          "Summary": { "type": ["string", "null"] },
          "CSat": { "type": ["number", "null"] },
          "CSatExplanation": { "type": ["string", "null"] },
          "Sentiment": { "type": ["number", "null"] },
          "SentimentExplanation": { "type": ["string", "null"] },
          "Problems": { "type": ["array", "null"], "items": { "type": "object", "additionalProperties": true } },
          "KPIs": { "type": ["array", "null"], "items": { "type": "object", "additionalProperties": true } },
          "SourceSystem": { "type": ["string", "null"] },
          "TicketId": { "type": ["string", "integer", "null"] },
          "TicketUrl": { "type": ["string", "null"] }
        }
      },
      "VocConversationReportingResponse": {
        "type": "object",
        "properties": {
          "total": { "type": "integer", "format": "int64" },
          "cursor": { "$ref": "#/components/schemas/ReportingCursor" },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/VocConversationRow" } }
        },
        "required": ["total", "cursor", "data"]
      },
      "VocUploadForm": {
        "type": "object",
        "properties": {
          "audio": {
            "type": "string",
            "format": "binary",
            "description": "Audio file (mp3 or wav)."
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "Alternative field name for the audio file (mp3 or wav)."
          },
          "metadata": {
            "type": "string",
            "description": "JSON string containing recording metadata. Must include `id`."
          }
        },
        "required": ["metadata"]
      },
      "VocUploadAcceptedResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" }
        },
        "required": ["id"]
      },
      "VocJobStatus": {
        "type": "object",
        "description": "VOC job status payload. Fields may vary depending on job stage.",
        "properties": {
          "id": { "type": "string" },
          "status": { "type": "string", "enum": ["started", "completed", "failed"] },
          "started": { "type": "integer", "format": "int64" },
          "finished": { "type": ["integer", "null"], "format": "int64" },
          "file": { "type": ["string", "null"] },
          "recordingId": { "type": ["string", "null"] },
          "result": { "type": ["object", "null"], "additionalProperties": true },
          "error": { "type": ["string", "null"] }
        },
        "required": ["id", "status", "started"]
      },
      "McpJsonRpcRequest": {
        "type": "object",
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "type": ["string", "number", "null"] },
          "method": { "type": "string" },
          "params": { "type": ["object", "null"], "additionalProperties": true }
        },
        "required": ["jsonrpc", "method"]
      },
      "McpJsonRpcResponse": {
        "type": "object",
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0" },
          "id": { "type": ["string", "number", "null"] },
          "result": { "type": ["object", "null"], "additionalProperties": true },
          "error": {
            "type": ["object", "null"],
            "additionalProperties": true
          }
        },
        "required": ["jsonrpc"]
      }
    }
  }
}
