{
  "components": {
    "responses": {
      "Error400": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "invalid_argument",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#invalid_argument",
                "message": "A parameter is invalid; the message says which.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "invalid_request_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Invalid request. Codes: content_too_large, context_not_allowed_in_group, context_too_large, invalid_argument, invalid_cursor, invalid_idempotency_key, invalid_webhook."
      },
      "Error401": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "invalid_api_key",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#invalid_api_key",
                "message": "The key is missing, malformed, unknown, expired or revoked.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "authentication_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Missing or invalid API key. Codes: invalid_api_key."
      },
      "Error402": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "credits_exhausted",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#credits_exhausted",
                "message": "The agent's AI credits are used up. Nothing was stored.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "payment_required_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "AI credits used up. Codes: credits_exhausted, usage_limit_reached."
      },
      "Error403": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "insufficient_scope",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#insufficient_scope",
                "message": "The integration lacks the scope the endpoint requires.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "permission_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Scope, role or plan does not allow it. Codes: access_denied, all_agents_required, api_not_enabled, insufficient_scope, plan_limit_reached, plan_restricted, read_only_integration."
      },
      "Error404": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "not_found",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#not_found",
                "message": "The resource does not exist or belongs to another workspace or integration.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "not_found_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Not found. Codes: not_found."
      },
      "Error409": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "version_conflict",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#version_conflict",
                "message": "expected_version or expected_revision is outdated. Read the resource again.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "conflict_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Conflict. Codes: ambiguous_conversation, conversation_agent_mismatch, conversation_deleted, conversation_mismatch, endpoint_disabled, endpoint_limit, idempotency_conflict, operation_in_progress, plan_unavailable, request_in_progress, retryable_conflict, session_ended, version_conflict."
      },
      "Error422": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "validation_error",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#validation_error",
                "message": "The request body or a query parameter is invalid; `errors` lists the fields.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "invalid_request_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Validation error. Codes: validation_error."
      },
      "Error429": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "rate_limit_exceeded",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#rate_limit_exceeded",
                "message": "More requests per minute than allowed. Retry after Retry-After.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "rate_limit_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Rate or concurrency limit (Retry-After). Codes: concurrency_limit_exceeded, queue_limit_exceeded, rate_limit_exceeded, too_many_failed_attempts."
      },
      "Error500": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "internal_error",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#internal_error",
                "message": "An internal error. Retry; contact support with the request id if it stays.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "api_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Internal error. Codes: expired, generation_failed, integration_revoked, internal_error, interrupted."
      },
      "Error503": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "api_capacity_exhausted",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#api_capacity_exhausted",
                "message": "The API is at capacity. Retry after Retry-After or use async.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "service_unavailable_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Temporarily unavailable (Retry-After). Codes: api_capacity_exhausted, feature_unavailable, provider_unavailable, upload_unavailable, worker_unavailable."
      },
      "Error504": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "generation_timeout",
                "doc_url": "https://docs.ultimo-bots.com/api/errors#generation_timeout",
                "message": "The agent did not finish within 120 seconds.",
                "request_id": "req_cdf59285141a839feba3b644",
                "type": "api_error"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "The agent did not finish within 120 s. Codes: generation_timeout."
      }
    },
    "schemas": {
      "Agent": {
        "properties": {
          "api_access": {
            "default": true,
            "description": "false: the plan of this agent does not include the API; calls for it answer 403 plan_restricted.",
            "title": "Api Access",
            "type": "boolean"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name"
          },
          "object": {
            "const": "agent",
            "default": "agent",
            "title": "Object",
            "type": "string"
          },
          "status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Status"
          },
          "website_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Website Url"
          }
        },
        "required": [
          "id",
          "name",
          "status",
          "website_url",
          "created_at"
        ],
        "title": "Agent",
        "type": "object"
      },
      "AgentConversation": {
        "additionalProperties": true,
        "properties": {
          "api_conversation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "conv_... when the conversation came through the API.",
            "title": "Api Conversation Id"
          },
          "first_activity": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "First Activity"
          },
          "last_activity": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Last Activity"
          },
          "message_count": {
            "title": "Message Count",
            "type": "integer"
          },
          "object": {
            "const": "agent_conversation",
            "default": "agent_conversation",
            "title": "Object",
            "type": "string"
          },
          "reference": {
            "description": "Use it in GET /v1/agents/{agent_id}/conversations/{reference}/messages.",
            "title": "Reference",
            "type": "string"
          },
          "visitor_messages": {
            "title": "Visitor Messages",
            "type": "integer"
          }
        },
        "required": [
          "reference",
          "message_count",
          "visitor_messages"
        ],
        "title": "AgentConversation",
        "type": "object"
      },
      "AgentConversationList": {
        "additionalProperties": true,
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AgentConversation"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "AgentConversationList",
        "type": "object"
      },
      "AgentConversationMessage": {
        "additionalProperties": true,
        "properties": {
          "content": {
            "title": "Content",
            "type": "string"
          },
          "content_truncated": {
            "default": false,
            "title": "Content Truncated",
            "type": "boolean"
          },
          "id": {
            "title": "Id",
            "type": "integer"
          },
          "platform": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The channel: website, whatsapp, api, ...",
            "title": "Platform"
          },
          "timestamp": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Timestamp"
          },
          "type": {
            "description": "user_input (the end user), assistant (the agent) or agent (a person of the business).",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "content"
        ],
        "title": "AgentConversationMessage",
        "type": "object"
      },
      "AgentConversationMessageList": {
        "additionalProperties": true,
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AgentConversationMessage"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "AgentConversationMessageList",
        "type": "object"
      },
      "AgentList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Agent"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "AgentList",
        "type": "object"
      },
      "AutoResponse": {
        "additionalProperties": false,
        "properties": {
          "enabled": {
            "description": "false: messages are stored, the agent stays silent (no credits).",
            "title": "Enabled",
            "type": "boolean"
          }
        },
        "required": [
          "enabled"
        ],
        "title": "AutoResponse",
        "type": "object"
      },
      "Behaviors": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "allowance": {
            "additionalProperties": true,
            "description": "How many behavior rules the plan allows and how many exist.",
            "title": "Allowance",
            "type": "object"
          },
          "behaviors": {
            "description": "The owner's behavior rules as the AI Studio shows them.",
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Behaviors",
            "type": "array"
          },
          "definition_version": {
            "title": "Definition Version",
            "type": "integer"
          },
          "system_instructions": {
            "items": {
              "$ref": "#/components/schemas/SystemInstruction"
            },
            "title": "System Instructions",
            "type": "array"
          }
        },
        "required": [
          "agent_id",
          "definition_version",
          "behaviors",
          "system_instructions",
          "allowance"
        ],
        "title": "Behaviors",
        "type": "object"
      },
      "BusinessContext": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "business_context": {
            "title": "Business Context",
            "type": "string"
          },
          "version": {
            "description": "Pass it as expected_version when you replace the text.",
            "title": "Version",
            "type": "integer"
          }
        },
        "required": [
          "agent_id",
          "business_context",
          "version"
        ],
        "title": "BusinessContext",
        "type": "object"
      },
      "BusinessContextPut": {
        "additionalProperties": false,
        "properties": {
          "business_context": {
            "description": "The whole text (replaces it). Empty clears it.",
            "maxLength": 1000,
            "title": "Business Context",
            "type": "string"
          },
          "expected_version": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Version from GET; a changed version answers 409.",
            "title": "Expected Version"
          }
        },
        "required": [
          "business_context"
        ],
        "title": "BusinessContextPut",
        "type": "object"
      },
      "BusinessContextUpdated": {
        "additionalProperties": true,
        "properties": {
          "context": {
            "$ref": "#/components/schemas/BusinessContext"
          },
          "replayed": {
            "description": "true: this Idempotency-Key was used before, the stored result is returned.",
            "title": "Replayed",
            "type": "boolean"
          }
        },
        "required": [
          "context",
          "replayed"
        ],
        "title": "BusinessContextUpdated",
        "type": "object"
      },
      "Conversation": {
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "auto_response": {
            "title": "Auto Response",
            "type": "boolean"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "external_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "External Id"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "last_activity_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Activity At"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "object": {
            "const": "conversation",
            "default": "conversation",
            "title": "Object",
            "type": "string"
          },
          "type": {
            "enum": [
              "direct",
              "group"
            ],
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "id",
          "agent_id",
          "external_id",
          "type",
          "metadata",
          "auto_response",
          "created_at",
          "last_activity_at"
        ],
        "title": "Conversation",
        "type": "object"
      },
      "ConversationList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Conversation"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "ConversationList",
        "type": "object"
      },
      "Credits": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "available": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "What the agent can still spend in this period.",
            "title": "Available"
          },
          "object": {
            "const": "credits",
            "default": "credits",
            "title": "Object",
            "type": "string"
          },
          "plan_allowance": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Plan Allowance"
          },
          "plan_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Plan Name"
          },
          "unit": {
            "enum": [
              "credits",
              "answers"
            ],
            "title": "Unit",
            "type": "string"
          }
        },
        "required": [
          "agent_id",
          "unit"
        ],
        "title": "Credits",
        "type": "object"
      },
      "CreditsEvent": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "allowance": {
            "title": "Allowance",
            "type": "integer"
          },
          "object": {
            "const": "credits",
            "default": "credits",
            "title": "Object",
            "type": "string"
          },
          "remaining": {
            "title": "Remaining",
            "type": "integer"
          },
          "unit": {
            "enum": [
              "credits",
              "answers"
            ],
            "title": "Unit",
            "type": "string"
          },
          "window_start": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Window Start"
          }
        },
        "required": [
          "agent_id",
          "remaining",
          "allowance",
          "unit"
        ],
        "title": "CreditsEvent",
        "type": "object"
      },
      "Deleted": {
        "properties": {
          "deleted": {
            "title": "Deleted",
            "type": "boolean"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "object": {
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "id",
          "object",
          "deleted"
        ],
        "title": "Deleted",
        "type": "object"
      },
      "Delivery": {
        "additionalProperties": true,
        "properties": {
          "attempts": {
            "title": "Attempts",
            "type": "integer"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created At"
          },
          "delivered_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Delivered At"
          },
          "endpoint_id": {
            "title": "Endpoint Id",
            "type": "string"
          },
          "event_id": {
            "title": "Event Id",
            "type": "string"
          },
          "event_type": {
            "title": "Event Type",
            "type": "string"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "last_duration_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Last Duration Ms"
          },
          "last_error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Last Error"
          },
          "last_status_code": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Last Status Code"
          },
          "next_attempt_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Next Attempt At"
          },
          "object": {
            "const": "webhook_delivery",
            "default": "webhook_delivery",
            "title": "Object",
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "delivering",
              "succeeded",
              "failed"
            ],
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "id",
          "event_id",
          "event_type",
          "endpoint_id",
          "status",
          "attempts"
        ],
        "title": "Delivery",
        "type": "object"
      },
      "Embed": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "chat_url": {
            "title": "Chat Url",
            "type": "string"
          },
          "iframe_html": {
            "title": "Iframe Html",
            "type": "string"
          },
          "website_html": {
            "title": "Website Html",
            "type": "string"
          }
        },
        "required": [
          "agent_id",
          "website_html",
          "iframe_html",
          "chat_url"
        ],
        "title": "Embed",
        "type": "object"
      },
      "EndUser": {
        "additionalProperties": false,
        "properties": {
          "id": {
            "anyOf": [
              {
                "maxLength": 200,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your id of the person who wrote the message. No personal data in ids.",
            "title": "Id"
          },
          "name": {
            "anyOf": [
              {
                "maxLength": 100,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Display name; the agent sees the message as \"<name>: <text>\".",
            "title": "Name"
          }
        },
        "title": "EndUser",
        "type": "object"
      },
      "EndpointCreate": {
        "additionalProperties": false,
        "properties": {
          "description": {
            "default": "",
            "maxLength": 500,
            "title": "Description",
            "type": "string"
          },
          "events": {
            "description": "Event types to receive.",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "minItems": 1,
            "title": "Events",
            "type": "array"
          },
          "url": {
            "description": "Public https address of your receiver.",
            "maxLength": 2048,
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "url",
          "events"
        ],
        "title": "EndpointCreate",
        "type": "object"
      },
      "EndpointCreated": {
        "additionalProperties": true,
        "properties": {
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "events": {
            "items": {
              "type": "string"
            },
            "title": "Events",
            "type": "array"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "integration_id": {
            "title": "Integration Id",
            "type": "string"
          },
          "object": {
            "const": "webhook_endpoint",
            "default": "webhook_endpoint",
            "title": "Object",
            "type": "string"
          },
          "secret": {
            "description": "whsec_... Shown only in this response. Verify signatures with it.",
            "title": "Secret",
            "type": "string"
          },
          "secret_last4": {
            "title": "Secret Last4",
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "disabled"
            ],
            "title": "Status",
            "type": "string"
          },
          "url": {
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "id",
          "integration_id",
          "url",
          "events",
          "status",
          "secret_last4",
          "created_at",
          "secret"
        ],
        "title": "EndpointCreated",
        "type": "object"
      },
      "EndpointObject": {
        "additionalProperties": true,
        "properties": {
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "events": {
            "items": {
              "type": "string"
            },
            "title": "Events",
            "type": "array"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "integration_id": {
            "title": "Integration Id",
            "type": "string"
          },
          "object": {
            "const": "webhook_endpoint",
            "default": "webhook_endpoint",
            "title": "Object",
            "type": "string"
          },
          "secret_last4": {
            "title": "Secret Last4",
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "disabled"
            ],
            "title": "Status",
            "type": "string"
          },
          "url": {
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "id",
          "integration_id",
          "url",
          "events",
          "status",
          "secret_last4",
          "created_at"
        ],
        "title": "EndpointObject",
        "type": "object"
      },
      "EndpointPatch": {
        "additionalProperties": false,
        "properties": {
          "description": {
            "anyOf": [
              {
                "maxLength": 500,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "events": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "maxItems": 20,
                "minItems": 1,
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Events"
          },
          "status": {
            "anyOf": [
              {
                "enum": [
                  "active",
                  "disabled"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Status"
          },
          "url": {
            "anyOf": [
              {
                "maxLength": 2048,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Url"
          }
        },
        "title": "EndpointPatch",
        "type": "object"
      },
      "Error": {
        "properties": {
          "error": {
            "additionalProperties": true,
            "properties": {
              "code": {
                "description": "Stable machine-readable code, see x-error-codes.",
                "type": "string"
              },
              "doc_url": {
                "type": "string"
              },
              "message": {
                "description": "For people; do not parse it.",
                "type": "string"
              },
              "request_id": {
                "description": "Also in the X-Request-Id header. Name it to support.",
                "type": "string"
              },
              "type": {
                "enum": [
                  "api_error",
                  "authentication_error",
                  "conflict_error",
                  "invalid_request_error",
                  "not_found_error",
                  "payment_required_error",
                  "permission_error",
                  "rate_limit_error",
                  "service_unavailable_error"
                ],
                "type": "string"
              }
            },
            "required": [
              "type",
              "code",
              "message",
              "request_id"
            ],
            "type": "object"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "EventList": {
        "additionalProperties": true,
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/EventWithDeliveries"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "EventList",
        "type": "object"
      },
      "EventResent": {
        "additionalProperties": true,
        "properties": {
          "id": {
            "title": "Id",
            "type": "string"
          },
          "object": {
            "const": "event",
            "default": "event",
            "title": "Object",
            "type": "string"
          },
          "requeued_deliveries": {
            "title": "Requeued Deliveries",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "requeued_deliveries"
        ],
        "title": "EventResent",
        "type": "object"
      },
      "EventWithDeliveries": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Agent Id"
          },
          "api_version": {
            "const": "v1",
            "default": "v1",
            "title": "Api Version",
            "type": "string"
          },
          "conversation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Conversation Id"
          },
          "created_at": {
            "title": "Created At",
            "type": "string"
          },
          "data": {
            "additionalProperties": true,
            "title": "Data",
            "type": "object"
          },
          "deliveries": {
            "items": {
              "$ref": "#/components/schemas/Delivery"
            },
            "title": "Deliveries",
            "type": "array"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "object": {
            "const": "event",
            "default": "event",
            "title": "Object",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "created_at",
          "data",
          "deliveries"
        ],
        "title": "EventWithDeliveries",
        "type": "object"
      },
      "Export": {
        "additionalProperties": true,
        "properties": {
          "csv": {
            "title": "Csv",
            "type": "string"
          },
          "filename": {
            "title": "Filename",
            "type": "string"
          },
          "mime_type": {
            "title": "Mime Type",
            "type": "string"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "row_count": {
            "title": "Row Count",
            "type": "integer"
          }
        },
        "required": [
          "filename",
          "mime_type",
          "csv",
          "row_count",
          "next_cursor"
        ],
        "title": "Export",
        "type": "object"
      },
      "ExportBody": {
        "additionalProperties": false,
        "properties": {
          "after": {
            "anyOf": [
              {
                "maxLength": 20,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "After"
          },
          "end_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "End Date"
          },
          "kind": {
            "enum": [
              "conversations",
              "leads"
            ],
            "title": "Kind",
            "type": "string"
          },
          "limit": {
            "default": 100,
            "maximum": 100.0,
            "minimum": 1.0,
            "title": "Limit",
            "type": "integer"
          },
          "start_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Start Date"
          }
        },
        "required": [
          "kind"
        ],
        "title": "ExportBody",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "Handoff": {
        "properties": {
          "requested": {
            "description": "A person of the business has been asked to take over (or has taken over).",
            "title": "Requested",
            "type": "boolean"
          },
          "status": {
            "anyOf": [
              {
                "enum": [
                  "agent_requested",
                  "agent_joined"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Status"
          }
        },
        "required": [
          "requested"
        ],
        "title": "Handoff",
        "type": "object"
      },
      "HandoffEvent": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "conversation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Conversation Id"
          },
          "ended_reason": {
            "anyOf": [
              {
                "enum": [
                  "session_ended",
                  "returned_to_agent"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Only on handoff.ended.",
            "title": "Ended Reason"
          },
          "object": {
            "const": "handoff",
            "default": "handoff",
            "title": "Object",
            "type": "string"
          },
          "requested_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Requested At"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Status"
          },
          "visitor_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Visitor Name"
          }
        },
        "required": [
          "session_id",
          "agent_id"
        ],
        "title": "HandoffEvent",
        "type": "object"
      },
      "Insights": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "daily": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Daily",
            "type": "array"
          },
          "end_date": {
            "title": "End Date",
            "type": "string"
          },
          "start_date": {
            "title": "Start Date",
            "type": "string"
          },
          "timezone": {
            "title": "Timezone",
            "type": "string"
          },
          "totals": {
            "additionalProperties": true,
            "title": "Totals",
            "type": "object"
          }
        },
        "required": [
          "agent_id",
          "start_date",
          "end_date",
          "timezone",
          "totals",
          "daily"
        ],
        "title": "Insights",
        "type": "object"
      },
      "KnowledgeCreate": {
        "additionalProperties": false,
        "properties": {
          "text": {
            "anyOf": [
              {
                "maxLength": 60000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "type faq: the answer text",
            "title": "Text"
          },
          "title": {
            "maxLength": 500,
            "minLength": 1,
            "title": "Title",
            "type": "string"
          },
          "type": {
            "enum": [
              "website",
              "faq",
              "document"
            ],
            "title": "Type",
            "type": "string"
          },
          "upload_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "type document: upload_id from POST .../knowledge/uploads",
            "title": "Upload Id"
          },
          "url": {
            "anyOf": [
              {
                "maxLength": 2048,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "type website: the page or sitemap address",
            "title": "Url"
          }
        },
        "required": [
          "type",
          "title"
        ],
        "title": "KnowledgeCreate",
        "type": "object"
      },
      "KnowledgePut": {
        "additionalProperties": false,
        "properties": {
          "expected_revision": {
            "description": "revision from GET .../knowledge/{id}",
            "maxLength": 64,
            "minLength": 1,
            "title": "Expected Revision",
            "type": "string"
          },
          "text": {
            "anyOf": [
              {
                "maxLength": 60000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "FAQ: new answer",
            "title": "Text"
          },
          "title": {
            "anyOf": [
              {
                "maxLength": 500,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "FAQ: new question/title",
            "title": "Title"
          },
          "upload_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Document: replace with this upload",
            "title": "Upload Id"
          }
        },
        "required": [
          "expected_revision"
        ],
        "title": "KnowledgePut",
        "type": "object"
      },
      "KnowledgeSource": {
        "additionalProperties": true,
        "properties": {
          "can_refresh": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Can Refresh"
          },
          "content_length": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Content Length"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created At"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "document_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Document Name"
          },
          "download_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Download Url"
          },
          "downloadable": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Downloadable"
          },
          "failure_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Failure Code"
          },
          "failure_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Failure Reason"
          },
          "id": {
            "title": "Id",
            "type": "integer"
          },
          "revision": {
            "description": "Pass it as expected_revision when you change, refresh or delete the source.",
            "title": "Revision",
            "type": "string"
          },
          "source_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "website, faq, document or a cloud source.",
            "title": "Source Type"
          },
          "status": {
            "description": "completed, failed, scraping or deleting.",
            "title": "Status",
            "type": "string"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Title"
          },
          "type": {
            "description": "Stored type, e.g. faq, url_link, document.",
            "title": "Type",
            "type": "string"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Url"
          }
        },
        "required": [
          "id",
          "type",
          "status",
          "revision"
        ],
        "title": "KnowledgeSource",
        "type": "object"
      },
      "KnowledgeSourceContent": {
        "additionalProperties": true,
        "properties": {
          "can_refresh": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Can Refresh"
          },
          "content": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The text of the source, from content_offset on.",
            "title": "Content"
          },
          "content_length": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Content Length"
          },
          "content_offset": {
            "default": 0,
            "title": "Content Offset",
            "type": "integer"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created At"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "document_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Document Name"
          },
          "download_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Download Url"
          },
          "downloadable": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Downloadable"
          },
          "failure_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Failure Code"
          },
          "failure_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Failure Reason"
          },
          "id": {
            "title": "Id",
            "type": "integer"
          },
          "next_offset": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Offset of the next page, null at the end.",
            "title": "Next Offset"
          },
          "revision": {
            "description": "Pass it as expected_revision when you change, refresh or delete the source.",
            "title": "Revision",
            "type": "string"
          },
          "source_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "website, faq, document or a cloud source.",
            "title": "Source Type"
          },
          "status": {
            "description": "completed, failed, scraping or deleting.",
            "title": "Status",
            "type": "string"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Title"
          },
          "type": {
            "description": "Stored type, e.g. faq, url_link, document.",
            "title": "Type",
            "type": "string"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Url"
          }
        },
        "required": [
          "id",
          "type",
          "status",
          "revision"
        ],
        "title": "KnowledgeSourceContent",
        "type": "object"
      },
      "KnowledgeSourceList": {
        "additionalProperties": true,
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/KnowledgeSource"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "KnowledgeSourceList",
        "type": "object"
      },
      "Lead": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/LeadData"
          },
          "resource_id": {
            "title": "Resource Id",
            "type": "string"
          },
          "version": {
            "title": "Version",
            "type": "integer"
          }
        },
        "required": [
          "agent_id",
          "resource_id",
          "version",
          "data"
        ],
        "title": "Lead",
        "type": "object"
      },
      "LeadData": {
        "additionalProperties": true,
        "properties": {
          "date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Date"
          },
          "id": {
            "title": "Id",
            "type": "integer"
          },
          "params": {
            "additionalProperties": true,
            "description": "The fields the visitor gave (name, email, ...).",
            "title": "Params",
            "type": "object"
          },
          "read": {
            "title": "Read",
            "type": "boolean"
          },
          "session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Session Id"
          },
          "type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Type"
          }
        },
        "required": [
          "id",
          "params",
          "read"
        ],
        "title": "LeadData",
        "type": "object"
      },
      "LeadDeleted": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "deleted": {
            "title": "Deleted",
            "type": "boolean"
          },
          "id": {
            "title": "Id",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "agent_id",
          "deleted"
        ],
        "title": "LeadDeleted",
        "type": "object"
      },
      "LeadEvent": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "conversation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "conv_... when the lead came from an API conversation.",
            "title": "Conversation Id"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created At"
          },
          "fields": {
            "additionalProperties": true,
            "title": "Fields",
            "type": "object"
          },
          "id": {
            "title": "Id",
            "type": "integer"
          },
          "object": {
            "const": "lead",
            "default": "lead",
            "title": "Object",
            "type": "string"
          },
          "read": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Read"
          },
          "session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Session Id"
          },
          "type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Type"
          }
        },
        "required": [
          "id",
          "agent_id",
          "fields"
        ],
        "title": "LeadEvent",
        "type": "object"
      },
      "LeadList": {
        "additionalProperties": true,
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/LeadSummary"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "LeadList",
        "type": "object"
      },
      "LeadPatchBody": {
        "additionalProperties": false,
        "properties": {
          "expected_version": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Expected Version"
          },
          "read": {
            "title": "Read",
            "type": "boolean"
          }
        },
        "required": [
          "read"
        ],
        "title": "LeadPatchBody",
        "type": "object"
      },
      "LeadSummary": {
        "additionalProperties": true,
        "properties": {
          "date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Date"
          },
          "id": {
            "title": "Id",
            "type": "integer"
          },
          "read": {
            "title": "Read",
            "type": "boolean"
          },
          "session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Session Id"
          },
          "type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Type"
          },
          "version": {
            "title": "Version",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "read",
          "version"
        ],
        "title": "LeadSummary",
        "type": "object"
      },
      "LeadUpdated": {
        "additionalProperties": true,
        "properties": {
          "replayed": {
            "title": "Replayed",
            "type": "boolean"
          },
          "resource": {
            "$ref": "#/components/schemas/Lead"
          }
        },
        "required": [
          "resource",
          "replayed"
        ],
        "title": "LeadUpdated",
        "type": "object"
      },
      "LiveSession": {
        "additionalProperties": true,
        "properties": {
          "agent_display_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Agent Display Name"
          },
          "agent_requested_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Agent Requested At"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created At"
          },
          "last_activity": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Last Activity"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "status": {
            "description": "agent_requested (waiting for a person) or agent_joined.",
            "title": "Status",
            "type": "string"
          },
          "visitor_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Visitor Name"
          }
        },
        "required": [
          "session_id",
          "status"
        ],
        "title": "LiveSession",
        "type": "object"
      },
      "LiveSessionList": {
        "additionalProperties": true,
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/LiveSession"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "LiveSessionList",
        "type": "object"
      },
      "Message": {
        "properties": {
          "content": {
            "title": "Content",
            "type": "string"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "end_user": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "End User"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "default": {},
            "title": "Metadata",
            "type": "object"
          },
          "object": {
            "const": "message",
            "default": "message",
            "title": "Object",
            "type": "string"
          },
          "role": {
            "enum": [
              "user",
              "assistant",
              "staff"
            ],
            "title": "Role",
            "type": "string"
          }
        },
        "required": [
          "id",
          "role",
          "content",
          "created_at"
        ],
        "title": "Message",
        "type": "object"
      },
      "MessageList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Message"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "MessageList",
        "type": "object"
      },
      "Operation": {
        "additionalProperties": true,
        "properties": {
          "action": {
            "title": "Action",
            "type": "string"
          },
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "attempts": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Attempts"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created At"
          },
          "error_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Error Code"
          },
          "finished_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Finished At"
          },
          "knowledge_ids": {
            "default": [],
            "items": {
              "type": "integer"
            },
            "title": "Knowledge Ids",
            "type": "array"
          },
          "operation_id": {
            "title": "Operation Id",
            "type": "string"
          },
          "result": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Result"
          },
          "status": {
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed"
            ],
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "operation_id",
          "agent_id",
          "action",
          "status"
        ],
        "title": "Operation",
        "type": "object"
      },
      "OperationAccepted": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "knowledge_ids": {
            "default": [],
            "items": {
              "type": "integer"
            },
            "title": "Knowledge Ids",
            "type": "array"
          },
          "operation_id": {
            "title": "Operation Id",
            "type": "string"
          },
          "replayed": {
            "default": false,
            "title": "Replayed",
            "type": "boolean"
          },
          "status": {
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed"
            ],
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "operation_id",
          "status",
          "agent_id"
        ],
        "title": "OperationAccepted",
        "type": "object"
      },
      "OperationEvent": {
        "additionalProperties": true,
        "properties": {
          "action": {
            "title": "Action",
            "type": "string"
          },
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created At"
          },
          "error_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Error Code"
          },
          "finished_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Finished At"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "object": {
            "const": "operation",
            "default": "operation",
            "title": "Object",
            "type": "string"
          },
          "result": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Result"
          },
          "status": {
            "enum": [
              "completed",
              "failed"
            ],
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "id",
          "agent_id",
          "action",
          "status"
        ],
        "title": "OperationEvent",
        "type": "object"
      },
      "Output": {
        "properties": {
          "format": {
            "enum": [
              "markdown",
              "text"
            ],
            "title": "Format",
            "type": "string"
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Language"
          },
          "text": {
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "text",
          "format"
        ],
        "title": "Output",
        "type": "object"
      },
      "RefreshBody": {
        "additionalProperties": false,
        "properties": {
          "sources": {
            "description": "[{\"knowledge_id\": 1, \"expected_revision\": \"...\"}]",
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "maxItems": 100,
            "minItems": 1,
            "title": "Sources",
            "type": "array"
          }
        },
        "required": [
          "sources"
        ],
        "title": "RefreshBody",
        "type": "object"
      },
      "ResponseCreate": {
        "additionalProperties": false,
        "properties": {
          "agent_id": {
            "description": "Agent id from GET /v1/agents.",
            "maxLength": 200,
            "minLength": 1,
            "title": "Agent Id",
            "type": "string"
          },
          "async": {
            "default": false,
            "description": "Return 202 at once and poll GET /v1/responses/{id}.",
            "title": "Async",
            "type": "boolean"
          },
          "context": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Data from your system for this answer only (e.g. CRM fields). Never stored in the history.",
            "title": "Context"
          },
          "conversation_id": {
            "anyOf": [
              {
                "maxLength": 64,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Continue an existing conversation (conv_...).",
            "title": "Conversation Id"
          },
          "conversation_metadata": {
            "anyOf": [
              {
                "additionalProperties": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "integer"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Key-value data stored on the conversation.",
            "title": "Conversation Metadata"
          },
          "conversation_type": {
            "anyOf": [
              {
                "enum": [
                  "direct",
                  "group"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "direct (default) or group (several people in one channel). Set when the conversation is created. In a group conversation `context` is not accepted.",
            "title": "Conversation Type"
          },
          "end_user": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/EndUser"
              },
              {
                "type": "null"
              }
            ]
          },
          "external_id": {
            "anyOf": [
              {
                "maxLength": 200,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Your id of the conversation (channel, thread, ticket). Created on first use.",
            "title": "External Id"
          },
          "format": {
            "default": "markdown",
            "description": "Answer as Markdown (default) or plain text.",
            "enum": [
              "markdown",
              "text"
            ],
            "title": "Format",
            "type": "string"
          },
          "include": {
            "description": "Structured extras: product cards and quick-reply choices. Off by default.",
            "items": {
              "enum": [
                "products",
                "choices"
              ],
              "type": "string"
            },
            "title": "Include",
            "type": "array"
          },
          "input": {
            "description": "The message, at most 4000 characters.",
            "maxLength": 4000,
            "minLength": 1,
            "title": "Input",
            "type": "string"
          },
          "metadata": {
            "anyOf": [
              {
                "additionalProperties": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "integer"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Key-value data of this message, returned with the response.",
            "title": "Metadata"
          },
          "stream": {
            "default": false,
            "description": "Server-sent events instead of one JSON response.",
            "title": "Stream",
            "type": "boolean"
          }
        },
        "required": [
          "agent_id",
          "input"
        ],
        "title": "ResponseCreate",
        "type": "object"
      },
      "ResponseObject": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "choices": {
            "anyOf": [
              {
                "items": {},
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Only with include=[\"choices\"].",
            "title": "Choices"
          },
          "completed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Completed At"
          },
          "conversation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Conversation Id"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "end_user": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "End User"
          },
          "error": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Error"
          },
          "external_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "External Id"
          },
          "handoff": {
            "$ref": "#/components/schemas/Handoff"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "input_message_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Input Message Id"
          },
          "metadata": {
            "additionalProperties": true,
            "default": {},
            "title": "Metadata",
            "type": "object"
          },
          "mode": {
            "enum": [
              "sync",
              "stream",
              "async"
            ],
            "title": "Mode",
            "type": "string"
          },
          "object": {
            "const": "response",
            "default": "response",
            "title": "Object",
            "type": "string"
          },
          "output": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Output"
              },
              {
                "type": "null"
              }
            ],
            "description": "The answer. Null while queued, on failure, during a human handoff or when answers are off for the conversation."
          },
          "output_message_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Output Message Id"
          },
          "products": {
            "anyOf": [
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Only with include=[\"products\"].",
            "title": "Products"
          },
          "skipped_reason": {
            "anyOf": [
              {
                "enum": [
                  "human_handoff_active",
                  "auto_response_off"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Skipped Reason"
          },
          "status": {
            "enum": [
              "queued",
              "in_progress",
              "completed",
              "failed"
            ],
            "title": "Status",
            "type": "string"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "required": [
          "id",
          "status",
          "agent_id",
          "conversation_id",
          "mode",
          "created_at",
          "handoff",
          "usage"
        ],
        "title": "ResponseObject",
        "type": "object"
      },
      "SecretRotated": {
        "additionalProperties": true,
        "properties": {
          "id": {
            "title": "Id",
            "type": "string"
          },
          "previous_secret_valid_until": {
            "title": "Previous Secret Valid Until",
            "type": "string"
          },
          "secret": {
            "description": "whsec_... Shown only in this response.",
            "title": "Secret",
            "type": "string"
          }
        },
        "required": [
          "id",
          "secret",
          "previous_secret_valid_until"
        ],
        "title": "SecretRotated",
        "type": "object"
      },
      "StaffMessageEvent": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "channel": {
            "title": "Channel",
            "type": "string"
          },
          "content": {
            "title": "Content",
            "type": "string"
          },
          "conversation_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Conversation Id"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created At"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "object": {
            "const": "message",
            "default": "message",
            "title": "Object",
            "type": "string"
          },
          "role": {
            "const": "staff",
            "default": "staff",
            "title": "Role",
            "type": "string"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "agent_id",
          "session_id",
          "channel",
          "content"
        ],
        "title": "StaffMessageEvent",
        "type": "object"
      },
      "SystemInstruction": {
        "additionalProperties": true,
        "properties": {
          "enabled": {
            "title": "Enabled",
            "type": "boolean"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "summary": {
            "title": "Summary",
            "type": "string"
          },
          "title": {
            "title": "Title",
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "summary",
          "enabled"
        ],
        "title": "SystemInstruction",
        "type": "object"
      },
      "TestEvent": {
        "additionalProperties": true,
        "properties": {
          "message": {
            "title": "Message",
            "type": "string"
          },
          "object": {
            "const": "test",
            "default": "test",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "message"
        ],
        "title": "TestEvent",
        "type": "object"
      },
      "TestEventQueued": {
        "additionalProperties": true,
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Id"
          },
          "object": {
            "const": "event",
            "default": "event",
            "title": "Object",
            "type": "string"
          },
          "queued": {
            "title": "Queued",
            "type": "boolean"
          },
          "type": {
            "const": "webhook.test",
            "default": "webhook.test",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "id",
          "queued"
        ],
        "title": "TestEventQueued",
        "type": "object"
      },
      "UploadCreate": {
        "additionalProperties": false,
        "properties": {
          "filename": {
            "description": "pdf, docx, doc, rtf, txt, csv or md",
            "maxLength": 180,
            "minLength": 1,
            "title": "Filename",
            "type": "string"
          },
          "knowledge_id": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Set to replace this uploaded document.",
            "title": "Knowledge Id"
          },
          "size_bytes": {
            "maximum": 10485760.0,
            "minimum": 1.0,
            "title": "Size Bytes",
            "type": "integer"
          }
        },
        "required": [
          "filename",
          "size_bytes"
        ],
        "title": "UploadCreate",
        "type": "object"
      },
      "UploadTicket": {
        "additionalProperties": true,
        "properties": {
          "expires_at": {
            "title": "Expires At",
            "type": "string"
          },
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Send these headers with the upload.",
            "title": "Headers",
            "type": "object"
          },
          "max_bytes": {
            "title": "Max Bytes",
            "type": "integer"
          },
          "method": {
            "const": "PUT",
            "default": "PUT",
            "title": "Method",
            "type": "string"
          },
          "next_step": {
            "title": "Next Step",
            "type": "string"
          },
          "replayed": {
            "default": false,
            "title": "Replayed",
            "type": "boolean"
          },
          "upload_id": {
            "title": "Upload Id",
            "type": "string"
          },
          "upload_url": {
            "title": "Upload Url",
            "type": "string"
          }
        },
        "required": [
          "upload_id",
          "upload_url",
          "headers",
          "max_bytes",
          "expires_at",
          "next_step"
        ],
        "title": "UploadTicket",
        "type": "object"
      },
      "Usage": {
        "properties": {
          "credits": {
            "default": 0,
            "description": "AI credits booked for this answer.",
            "title": "Credits",
            "type": "integer"
          }
        },
        "title": "Usage",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      },
      "WebhookEndpoint": {
        "additionalProperties": true,
        "properties": {
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created At"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Description"
          },
          "disabled_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "manual, failing or integration_revoked.",
            "title": "Disabled Reason"
          },
          "events": {
            "items": {
              "type": "string"
            },
            "title": "Events",
            "type": "array"
          },
          "failing_since": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Failing Since"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "integration_id": {
            "title": "Integration Id",
            "type": "string"
          },
          "object": {
            "const": "webhook_endpoint",
            "default": "webhook_endpoint",
            "title": "Object",
            "type": "string"
          },
          "secret_last4": {
            "title": "Secret Last4",
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "disabled"
            ],
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Updated At"
          },
          "url": {
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "id",
          "integration_id",
          "url",
          "events",
          "status",
          "secret_last4"
        ],
        "title": "WebhookEndpoint",
        "type": "object"
      },
      "WebhookEndpointDeleted": {
        "additionalProperties": true,
        "properties": {
          "deleted": {
            "title": "Deleted",
            "type": "boolean"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "object": {
            "const": "webhook_endpoint",
            "default": "webhook_endpoint",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "id",
          "deleted"
        ],
        "title": "WebhookEndpointDeleted",
        "type": "object"
      },
      "WebhookEndpointList": {
        "additionalProperties": true,
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/WebhookEndpoint"
            },
            "title": "Data",
            "type": "array"
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "required": [
          "data",
          "next_cursor"
        ],
        "title": "WebhookEndpointList",
        "type": "object"
      },
      "WidgetPatchBody": {
        "additionalProperties": true,
        "properties": {
          "expected_version": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Expected Version"
          }
        },
        "title": "WidgetPatchBody",
        "type": "object"
      },
      "WidgetSettings": {
        "additionalProperties": true,
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "data": {
            "additionalProperties": true,
            "description": "The widget fields (welcome_message, theme_color, header_text, ...).",
            "title": "Data",
            "type": "object"
          },
          "resource_id": {
            "title": "Resource Id",
            "type": "string"
          },
          "version": {
            "title": "Version",
            "type": "integer"
          }
        },
        "required": [
          "agent_id",
          "resource_id",
          "version",
          "data"
        ],
        "title": "WidgetSettings",
        "type": "object"
      },
      "WidgetUpdated": {
        "additionalProperties": true,
        "properties": {
          "replayed": {
            "title": "Replayed",
            "type": "boolean"
          },
          "resource": {
            "$ref": "#/components/schemas/WidgetSettings"
          }
        },
        "required": [
          "resource",
          "replayed"
        ],
        "title": "WidgetUpdated",
        "type": "object"
      }
    },
    "securitySchemes": {
      "ServiceKey": {
        "description": "Service key of an integration: ub_live_...",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Build Ultimo agents into your own product: send messages and get answers as JSON, as a stream or\nasync, keep conversations under your own ids, read the history, mirror your knowledge, read leads and insights,\nand receive webhooks.\n\nAuthentication: `Authorization: Bearer ub_live_...` (a service key of an integration, created in the portal under\nAPI & Integrations). Keys are for server-to-server use only.\n\nErrors always have the form `{\"error\": {\"type\", \"code\", \"message\", \"request_id\", \"doc_url\"}}`. Every response\ncarries `X-Request-Id`. Version 1 only adds fields; ignore fields you do not know.\n",
    "title": "Ultimo API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/agents": {
      "get": {
        "description": "The agents this integration may use. Requires `agents:read`.",
        "operationId": "list_agents_agents_get",
        "parameters": [
          {
            "description": "Page size, 1-100.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "description": "Page size, 1-100.",
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "description": "next_cursor of the previous page.",
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 200,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "next_cursor of the previous page.",
              "title": "After"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "api_access": true,
                      "created_at": "2026-11-01T09:00:00Z",
                      "id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                      "name": "Sonnenhang Winery",
                      "object": "agent",
                      "status": "completed",
                      "website_url": "https://example.com"
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/AgentList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "List agents",
        "tags": [
          "Agents"
        ],
        "x-required-scope": "agents:read",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}": {
      "get": {
        "description": "Requires `agents:read`.",
        "operationId": "get_agent_agents__agent_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "api_access": true,
                  "created_at": "2026-11-01T09:00:00Z",
                  "id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "name": "Sonnenhang Winery",
                  "object": "agent",
                  "status": "completed",
                  "website_url": "https://example.com"
                },
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Get an agent",
        "tags": [
          "Agents"
        ],
        "x-required-scope": "agents:read",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/behaviors": {
      "get": {
        "description": "The owner's behavior rules and the platform's system instructions, as the AI Studio shows them.\nRequires `agents:behaviors:read`.",
        "operationId": "get_behaviors_agents__agent_id__behaviors_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "allowance": {
                    "can_add": true,
                    "current_count": 1,
                    "limit": 30
                  },
                  "behaviors": [
                    {
                      "enabled": true,
                      "id": "b1",
                      "text": "Address customers formally.",
                      "title": "Formal address"
                    }
                  ],
                  "definition_version": 3,
                  "system_instructions": [
                    {
                      "enabled": true,
                      "id": "stay_on_topic",
                      "summary": "Helps only with the business's topics and politely steers back.",
                      "title": "Stay on topic"
                    }
                  ]
                },
                "schema": {
                  "$ref": "#/components/schemas/Behaviors"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Read the behavior rules",
        "tags": [
          "Agents"
        ],
        "x-required-scope": "agents:behaviors:read",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/business-context": {
      "get": {
        "description": "Requires `agents:context:read`.",
        "operationId": "get_business_context_agents__agent_id__business_context_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "business_context": "Sonnenhang Winery sells wines from the Palatinate. Farm shop open Mon-Fri 9-18, Sat 9-14.",
                  "version": 5
                },
                "schema": {
                  "$ref": "#/components/schemas/BusinessContext"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Read the Business Context",
        "tags": [
          "Agents"
        ],
        "x-required-scope": "agents:context:read",
        "x-requires-write-integration": false
      },
      "put": {
        "description": "Requires `agents:context:write`.",
        "operationId": "put_business_context_agents__agent_id__business_context_put",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "description": "Same key + same body = the stored result (no second change).",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Same key + same body = the stored result (no second change).",
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "business_context": "Sonnenhang Winery sells wines from the Palatinate. Farm shop open Mon-Sat 9-18.",
                "expected_version": 5
              },
              "schema": {
                "$ref": "#/components/schemas/BusinessContextPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "context": {
                    "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                    "business_context": "Sonnenhang Winery sells wines from the Palatinate. Farm shop open Mon-Fri 9-18, Sat 9-14.",
                    "version": 6
                  },
                  "replayed": false
                },
                "schema": {
                  "$ref": "#/components/schemas/BusinessContextUpdated"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Replace the Business Context",
        "tags": [
          "Agents"
        ],
        "x-required-scope": "agents:context:write",
        "x-requires-write-integration": true
      }
    },
    "/agents/{agent_id}/conversations": {
      "get": {
        "description": "Every channel (website, WhatsApp, API, ...), newest activity per session. Requires `conversations:read_all`.",
        "operationId": "agent_conversations_agents__agent_id__conversations_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 20,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "start_date",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Start Date"
            }
          },
          {
            "in": "query",
            "name": "end_date",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "End Date"
            }
          },
          {
            "in": "query",
            "name": "channel",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 64,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Channel"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "api_conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                      "first_activity": "2026-11-10T16:30:45.081227",
                      "last_activity": "2026-11-10T16:30:48.673890",
                      "message_count": 6,
                      "object": "agent_conversation",
                      "reference": "conv_2346",
                      "visitor_messages": 3
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/AgentConversationList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "All conversations of an agent",
        "tags": [
          "Conversations"
        ],
        "x-required-scope": "conversations:read_all",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/conversations/{reference}/messages": {
      "get": {
        "description": "`reference` from the list above. Requires `conversations:read_all`.",
        "operationId": "agent_conversation_messages_agents__agent_id__conversations__reference__messages_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "reference",
            "required": true,
            "schema": {
              "title": "Reference",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 20,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "content": "When is the farm shop open on Saturday?",
                      "content_truncated": false,
                      "id": 2346,
                      "platform": "api",
                      "timestamp": "2026-11-10T16:30:45.081227",
                      "type": "user_input"
                    },
                    {
                      "content": "Hello Anna, the farm shop is open on Saturdays from 9 to 14.",
                      "content_truncated": false,
                      "id": 2347,
                      "platform": "api",
                      "timestamp": "2026-11-10T16:30:46.637930",
                      "type": "assistant"
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/AgentConversationMessageList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "History of any conversation",
        "tags": [
          "Conversations"
        ],
        "x-required-scope": "conversations:read_all",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/credits": {
      "get": {
        "description": "Balance, plan allowance and price per answer. Requires `credits:read`.",
        "operationId": "credits_agents__agent_id__credits_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "answer_level": "standard",
                  "answer_price": 1,
                  "available": 9100,
                  "balance": 9100,
                  "extra_remaining": 0,
                  "extra_total": 0,
                  "mode": "on",
                  "object": "credits",
                  "period_end": "2026-12-01T00:00:00",
                  "period_start": "2026-11-01T00:00:00",
                  "plan_allowance": 10000,
                  "plan_name": "Ultimo",
                  "plan_remaining": 9100,
                  "unit": "credits"
                },
                "schema": {
                  "$ref": "#/components/schemas/Credits"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "AI credits and usage",
        "tags": [
          "Insights"
        ],
        "x-required-scope": "credits:read",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/embed": {
      "get": {
        "description": "The website code and chat link, as in the portal under Deploy. Requires `widget:read`.",
        "operationId": "get_embed_agents__agent_id__embed_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "chat_url": "https://chat.ultimo-bots.com/c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "iframe_html": "<iframe src=\"https://chat.ultimo-bots.com/c3e02486-f107-40c4-ac4d-e6155111bc8e\" style=\"width:400px;height:600px;border:0\"></iframe>",
                  "website_html": "<div id=\"chat-widget-container\" data-user-id=\"c3e02486-f107-40c4-ac4d-e6155111bc8e\"></div>\n<script src=\"...\"></script>"
                },
                "schema": {
                  "$ref": "#/components/schemas/Embed"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Embed code",
        "tags": [
          "Widget"
        ],
        "x-required-scope": "widget:read",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/exports": {
      "post": {
        "description": "A CSV page (`csv`, `row_count`, `next_cursor`); call again with `after` for the next page.\nRequires `exports:read`.",
        "operationId": "export_agents__agent_id__exports_post",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "end_date": "2026-11-10",
                "kind": "leads",
                "limit": 100,
                "start_date": "2026-11-01"
              },
              "schema": {
                "$ref": "#/components/schemas/ExportBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "csv": "id,date,session_id,params,read,type\r\n46,2026-11-10 17:00:37.539882,api-conv_8TFivGiB5wHJqdt7FfRZkFYH,\"{\"\"name\"\": \"\"Anna Example\"\", \"\"email\"\": \"\"anna@example.com\"\"}\",False,contact\r\n",
                  "filename": "leads.csv",
                  "formula_safe": true,
                  "header_included": true,
                  "mime_type": "text/csv; charset=utf-8",
                  "next_cursor": null,
                  "row_count": 1
                },
                "schema": {
                  "$ref": "#/components/schemas/Export"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Export conversations or leads as CSV",
        "tags": [
          "Leads"
        ],
        "x-required-scope": "exports:read",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/insights": {
      "get": {
        "description": "Conversations, messages, leads, topics and countries per day, at most 366 days. Requires `reports:read`.",
        "operationId": "insights_agents__agent_id__insights_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "start_date",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Start Date"
            }
          },
          {
            "in": "query",
            "name": "end_date",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "End Date"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "daily": [
                    {
                      "conversations": 16,
                      "date": "2026-11-10",
                      "replies": 20,
                      "visitor_messages": 18
                    }
                  ],
                  "end_date": "2026-11-10",
                  "platforms": [
                    {
                      "conversations": 13,
                      "platform": "api",
                      "replies": 17,
                      "visitor_messages": 17
                    }
                  ],
                  "start_date": "2026-10-12",
                  "timezone": "UTC",
                  "totals": {
                    "conversations": 16,
                    "leads": 3,
                    "replies": 20,
                    "visitor_messages": 18
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/Insights"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Key figures",
        "tags": [
          "Insights"
        ],
        "x-required-scope": "reports:read",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/knowledge": {
      "get": {
        "description": "URLs, files, FAQs and cloud sources with status and revision. Requires `knowledge:read`.",
        "operationId": "list_knowledge_agents__agent_id__knowledge_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 20,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "source_type",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 40,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Source Type"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "default": "",
              "maxLength": 200,
              "title": "Q",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "enum": [
                    "completed",
                    "failed",
                    "scraping",
                    "deleting"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Status"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "can_refresh": false,
                      "content_length": 21,
                      "created_at": "2026-11-10T17:00:49.169767",
                      "description": "Is parking free?",
                      "document_name": null,
                      "download_url": null,
                      "downloadable": false,
                      "failure_code": null,
                      "failure_reason": null,
                      "id": 226064,
                      "revision": "2",
                      "source_type": "faq",
                      "status": "completed",
                      "title": "Is parking free?",
                      "type": "faq",
                      "url": null
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeSourceList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "List knowledge sources",
        "tags": [
          "Knowledge"
        ],
        "x-required-scope": "knowledge:read",
        "x-requires-write-integration": false
      },
      "post": {
        "description": "Adds a website (crawled), an FAQ or an uploaded document. Returns an operation: poll\n`GET /v1/operations/{id}` or receive `knowledge.operation.completed`. Requires `knowledge:write`.",
        "operationId": "add_knowledge_agents__agent_id__knowledge_post",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "description": "Same key + same body = the stored result (no second change).",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Same key + same body = the stored result (no second change).",
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "text": "Yes, parking in the yard is free.",
                "title": "Is parking free?",
                "type": "faq"
              },
              "schema": {
                "$ref": "#/components/schemas/KnowledgeCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "knowledge_ids": [
                    226069
                  ],
                  "operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
                  "replayed": false,
                  "status": "queued"
                },
                "schema": {
                  "$ref": "#/components/schemas/OperationAccepted"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Add a source",
        "tags": [
          "Knowledge"
        ],
        "x-required-scope": "knowledge:write",
        "x-requires-write-integration": true
      }
    },
    "/agents/{agent_id}/knowledge/refresh": {
      "post": {
        "description": "Re-imports websites and cloud files now. Requires `knowledge:write`.",
        "operationId": "refresh_knowledge_agents__agent_id__knowledge_refresh_post",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "description": "Same key + same body = the stored result (no second change).",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Same key + same body = the stored result (no second change).",
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "sources": [
                  {
                    "expected_revision": "2",
                    "knowledge_id": 226065
                  }
                ]
              },
              "schema": {
                "$ref": "#/components/schemas/RefreshBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "knowledge_ids": [
                    226065
                  ],
                  "operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
                  "replayed": false,
                  "status": "queued"
                },
                "schema": {
                  "$ref": "#/components/schemas/OperationAccepted"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Read sources again",
        "tags": [
          "Knowledge"
        ],
        "x-required-scope": "knowledge:write",
        "x-requires-write-integration": true
      }
    },
    "/agents/{agent_id}/knowledge/uploads": {
      "post": {
        "description": "Returns a one-time upload address. Send the bytes there with HTTP PUT, then add the document with\n`POST .../knowledge` (`type: document`, `upload_id`) or replace one with `PUT .../knowledge/{id}`.\nRequires `knowledge:write`.",
        "operationId": "prepare_upload_agents__agent_id__knowledge_uploads_post",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "description": "Same key + same body = the stored result (no second change).",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Same key + same body = the stored result (no second change).",
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "filename": "price-list.pdf",
                "size_bytes": 48211
              },
              "schema": {
                "$ref": "#/components/schemas/UploadCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "expires_at": "2026-11-10T18:12:04.045492+00:00",
                  "headers": {
                    "Authorization": "Bearer <one-time upload token>",
                    "Content-Type": "application/octet-stream"
                  },
                  "max_bytes": 48211,
                  "method": "PUT",
                  "next_step": "PUT the exact file bytes to upload_url with these headers, then call POST /v1/agents/{id}/knowledge with type=document and upload_id (or PUT /v1/agents/{id}/knowledge/{knowledge_id} to replace).",
                  "replayed": false,
                  "upload_id": "38dfa648-592f-489a-9a43-6dd25ccdea45",
                  "upload_url": "https://portal.ultimo-bots.com/api/mcp-platform/uploads/38dfa648-592f-489a-9a43-6dd25ccdea45"
                },
                "schema": {
                  "$ref": "#/components/schemas/UploadTicket"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Prepare a file upload",
        "tags": [
          "Knowledge"
        ],
        "x-required-scope": "knowledge:write",
        "x-requires-write-integration": true
      }
    },
    "/agents/{agent_id}/knowledge/{knowledge_id}": {
      "delete": {
        "description": "Removes the source from the agent's knowledge (an operation). Requires `knowledge:write`.",
        "operationId": "delete_knowledge_agents__agent_id__knowledge__knowledge_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "knowledge_id",
            "required": true,
            "schema": {
              "title": "Knowledge Id",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "expected_revision",
            "required": true,
            "schema": {
              "maxLength": 64,
              "minLength": 1,
              "title": "Expected Revision",
              "type": "string"
            }
          },
          {
            "description": "Same key + same body = the stored result (no second change).",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Same key + same body = the stored result (no second change).",
              "title": "Idempotency-Key"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "knowledge_ids": [
                    226064
                  ],
                  "operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
                  "replayed": false,
                  "status": "queued"
                },
                "schema": {
                  "$ref": "#/components/schemas/OperationAccepted"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Delete a source",
        "tags": [
          "Knowledge"
        ],
        "x-required-scope": "knowledge:write",
        "x-requires-write-integration": true
      },
      "get": {
        "description": "The content in pages of up to 16000 characters (`next_offset`). Requires `knowledge:read`.",
        "operationId": "get_knowledge_agents__agent_id__knowledge__knowledge_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "knowledge_id",
            "required": true,
            "schema": {
              "title": "Knowledge Id",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "minimum": 0,
              "title": "Offset",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "max_chars",
            "required": false,
            "schema": {
              "default": 8000,
              "maximum": 16000,
              "minimum": 1,
              "title": "Max Chars",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "can_refresh": false,
                  "content": "Yes, parking is free.",
                  "content_length": 21,
                  "content_offset": 0,
                  "created_at": "2026-11-10T17:00:49.169767",
                  "description": "Is parking free?",
                  "document_name": null,
                  "download_url": null,
                  "downloadable": false,
                  "failure_code": null,
                  "failure_reason": null,
                  "id": 226064,
                  "next_offset": null,
                  "revision": "2",
                  "source_type": "faq",
                  "status": "completed",
                  "title": "Is parking free?",
                  "type": "faq",
                  "url": null
                },
                "schema": {
                  "$ref": "#/components/schemas/KnowledgeSourceContent"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "A knowledge source with content",
        "tags": [
          "Knowledge"
        ],
        "x-required-scope": "knowledge:read",
        "x-requires-write-integration": false
      },
      "put": {
        "description": "FAQ: send `title` and `text`. Document: send `upload_id`. Requires `knowledge:write`.",
        "operationId": "put_knowledge_agents__agent_id__knowledge__knowledge_id__put",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "knowledge_id",
            "required": true,
            "schema": {
              "title": "Knowledge Id",
              "type": "integer"
            }
          },
          {
            "description": "Same key + same body = the stored result (no second change).",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Same key + same body = the stored result (no second change).",
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "expected_revision": "2",
                "text": "Yes, parking in the yard and on the street is free.",
                "title": "Is parking free?"
              },
              "schema": {
                "$ref": "#/components/schemas/KnowledgePut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "knowledge_ids": [
                    226064
                  ],
                  "operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
                  "replayed": false,
                  "status": "queued"
                },
                "schema": {
                  "$ref": "#/components/schemas/OperationAccepted"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Change an FAQ or replace a document",
        "tags": [
          "Knowledge"
        ],
        "x-required-scope": "knowledge:write",
        "x-requires-write-integration": true
      }
    },
    "/agents/{agent_id}/leads": {
      "get": {
        "description": "Requires `leads:read`.",
        "operationId": "list_leads_agents__agent_id__leads_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 20,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "start_date",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Start Date"
            }
          },
          {
            "in": "query",
            "name": "end_date",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "End Date"
            }
          },
          {
            "in": "query",
            "name": "read",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Read"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "date": "2026-11-10T17:00:37.539882",
                      "id": 46,
                      "read": false,
                      "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
                      "type": "contact",
                      "version": 2
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/LeadList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "List leads",
        "tags": [
          "Leads"
        ],
        "x-required-scope": "leads:read",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/leads/{lead_id}": {
      "delete": {
        "description": "Deletes the lead and its `lead.created` webhook event. Requires `leads:write`. Without\n`expected_version` the current version is used.",
        "operationId": "delete_lead_agents__agent_id__leads__lead_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "lead_id",
            "required": true,
            "schema": {
              "title": "Lead Id",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "expected_version",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "minimum": 1,
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Expected Version"
            }
          },
          {
            "description": "Same key + same body = the stored result (no second change).",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Same key + same body = the stored result (no second change).",
              "title": "Idempotency-Key"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "deleted": true,
                  "id": 46
                },
                "schema": {
                  "$ref": "#/components/schemas/LeadDeleted"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Delete a lead",
        "tags": [
          "Leads"
        ],
        "x-required-scope": "leads:write",
        "x-requires-write-integration": true
      },
      "get": {
        "description": "The lead with all its fields and version. Requires `leads:read`.",
        "operationId": "get_lead_agents__agent_id__leads__lead_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "lead_id",
            "required": true,
            "schema": {
              "title": "Lead Id",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "data": {
                    "date": "2026-11-10T17:00:37.539882",
                    "id": 46,
                    "params": {
                      "email": "anna@example.com",
                      "name": "Anna Example"
                    },
                    "read": false,
                    "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
                    "type": "contact"
                  },
                  "resource_id": "46",
                  "version": 2
                },
                "schema": {
                  "$ref": "#/components/schemas/Lead"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Get a lead",
        "tags": [
          "Leads"
        ],
        "x-required-scope": "leads:read",
        "x-requires-write-integration": false
      },
      "patch": {
        "description": "Requires `leads:write`.",
        "operationId": "patch_lead_agents__agent_id__leads__lead_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "lead_id",
            "required": true,
            "schema": {
              "title": "Lead Id",
              "type": "integer"
            }
          },
          {
            "description": "Same key + same body = the stored result (no second change).",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Same key + same body = the stored result (no second change).",
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "expected_version": 2,
                "read": true
              },
              "schema": {
                "$ref": "#/components/schemas/LeadPatchBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "replayed": false,
                  "resource": {
                    "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                    "data": {
                      "date": "2026-11-10T17:00:37.539882",
                      "id": 46,
                      "params": {
                        "email": "anna@example.com",
                        "name": "Anna Example"
                      },
                      "read": true,
                      "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
                      "type": "contact"
                    },
                    "resource_id": "46",
                    "version": 3
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/LeadUpdated"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Mark a lead as read or unread",
        "tags": [
          "Leads"
        ],
        "x-required-scope": "leads:write",
        "x-requires-write-integration": true
      }
    },
    "/agents/{agent_id}/live-sessions": {
      "get": {
        "description": "Conversations waiting for or handled by a person of the business. Answering from your own tool comes in\nv1.1; staff replies arrive as `handoff.message` webhooks. Requires `livechat:read`.",
        "operationId": "live_sessions_agents__agent_id__live_sessions_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 200,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "agent_display_name": null,
                      "agent_requested_at": "2026-11-10T16:31:02.114",
                      "bot_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                      "created_at": "2026-11-10T16:30:45.081",
                      "last_activity": "2026-11-10T16:31:02.114",
                      "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
                      "status": "agent_requested",
                      "visitor_name": "Anna"
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/LiveSessionList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Open handoffs",
        "tags": [
          "Conversations"
        ],
        "x-required-scope": "livechat:read",
        "x-requires-write-integration": false
      }
    },
    "/agents/{agent_id}/widget": {
      "get": {
        "description": "Colours, greeting, position, question chips and the other widget fields, with their version.\nRequires `widget:read`.",
        "operationId": "get_widget_agents__agent_id__widget_get",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "data": {
                    "header_text": "Chat with us",
                    "input_placeholder": "Type your message...",
                    "pop_up_messages": true,
                    "theme_color": "#5616eaff",
                    "welcome_message": [
                      "Hello! How can I help you?"
                    ],
                    "widget_horizontal_alignment": "right"
                  },
                  "resource_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "version": 4
                },
                "schema": {
                  "$ref": "#/components/schemas/WidgetSettings"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Widget settings",
        "tags": [
          "Widget"
        ],
        "x-required-scope": "widget:read",
        "x-requires-write-integration": false
      },
      "patch": {
        "description": "Send only the fields to change (same names as GET returns in `data`). Requires `widget:write`.",
        "operationId": "patch_widget_agents__agent_id__widget_patch",
        "parameters": [
          {
            "in": "path",
            "name": "agent_id",
            "required": true,
            "schema": {
              "title": "Agent Id",
              "type": "string"
            }
          },
          {
            "description": "Same key + same body = the stored result (no second change).",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Same key + same body = the stored result (no second change).",
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "expected_version": 4,
                "header_text": "Ask our team"
              },
              "schema": {
                "$ref": "#/components/schemas/WidgetPatchBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "replayed": false,
                  "resource": {
                    "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                    "data": {
                      "header_text": "Chat with us",
                      "input_placeholder": "Type your message...",
                      "pop_up_messages": true,
                      "theme_color": "#5616eaff",
                      "welcome_message": [
                        "Hello! How can I help you?"
                      ],
                      "widget_horizontal_alignment": "right"
                    },
                    "resource_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                    "version": 5
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/WidgetUpdated"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Change the widget",
        "tags": [
          "Widget"
        ],
        "x-required-scope": "widget:write",
        "x-requires-write-integration": true
      }
    },
    "/conversations": {
      "get": {
        "description": "Conversations of this integration, newest first. Requires `chat:write`.",
        "operationId": "list_conversations_conversations_get",
        "parameters": [
          {
            "in": "query",
            "name": "agent_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 200,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Agent Id"
            }
          },
          {
            "in": "query",
            "name": "external_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 200,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "External Id"
            }
          },
          {
            "description": "Page size, 1-100.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "description": "Page size, 1-100.",
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "description": "next_cursor of the previous page.",
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 200,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "next_cursor of the previous page.",
              "title": "After"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                      "auto_response": true,
                      "created_at": "2026-11-10T16:30:45Z",
                      "external_id": "ticket-4711",
                      "id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                      "last_activity_at": "2026-11-10T16:30:47Z",
                      "metadata": {
                        "team": "support"
                      },
                      "object": "conversation",
                      "type": "direct"
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/ConversationList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "List conversations",
        "tags": [
          "Conversations"
        ],
        "x-required-scope": "chat:write",
        "x-requires-write-integration": false
      }
    },
    "/conversations/{conversation_id}": {
      "delete": {
        "description": "Deletes the conversation and everything stored for it: the history with its authors, the stored requests\nand answers of `POST /v1/responses`, and the webhook events that carry its content. A request that is still\nwaiting or running for it ends `failed` with code `conversation_deleted`. Leads are their own records: delete\nthem with `DELETE /v1/agents/{agent_id}/leads/{lead_id}`. Use it for a new topic or a deletion request.\nRequires `chat:write`.",
        "operationId": "delete_conversation_conversations__conversation_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "title": "Conversation Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "deleted": true,
                  "id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "object": "conversation"
                },
                "schema": {
                  "$ref": "#/components/schemas/Deleted"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Delete a conversation",
        "tags": [
          "Conversations"
        ],
        "x-required-scope": "chat:write",
        "x-requires-write-integration": true
      },
      "get": {
        "description": "Requires `chat:write`.",
        "operationId": "get_conversation_conversations__conversation_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "title": "Conversation Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "auto_response": true,
                  "created_at": "2026-11-10T16:30:45Z",
                  "external_id": "ticket-4711",
                  "id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "last_activity_at": "2026-11-10T16:30:47Z",
                  "metadata": {
                    "team": "support"
                  },
                  "object": "conversation",
                  "type": "direct"
                },
                "schema": {
                  "$ref": "#/components/schemas/Conversation"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Get a conversation",
        "tags": [
          "Conversations"
        ],
        "x-required-scope": "chat:write",
        "x-requires-write-integration": false
      }
    },
    "/conversations/{conversation_id}/auto-response": {
      "put": {
        "description": "Mute the agent in one conversation (or switch it back on). Requires `chat:write`.",
        "operationId": "set_auto_response_conversations__conversation_id__auto_response_put",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "title": "Conversation Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "enabled": false
              },
              "schema": {
                "$ref": "#/components/schemas/AutoResponse"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "auto_response": false,
                  "created_at": "2026-11-10T16:30:45Z",
                  "external_id": "ticket-4711",
                  "id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "last_activity_at": "2026-11-10T16:30:47Z",
                  "metadata": {
                    "team": "support"
                  },
                  "object": "conversation",
                  "type": "direct"
                },
                "schema": {
                  "$ref": "#/components/schemas/Conversation"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Switch answers on or off",
        "tags": [
          "Conversations"
        ],
        "x-required-scope": "chat:write",
        "x-requires-write-integration": true
      }
    },
    "/conversations/{conversation_id}/messages": {
      "get": {
        "description": "The stored messages, oldest first: the end users' messages, the agent's answers and replies of the\nbusiness's team (role `staff`). Requires `chat:write`.",
        "operationId": "conversation_messages_conversations__conversation_id__messages_get",
        "parameters": [
          {
            "in": "path",
            "name": "conversation_id",
            "required": true,
            "schema": {
              "title": "Conversation Id",
              "type": "string"
            }
          },
          {
            "description": "Page size, 1-100.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "description": "Page size, 1-100.",
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "description": "next_cursor of the previous page.",
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 200,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "next_cursor of the previous page.",
              "title": "After"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "content": "When is the farm shop open on Saturday?",
                      "created_at": "2026-11-10T16:30:45Z",
                      "end_user": {
                        "id": "u-17",
                        "name": "Anna"
                      },
                      "id": "msg_0000000000002346",
                      "metadata": {
                        "ticket": "4711"
                      },
                      "object": "message",
                      "role": "user"
                    },
                    {
                      "content": "Hello Anna, the farm shop is open on Saturdays from 9 to 14.",
                      "created_at": "2026-11-10T16:30:47Z",
                      "end_user": null,
                      "id": "msg_0000000000002347",
                      "metadata": {},
                      "object": "message",
                      "role": "assistant"
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/MessageList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Conversation history",
        "tags": [
          "Conversations"
        ],
        "x-required-scope": "chat:write",
        "x-requires-write-integration": false
      }
    },
    "/events": {
      "get": {
        "description": "The last 30 days of events sent to this integration's endpoints, newest first, each with its deliveries\n(status, attempts, last HTTP status, duration). Requires `webhooks:write`.",
        "operationId": "list_events_events_get",
        "parameters": [
          {
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 64,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Type"
            }
          },
          {
            "in": "query",
            "name": "delivery_status",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "enum": [
                    "pending",
                    "delivering",
                    "succeeded",
                    "failed"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Delivery Status"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 25,
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 64,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                      "api_version": "v1",
                      "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                      "created_at": "2026-11-10T16:30:45Z",
                      "data": {
                        "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                        "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                        "created_at": "2026-11-10T17:00:37.539882Z",
                        "fields": {
                          "email": "anna@example.com",
                          "name": "Anna Example"
                        },
                        "id": 46,
                        "object": "lead",
                        "read": false,
                        "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
                        "type": "contact"
                      },
                      "deliveries": [
                        {
                          "attempts": 1,
                          "created_at": "2026-11-10T16:30:45Z",
                          "delivered_at": "2026-11-10T16:30:45Z",
                          "endpoint_id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
                          "event_id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                          "event_type": "lead.created",
                          "id": "wd_2Yc5RkP8mT1xZ7bN4cL0pQdH",
                          "last_duration_ms": 142,
                          "last_error": null,
                          "last_status_code": 200,
                          "next_attempt_at": null,
                          "object": "webhook_delivery",
                          "status": "succeeded"
                        }
                      ],
                      "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                      "object": "event",
                      "type": "lead.created"
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/EventList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Events and their deliveries",
        "tags": [
          "Webhooks"
        ],
        "x-required-scope": "webhooks:write",
        "x-requires-write-integration": false
      }
    },
    "/events/{event_id}/resend": {
      "post": {
        "description": "Queues every delivery of this event to this integration's endpoints again. Requires `webhooks:write`.",
        "operationId": "resend_event_events__event_id__resend_post",
        "parameters": [
          {
            "in": "path",
            "name": "event_id",
            "required": true,
            "schema": {
              "title": "Event Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                  "object": "event",
                  "requeued_deliveries": 1
                },
                "schema": {
                  "$ref": "#/components/schemas/EventResent"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Send an event again",
        "tags": [
          "Webhooks"
        ],
        "x-required-scope": "webhooks:write",
        "x-requires-write-integration": true
      }
    },
    "/operations/{operation_id}": {
      "get": {
        "description": "queued, running, succeeded or failed, with per-item results. Requires `knowledge:read`.",
        "operationId": "get_operation_operations__operation_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "operation_id",
            "required": true,
            "schema": {
              "title": "Operation Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "action": "ingest",
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "attempts": 1,
                  "created_at": "2026-11-10T17:57:04.057886+00:00",
                  "error_code": null,
                  "finished_at": "2026-11-10T17:57:06.005898+00:00",
                  "knowledge_ids": [
                    226069
                  ],
                  "operation_id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
                  "result": {
                    "indexed_knowledge_ids": [
                      226069
                    ]
                  },
                  "status": "succeeded"
                },
                "schema": {
                  "$ref": "#/components/schemas/Operation"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "State of a long operation",
        "tags": [
          "Knowledge"
        ],
        "x-required-scope": "knowledge:read",
        "x-requires-write-integration": false
      }
    },
    "/responses": {
      "post": {
        "description": "Send one message to an agent and get its answer.\n\n- JSON (default): waits for the answer (up to 120 s).\n- `\"stream\": true`: server-sent events `response.created`, `status`, `delta`, `products`, `choices`,\n  `response.completed`, `error`; JSON in every event; a heartbeat comment every 15 s.\n- `\"async\": true`: 202 at once; poll `GET /v1/responses/{id}` or receive the `response.completed` webhook.\n\nConversations: pass your `external_id` (created on first use), a `conversation_id`, or neither (a new\nconversation). With the same `Idempotency-Key` and body a retry returns the stored result for 24 hours\nwithout a second answer or charge. Requires `chat:write`.",
        "operationId": "create_response_responses_post",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Idempotency-Key"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "context": {
                  "customer_tier": "gold",
                  "last_order": "2026-10-28"
                },
                "end_user": {
                  "id": "u-17",
                  "name": "Anna"
                },
                "external_id": "ticket-4711",
                "input": "When is the farm shop open on Saturday?",
                "metadata": {
                  "ticket": "4711"
                }
              },
              "schema": {
                "$ref": "#/components/schemas/ResponseCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "completed_at": "2026-11-10T16:30:47Z",
                  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "created_at": "2026-11-10T16:30:45Z",
                  "end_user": {
                    "id": "u-17",
                    "name": "Anna"
                  },
                  "error": null,
                  "external_id": "ticket-4711",
                  "handoff": {
                    "requested": false,
                    "status": null
                  },
                  "id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
                  "input_message_id": "msg_0000000000002346",
                  "metadata": {
                    "ticket": "4711"
                  },
                  "mode": "sync",
                  "object": "response",
                  "output": {
                    "format": "markdown",
                    "language": "en",
                    "text": "Hello Anna, the farm shop is open on Saturdays from 9 to 14."
                  },
                  "output_message_id": "msg_0000000000002347",
                  "status": "completed",
                  "usage": {
                    "credits": 1
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ResponseObject"
                }
              }
            },
            "description": "Successful Response"
          },
          "202": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "completed_at": null,
                  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "created_at": "2026-11-10T16:30:45Z",
                  "end_user": {
                    "id": "u-17",
                    "name": "Anna"
                  },
                  "error": null,
                  "external_id": "ticket-4711",
                  "handoff": {
                    "requested": false,
                    "status": null
                  },
                  "id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
                  "input_message_id": null,
                  "metadata": {
                    "ticket": "4711"
                  },
                  "mode": "async",
                  "object": "response",
                  "output": null,
                  "output_message_id": null,
                  "status": "queued",
                  "usage": {
                    "credits": 0
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ResponseObject"
                }
              }
            },
            "description": "Accepted (async)"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "402": {
            "$ref": "#/components/responses/Error402"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          },
          "504": {
            "$ref": "#/components/responses/Error504"
          }
        },
        "summary": "Send a message",
        "tags": [
          "Responses"
        ],
        "x-required-scope": "chat:write",
        "x-requires-write-integration": true
      }
    },
    "/responses/{response_id}": {
      "get": {
        "description": "The state and result of a response, e.g. an async one: queued, in_progress, completed or failed.\nRequires `chat:write`.",
        "operationId": "get_response_responses__response_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "response_id",
            "required": true,
            "schema": {
              "title": "Response Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "completed_at": "2026-11-10T16:30:47Z",
                  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "created_at": "2026-11-10T16:30:45Z",
                  "end_user": {
                    "id": "u-17",
                    "name": "Anna"
                  },
                  "error": null,
                  "external_id": "ticket-4711",
                  "handoff": {
                    "requested": false,
                    "status": null
                  },
                  "id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
                  "input_message_id": "msg_0000000000002346",
                  "metadata": {
                    "ticket": "4711"
                  },
                  "mode": "async",
                  "object": "response",
                  "output": {
                    "format": "markdown",
                    "language": "en",
                    "text": "Hello Anna, the farm shop is open on Saturdays from 9 to 14."
                  },
                  "output_message_id": "msg_0000000000002347",
                  "status": "completed",
                  "usage": {
                    "credits": 1
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ResponseObject"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Get a response",
        "tags": [
          "Responses"
        ],
        "x-required-scope": "chat:write",
        "x-requires-write-integration": false
      }
    },
    "/webhook-endpoints": {
      "get": {
        "description": "The endpoints of this integration. Requires `webhooks:write`.",
        "operationId": "list_endpoints_webhook_endpoints_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "created_at": "2026-11-10T16:30:45Z",
                      "description": "CRM sync",
                      "disabled_reason": null,
                      "events": [
                        "lead.created",
                        "response.completed"
                      ],
                      "failing_since": null,
                      "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
                      "integration_id": "int_5UZEgyPjQc9cfpQlGJB3CuGX",
                      "object": "webhook_endpoint",
                      "secret_last4": "x9Qe",
                      "status": "active",
                      "updated_at": "2026-11-10T16:30:45Z",
                      "url": "https://example.com/ultimo/webhooks"
                    }
                  ],
                  "next_cursor": null,
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointList"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "List webhook endpoints",
        "tags": [
          "Webhooks"
        ],
        "x-required-scope": "webhooks:write",
        "x-requires-write-integration": false
      },
      "post": {
        "description": "Creates an endpoint and returns its signing secret once. Requires `webhooks:write`.",
        "operationId": "create_endpoint_route_webhook_endpoints_post",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "description": "CRM sync",
                "events": [
                  "lead.created",
                  "response.completed"
                ],
                "url": "https://example.com/ultimo/webhooks"
              },
              "schema": {
                "$ref": "#/components/schemas/EndpointCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "example": {
                  "created_at": "2026-11-10T16:30:45Z",
                  "description": "CRM sync",
                  "disabled_reason": null,
                  "events": [
                    "lead.created",
                    "response.completed"
                  ],
                  "failing_since": null,
                  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
                  "integration_id": "int_5UZEgyPjQc9cfpQlGJB3CuGX",
                  "object": "webhook_endpoint",
                  "secret": "whsec_3fJ8kQ2mZ7xV1bN6cR0dLpYt5Hs9WgUeAaBbCcDdEe0",
                  "secret_last4": "x9Qe",
                  "status": "active",
                  "updated_at": "2026-11-10T16:30:45Z",
                  "url": "https://example.com/ultimo/webhooks"
                },
                "schema": {
                  "$ref": "#/components/schemas/EndpointCreated"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Create a webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "x-required-scope": "webhooks:write",
        "x-requires-write-integration": true
      }
    },
    "/webhook-endpoints/{endpoint_id}": {
      "delete": {
        "description": "Requires `webhooks:write`.",
        "operationId": "delete_endpoint_webhook_endpoints__endpoint_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "endpoint_id",
            "required": true,
            "schema": {
              "title": "Endpoint Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "deleted": true,
                  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
                  "object": "webhook_endpoint"
                },
                "schema": {
                  "$ref": "#/components/schemas/WebhookEndpointDeleted"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Delete a webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "x-required-scope": "webhooks:write",
        "x-requires-write-integration": true
      },
      "get": {
        "description": "Requires `webhooks:write`.",
        "operationId": "get_endpoint_webhook_endpoints__endpoint_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "endpoint_id",
            "required": true,
            "schema": {
              "title": "Endpoint Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "created_at": "2026-11-10T16:30:45Z",
                  "description": "CRM sync",
                  "disabled_reason": null,
                  "events": [
                    "lead.created",
                    "response.completed"
                  ],
                  "failing_since": null,
                  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
                  "integration_id": "int_5UZEgyPjQc9cfpQlGJB3CuGX",
                  "object": "webhook_endpoint",
                  "secret_last4": "x9Qe",
                  "status": "active",
                  "updated_at": "2026-11-10T16:30:45Z",
                  "url": "https://example.com/ultimo/webhooks"
                },
                "schema": {
                  "$ref": "#/components/schemas/EndpointObject"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Get a webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "x-required-scope": "webhooks:write",
        "x-requires-write-integration": false
      },
      "patch": {
        "description": "Change address, events or description, pause (`disabled`) or resume (`active`). Requires `webhooks:write`.",
        "operationId": "patch_endpoint_webhook_endpoints__endpoint_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "endpoint_id",
            "required": true,
            "schema": {
              "title": "Endpoint Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "status": "disabled"
              },
              "schema": {
                "$ref": "#/components/schemas/EndpointPatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "created_at": "2026-11-10T16:30:45Z",
                  "description": "CRM sync",
                  "disabled_reason": "manual",
                  "events": [
                    "lead.created",
                    "response.completed"
                  ],
                  "failing_since": null,
                  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
                  "integration_id": "int_5UZEgyPjQc9cfpQlGJB3CuGX",
                  "object": "webhook_endpoint",
                  "secret_last4": "x9Qe",
                  "status": "disabled",
                  "updated_at": "2026-11-10T16:30:45Z",
                  "url": "https://example.com/ultimo/webhooks"
                },
                "schema": {
                  "$ref": "#/components/schemas/EndpointObject"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Change a webhook endpoint",
        "tags": [
          "Webhooks"
        ],
        "x-required-scope": "webhooks:write",
        "x-requires-write-integration": true
      }
    },
    "/webhook-endpoints/{endpoint_id}/rotate-secret": {
      "post": {
        "description": "A new secret, returned once. The old one keeps signing for 24 hours as a second v1 value.",
        "operationId": "rotate_route_webhook_endpoints__endpoint_id__rotate_secret_post",
        "parameters": [
          {
            "in": "path",
            "name": "endpoint_id",
            "required": true,
            "schema": {
              "title": "Endpoint Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "id": "we_4Hq9ZtB2mK7sX1vN6cR0dLpY",
                  "previous_secret_valid_until": "2026-11-11T16:30:45Z",
                  "secret": "whsec_9aK2mQ7xV1bN6cR0dLpYt5Hs3fJ8WgUeAaBbCcDdEe1"
                },
                "schema": {
                  "$ref": "#/components/schemas/SecretRotated"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Rotate the signing secret",
        "tags": [
          "Webhooks"
        ],
        "x-required-scope": "webhooks:write",
        "x-requires-write-integration": true
      }
    },
    "/webhook-endpoints/{endpoint_id}/test": {
      "post": {
        "description": "Queues a `webhook.test` event for this endpoint only. Requires `webhooks:write`.",
        "operationId": "test_endpoint_webhook_endpoints__endpoint_id__test_post",
        "parameters": [
          {
            "in": "path",
            "name": "endpoint_id",
            "required": true,
            "schema": {
              "title": "Endpoint Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                  "object": "event",
                  "queued": true,
                  "type": "webhook.test"
                },
                "schema": {
                  "$ref": "#/components/schemas/TestEventQueued"
                }
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "$ref": "#/components/responses/Error400"
          },
          "401": {
            "$ref": "#/components/responses/Error401"
          },
          "403": {
            "$ref": "#/components/responses/Error403"
          },
          "404": {
            "$ref": "#/components/responses/Error404"
          },
          "409": {
            "$ref": "#/components/responses/Error409"
          },
          "422": {
            "$ref": "#/components/responses/Error422"
          },
          "429": {
            "$ref": "#/components/responses/Error429"
          },
          "500": {
            "$ref": "#/components/responses/Error500"
          },
          "503": {
            "$ref": "#/components/responses/Error503"
          }
        },
        "summary": "Send a test event",
        "tags": [
          "Webhooks"
        ],
        "x-required-scope": "webhooks:write",
        "x-requires-write-integration": true
      }
    }
  },
  "security": [
    {
      "ServiceKey": []
    }
  ],
  "servers": [
    {
      "url": "https://api.ultimo-bots.com/v1"
    }
  ],
  "webhooks": {
    "credits.exhausted": {
      "post": {
        "description": "The AI credits are used up; the agent answers 402 until credits are added. Sent once per period. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_credits_exhausted",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": null,
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "allowance": 10000,
                  "object": "credits",
                  "remaining": 0,
                  "unit": "credits",
                  "window_start": "2026-11-01T00:00:00Z"
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "credits.exhausted"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/CreditsEvent"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "credits.exhausted"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "credits.exhausted",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "credits.low": {
      "post": {
        "description": "At most 10 % of the period's AI credits are left. Sent once per period. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_credits_low",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": null,
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "allowance": 10000,
                  "object": "credits",
                  "remaining": 900,
                  "unit": "credits",
                  "window_start": "2026-11-01T00:00:00Z"
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "credits.low"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/CreditsEvent"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "credits.low"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "credits.low",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "handoff.ended": {
      "post": {
        "description": "The handoff ended; the agent answers again. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_handoff_ended",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "ended_reason": "session_ended",
                  "object": "handoff",
                  "requested_at": "2026-11-10T16:30:45Z",
                  "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "status": "ended",
                  "visitor_name": "Anna"
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "handoff.ended"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/HandoffEvent"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "handoff.ended"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "handoff.ended",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "handoff.message": {
      "post": {
        "description": "A person of the business wrote in a handoff. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_handoff_message",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "channel": "api",
                  "content": "Hi Anna, Tom here. I will check your order.",
                  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "created_at": "2026-11-10T16:30:45Z",
                  "id": "msg_0000000000002351",
                  "object": "message",
                  "role": "staff",
                  "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH"
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "handoff.message"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/StaffMessageEvent"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "handoff.message"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "handoff.message",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "handoff.requested": {
      "post": {
        "description": "A visitor asked for a person of the business (or one took over). Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_handoff_requested",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "object": "handoff",
                  "requested_at": "2026-11-10T16:30:45Z",
                  "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "status": "agent_requested",
                  "visitor_name": "Anna"
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "handoff.requested"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/HandoffEvent"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "handoff.requested"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "handoff.requested",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "knowledge.operation.completed": {
      "post": {
        "description": "A knowledge operation (add, change, refresh, delete) finished. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_knowledge_operation_completed",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": null,
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "action": "ingest",
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "created_at": "2026-11-10T16:30:45Z",
                  "error_code": null,
                  "finished_at": "2026-11-10T16:30:47Z",
                  "id": "8735fcb4-5d35-4c9b-ac8b-300546fa1a3d",
                  "object": "operation",
                  "result": {
                    "indexed_knowledge_ids": [
                      226069
                    ]
                  },
                  "status": "completed"
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "knowledge.operation.completed"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/OperationEvent"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "knowledge.operation.completed"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "knowledge.operation.completed",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "knowledge.operation.failed": {
      "post": {
        "description": "A knowledge operation failed. `data.error_code` says why. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_knowledge_operation_failed",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": null,
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "action": "ingest",
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "created_at": "2026-11-10T16:30:45Z",
                  "error_code": "SOURCE_UNAVAILABLE",
                  "finished_at": "2026-11-10T16:30:47Z",
                  "id": "21bc0b41-3ee8-4f14-8e08-e5148524c3c1",
                  "object": "operation",
                  "result": null,
                  "status": "failed"
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "knowledge.operation.failed"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/OperationEvent"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "knowledge.operation.failed"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "knowledge.operation.failed",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "lead.created": {
      "post": {
        "description": "An agent collected a lead, on any channel. `data.fields` holds what the visitor gave. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_lead_created",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "created_at": "2026-11-10T17:00:37.539882Z",
                  "fields": {
                    "email": "anna@example.com",
                    "name": "Anna Example"
                  },
                  "id": 46,
                  "object": "lead",
                  "read": false,
                  "session_id": "api-conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "type": "contact"
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "lead.created"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/LeadEvent"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "lead.created"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "lead.created",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "response.completed": {
      "post": {
        "description": "An async response finished. `data` is the response object. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_response_completed",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "completed_at": "2026-11-10T16:30:47Z",
                  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "created_at": "2026-11-10T16:30:45Z",
                  "end_user": {
                    "id": "u-17",
                    "name": "Anna"
                  },
                  "error": null,
                  "external_id": "ticket-4711",
                  "handoff": {
                    "requested": false,
                    "status": null
                  },
                  "id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
                  "input_message_id": "msg_0000000000002346",
                  "metadata": {
                    "ticket": "4711"
                  },
                  "mode": "async",
                  "object": "response",
                  "output": {
                    "format": "markdown",
                    "language": "en",
                    "text": "Hello Anna, the farm shop is open on Saturdays from 9 to 14."
                  },
                  "output_message_id": "msg_0000000000002347",
                  "status": "completed",
                  "usage": {
                    "credits": 1
                  }
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "response.completed"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/ResponseObject"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "response.completed"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "response.completed",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "response.failed": {
      "post": {
        "description": "An async response failed. `data.error.code` says why. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_response_failed",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                  "completed_at": "2026-11-10T16:32:45Z",
                  "conversation_id": "conv_8TFivGiB5wHJqdt7FfRZkFYH",
                  "created_at": "2026-11-10T16:30:45Z",
                  "end_user": {
                    "id": "u-17",
                    "name": "Anna"
                  },
                  "error": {
                    "code": "generation_timeout",
                    "message": "The agent did not finish within 120 seconds."
                  },
                  "external_id": "ticket-4711",
                  "handoff": {
                    "requested": false,
                    "status": null
                  },
                  "id": "resp_Qk3mV8sT1xZ7bN4cL0pR2dHw",
                  "input_message_id": null,
                  "metadata": {
                    "ticket": "4711"
                  },
                  "mode": "async",
                  "object": "response",
                  "output": null,
                  "output_message_id": null,
                  "status": "failed",
                  "usage": {
                    "credits": 0
                  }
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "response.failed"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/ResponseObject"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "response.failed"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "response.failed",
        "tags": [
          "Webhook events"
        ]
      }
    },
    "webhook.test": {
      "post": {
        "description": "Sent by POST /v1/webhook-endpoints/{endpoint_id}/test or the portal's Send test button. Sent as a signed POST to your endpoint. Answer with a 2xx status within 10 seconds; anything else is retried (8 attempts over about 23 hours) with the same event id.",
        "operationId": "webhook_webhook_test",
        "parameters": [
          {
            "description": "t=<unix seconds>,v1=<hex>: v1 = HMAC-SHA256(secret, \"<t>.<raw body>\"). Two v1 values during a secret rotation.",
            "example": "t=1794328245,v1=5f0c9a...",
            "in": "header",
            "name": "Ultimo-Signature",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The event id (evt_...). The same on every retry: use it to drop duplicates.",
            "in": "header",
            "name": "Ultimo-Event-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Event-Type",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Ultimo-Delivery-Id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "agent_id": "c3e02486-f107-40c4-ac4d-e6155111bc8e",
                "api_version": "v1",
                "conversation_id": null,
                "created_at": "2026-11-10T16:30:45Z",
                "data": {
                  "message": "This is a test event from Ultimo.",
                  "object": "test"
                },
                "id": "evt_7Bn2QwLx0R5tVc8MzK1yHs4D",
                "object": "event",
                "type": "webhook.test"
              },
              "schema": {
                "properties": {
                  "agent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "api_version": {
                    "enum": [
                      "v1"
                    ],
                    "type": "string"
                  },
                  "conversation_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "created_at": {
                    "type": "string"
                  },
                  "data": {
                    "$ref": "#/components/schemas/TestEvent"
                  },
                  "id": {
                    "type": "string"
                  },
                  "object": {
                    "enum": [
                      "event"
                    ],
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "webhook.test"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "object",
                  "type",
                  "api_version",
                  "created_at",
                  "data"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "2XX": {
            "description": "Received."
          }
        },
        "security": [],
        "summary": "webhook.test",
        "tags": [
          "Webhook events"
        ]
      }
    }
  },
  "x-error-codes": [
    {
      "code": "content_too_large",
      "description": "The content is larger than the endpoint accepts.",
      "status": 400,
      "type": "invalid_request_error"
    },
    {
      "code": "context_not_allowed_in_group",
      "description": "`context` was sent to a group conversation. Everyone in a group reads the answer, so data about one person is not accepted there.",
      "status": 400,
      "type": "invalid_request_error"
    },
    {
      "code": "context_too_large",
      "description": "`context` is longer than 8000 characters.",
      "status": 400,
      "type": "invalid_request_error"
    },
    {
      "code": "invalid_argument",
      "description": "A parameter is invalid; the message says which.",
      "status": 400,
      "type": "invalid_request_error"
    },
    {
      "code": "invalid_cursor",
      "description": "`after` is not a next_cursor of this list.",
      "status": 400,
      "type": "invalid_request_error"
    },
    {
      "code": "invalid_idempotency_key",
      "description": "Idempotency-Key must be 1-255 printable characters.",
      "status": 400,
      "type": "invalid_request_error"
    },
    {
      "code": "invalid_webhook",
      "description": "The webhook address is not a public https address or an event type is unknown.",
      "status": 400,
      "type": "invalid_request_error"
    },
    {
      "code": "invalid_api_key",
      "description": "The key is missing, malformed, unknown, expired or revoked.",
      "status": 401,
      "type": "authentication_error"
    },
    {
      "code": "credits_exhausted",
      "description": "The agent's AI credits are used up. Nothing was stored.",
      "status": 402,
      "type": "payment_required_error"
    },
    {
      "code": "usage_limit_reached",
      "description": "The agent's monthly answer allowance is used up. Nothing was stored.",
      "status": 402,
      "type": "payment_required_error"
    },
    {
      "code": "access_denied",
      "description": "The key is no longer valid for this operation.",
      "status": 403,
      "type": "permission_error"
    },
    {
      "code": "all_agents_required",
      "description": "The operation needs an integration that may use all agents.",
      "status": 403,
      "type": "permission_error"
    },
    {
      "code": "api_not_enabled",
      "description": "The API is not enabled for this workspace.",
      "status": 403,
      "type": "permission_error"
    },
    {
      "code": "insufficient_scope",
      "description": "The integration lacks the scope the endpoint requires.",
      "status": 403,
      "type": "permission_error"
    },
    {
      "code": "plan_limit_reached",
      "description": "A limit of the plan is reached, e.g. the number of knowledge sources.",
      "status": 403,
      "type": "permission_error"
    },
    {
      "code": "plan_restricted",
      "description": "The agent's plan does not include the API (or the requested feature).",
      "status": 403,
      "type": "permission_error"
    },
    {
      "code": "read_only_integration",
      "description": "The integration is read-only and the endpoint changes something.",
      "status": 403,
      "type": "permission_error"
    },
    {
      "code": "not_found",
      "description": "The resource does not exist or belongs to another workspace or integration.",
      "status": 404,
      "type": "not_found_error"
    },
    {
      "code": "method_not_allowed",
      "description": "The path exists, the method does not.",
      "status": 405,
      "type": "invalid_request_error"
    },
    {
      "code": "ambiguous_conversation",
      "description": "The conversation reference matches several agents.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "conversation_agent_mismatch",
      "description": "The conversation belongs to a different agent.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "conversation_deleted",
      "description": "The conversation was deleted while the answer was produced.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "conversation_mismatch",
      "description": "conversation_id and external_id name different conversations.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "endpoint_disabled",
      "description": "The webhook endpoint is paused. Resume it first.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "endpoint_limit",
      "description": "The integration already has 10 webhook endpoints.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "idempotency_conflict",
      "description": "The Idempotency-Key was already used with a different request.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "operation_in_progress",
      "description": "Another operation on this resource is still running.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "plan_unavailable",
      "description": "The plan of the agent could not be determined.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "request_in_progress",
      "description": "A request with this Idempotency-Key is still running. Retry after Retry-After.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "retryable_conflict",
      "description": "A concurrent change got in the way. Retry the request.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "session_ended",
      "description": "The live session has ended.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "version_conflict",
      "description": "expected_version or expected_revision is outdated. Read the resource again.",
      "status": 409,
      "type": "conflict_error"
    },
    {
      "code": "validation_error",
      "description": "The request body or a query parameter is invalid; `errors` lists the fields.",
      "status": 422,
      "type": "invalid_request_error"
    },
    {
      "code": "concurrency_limit_exceeded",
      "description": "The workspace already runs its maximum of answers at once. Retry or use async.",
      "status": 429,
      "type": "rate_limit_error"
    },
    {
      "code": "queue_limit_exceeded",
      "description": "The workspace already has its maximum of async requests waiting (100). Retry after Retry-After.",
      "status": 429,
      "type": "rate_limit_error"
    },
    {
      "code": "rate_limit_exceeded",
      "description": "More requests per minute than allowed. Retry after Retry-After.",
      "status": 429,
      "type": "rate_limit_error"
    },
    {
      "code": "too_many_failed_attempts",
      "description": "Too many requests with a missing or invalid key from this address. Retry after Retry-After.",
      "status": 429,
      "type": "rate_limit_error"
    },
    {
      "code": "expired",
      "description": "The async job waited longer than 15 minutes and was not run. Send the request again if needed.",
      "status": 500,
      "type": "api_error"
    },
    {
      "code": "generation_failed",
      "description": "The answer could not be generated. Retry the request.",
      "status": 500,
      "type": "api_error"
    },
    {
      "code": "integration_revoked",
      "description": "The integration was revoked before the async job ran.",
      "status": 500,
      "type": "api_error"
    },
    {
      "code": "internal_error",
      "description": "An internal error. Retry; contact support with the request id if it stays.",
      "status": 500,
      "type": "api_error"
    },
    {
      "code": "interrupted",
      "description": "The request or async job was interrupted (restart) and was not run again.",
      "status": 500,
      "type": "api_error"
    },
    {
      "code": "api_capacity_exhausted",
      "description": "The API is at capacity. Retry after Retry-After or use async.",
      "status": 503,
      "type": "service_unavailable_error"
    },
    {
      "code": "feature_unavailable",
      "description": "The feature is not available on this installation.",
      "status": 503,
      "type": "service_unavailable_error"
    },
    {
      "code": "provider_unavailable",
      "description": "A service the operation needs did not answer. Retry later.",
      "status": 503,
      "type": "service_unavailable_error"
    },
    {
      "code": "upload_unavailable",
      "description": "File uploads are not available right now.",
      "status": 503,
      "type": "service_unavailable_error"
    },
    {
      "code": "worker_unavailable",
      "description": "The knowledge worker is not available. Retry later.",
      "status": 503,
      "type": "service_unavailable_error"
    },
    {
      "code": "generation_timeout",
      "description": "The agent did not finish within 120 seconds.",
      "status": 504,
      "type": "api_error"
    }
  ]
}
