{
  "openapi": "3.0.0",
  "paths": {
    "/external/users": {
      "post": {
        "description": "Creates a new conversation user using either an email or phoneNumber.",
        "operationId": "ExternalApiUsersController_createConversationUser",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Provide the user details to create.",
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/CreateUserWithPhoneNumberBodyDTO"
                  },
                  {
                    "$ref": "#/components/schemas/CreateUserWithEmailBodyDTO"
                  },
                  {
                    "$ref": "#/components/schemas/CreateUserWithFkIdBodyDTO"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created a new conversation user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiUserResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "User already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Create a conversation user",
        "tags": [
          "Users",
          "Agent API Key"
        ]
      }
    },
    "/external/users/search": {
      "get": {
        "description": "Retrieves a user by their email, phone number or fkId, along with their conversation IDs for the current agent.",
        "operationId": "ExternalApiUsersController_findUserByContactInfo",
        "parameters": [
          {
            "name": "email",
            "required": false,
            "in": "query",
            "description": "User email",
            "schema": {
              "example": "test@test.com",
              "type": "string"
            }
          },
          {
            "name": "phoneNumber",
            "required": false,
            "in": "query",
            "description": "User phone number",
            "schema": {
              "example": "+1234567890",
              "type": "string"
            }
          },
          {
            "name": "fkId",
            "required": false,
            "in": "query",
            "description": "User fkId",
            "schema": {
              "example": "123456",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the user and conversation ids",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchConversationUserByContactsResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters provided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "User not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Find user by contact information",
        "tags": [
          "Users",
          "Agent API Key"
        ]
      }
    },
    "/external/users/{id}": {
      "get": {
        "description": "Retrieves a conversation user by their unique identifier.",
        "operationId": "ExternalApiUsersController_getConversationUser",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the conversation user.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the conversation user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiUserResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "User not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get conversation user by ID",
        "tags": [
          "Users",
          "Agent API Key"
        ]
      },
      "delete": {
        "description": "Delete a conversation user by their unique identifier.",
        "operationId": "ExternalApiUsersController_deleteConversationUserById",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the conversation user.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully delete the conversation user."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Conversation user not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Delete conversation user by ID",
        "tags": [
          "Users",
          "Agent API Key"
        ]
      }
    },
    "/external/users/{id}/limits": {
      "get": {
        "description": "Retrieves limits for a conversation user by their unique identifier.",
        "operationId": "ExternalApiUsersController_getConversationUserLimits",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the conversation user.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved conversation user limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationUserLimitsResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "User not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get conversation user limits by ID",
        "tags": [
          "Users",
          "Agent API Key"
        ]
      },
      "post": {
        "description": "Creates limits for a conversation user by their unique identifier.",
        "operationId": "ExternalApiUsersController_createConversationUserLimits",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the conversation user.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConversationUserLimitsBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created conversation user limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationUserLimitsResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "User not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Create conversation user limits by ID",
        "tags": [
          "Users",
          "Agent API Key"
        ]
      },
      "put": {
        "description": "Updates limits for a conversation user by their unique identifier.",
        "operationId": "ExternalApiUsersController_updateConversationUserLimits",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the conversation user.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateConversationUserLimitsBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated conversation user limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationUserLimitsResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "User not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Update conversation user limits by ID",
        "tags": [
          "Users",
          "Agent API Key"
        ]
      },
      "delete": {
        "description": "Deletes limits for a conversation user by their unique identifier.",
        "operationId": "ExternalApiUsersController_deleteConversationUserLimits",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the conversation user.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully deleted conversation user limits."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "User not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Delete conversation user limits by ID",
        "tags": [
          "Users",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations": {
      "get": {
        "description": "Fetches a conversations by agent API key. The response includes the conversation details.",
        "operationId": "ExternalApiConversationsController_getConversations",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Page size",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "orderBy",
            "required": false,
            "in": "query",
            "description": "Order by",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "updatedAt"
              ]
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Order direction",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          },
          {
            "name": "searchKeyword",
            "required": false,
            "in": "query",
            "description": "Search keyword in conversation title, summary, agent name, user first and last name, email and phone number",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "required": false,
            "in": "query",
            "description": "Conversation user ID",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "name": "startDate",
            "required": false,
            "in": "query",
            "description": "Start date of conversation updatedAt.",
            "schema": {
              "format": "date-time",
              "example": "2024-03-20T12:00:00Z",
              "type": "string"
            }
          },
          {
            "name": "endDate",
            "required": false,
            "in": "query",
            "description": "End date of conversation updatedAt.",
            "schema": {
              "format": "date-time",
              "example": "2024-03-20T12:00:00Z",
              "type": "string"
            }
          },
          {
            "name": "withFeedbacksOnly",
            "required": false,
            "in": "query",
            "description": "If true, returns conversations with at least one feedback",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully received conversations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetConversationWithFeedbacksResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get conversations",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      },
      "post": {
        "description": "Creates a new conversation . The response includes the conversation ID.",
        "operationId": "ExternalApiConversationsController_createConversation",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Details of the conversation to be created.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConversationBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created a new conversation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Create a new conversation",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      },
      "delete": {
        "description": "Delete all conversations associated with specified user in current agent.",
        "operationId": "ExternalApiConversationsController_deleteAllUsersConversations",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Provide user id.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteUserConversationsBodyDTO"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "Successfully delete all user conversations in current agent."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Delete all user conversations in current agent",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/states": {
      "get": {
        "description": "Fetches all available conversation states by agent API key.",
        "operationId": "ExternalApiConversationsController_getConversationStates",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successfully retrieved conversation states.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiGetConversationStateResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get conversation states",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/{id}": {
      "get": {
        "description": "Fetches a conversation by its unique ID. The response includes the conversation details.",
        "operationId": "ExternalApiConversationsController_getConversationById",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation to retrieve.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the conversation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationWithFeedbacksResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Conversation not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get conversation by ID",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      },
      "put": {
        "description": "Updates an existing conversation by ID. Returns the updated conversation.",
        "operationId": "ExternalApiConversationsController_updateConversation",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation to update.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Details of the conversation to be updated.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateConversationBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated the conversation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Conversation not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Update conversation",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/start": {
      "post": {
        "description": "Start a new conversation using either an email, SMS or voice as the communication method. The response includes the conversation ID.",
        "operationId": "ExternalApiConversationsController_startConversation",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "discriminator": {
                  "propertyName": "channel",
                  "mapping": {
                    "email": "#/components/schemas/StartEmailConversationBodyDTO",
                    "sms": "#/components/schemas/StartSmsConversationBodyDTO",
                    "voice": "#/components/schemas/StartVoiceConversationBodyDTO"
                  }
                },
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/StartEmailConversationBodyDTO"
                  },
                  {
                    "$ref": "#/components/schemas/StartSmsConversationBodyDTO"
                  },
                  {
                    "$ref": "#/components/schemas/StartVoiceConversationBodyDTO"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully start a new conversation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StartConversationResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Start a new conversation",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/{id}/messages": {
      "get": {
        "description": "Fetches all messages associated with a specific conversation ID.",
        "operationId": "ExternalApiConversationsController_getConversationMessages",
        "parameters": [
          {
            "name": "shouldIncludeFeedbacks",
            "required": false,
            "in": "query",
            "description": "If true, returns conversation messages with feedbacks",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Message created at order direction. Default: ASC",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation to retrieve messages for.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved conversation messages.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetConversationMessagesResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get conversation messages",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      },
      "post": {
        "description": "Send a new message to an agent using conversationId.",
        "operationId": "ExternalApiConversationsController_processMessage",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation to send a message to.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Provide conversationId and message.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProcessMessageBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully processed a message to an agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProcessMessageResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Send a message to an agent",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/{id}/messages/async": {
      "post": {
        "description": "Send a new message to an agent using conversationId.",
        "operationId": "ExternalApiConversationsController_sendMessage",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation to send a message to.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Provide conversationId and message.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMessageBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully sent a message to an agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendMessageResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Send a message to an agent (async)",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/{id}/messages/{questionMessageId}/response-on": {
      "get": {
        "description": "Fetches response on a specific conversation message ID.",
        "operationId": "ExternalApiConversationsController_getResponseOn",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation to retrieve message for.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "questionMessageId",
            "required": true,
            "in": "path",
            "description": "The ID of the question message to retrieve response for. (The message that the user sent to the AI agent)",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved conversation message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetResponseOnResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get response on",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/{id}/mode": {
      "put": {
        "description": "Updates conversation mode. Returns the updated conversation.",
        "operationId": "ExternalApiConversationsController_updateConversationMode",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation to update.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Details of the conversation mode to be updated.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateConversationModeBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated the conversation mode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Conversation not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Update conversation mode",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/{id}/send-manual-message": {
      "post": {
        "description": "Send a manual message to a user in a conversation that is in manual mode. Will fail if the conversation is not in manual mode or is a voice conversation.",
        "operationId": "ExternalApiConversationsController_sendManualMessage",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation to send a message to the user.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Provide message to send to the user.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendMessageToUserBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Message sent successfully to the user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SendMessageResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Conversation must be in manual mode and not a voice conversation."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Conversation not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Send a manual message to a user",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/{id}/message-files/upload-url": {
      "post": {
        "description": "Creates a signed URL that allows uploading a file that can later be attached to a message via the send message API (use returned storagePath in body.files).",
        "operationId": "ExternalApiConversationsController_createConversationMessageFileSignedUploadUrl",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation to create upload URL for.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Provide fileName and contentType.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConversationMessageFileSignedUploadUrlBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully created signed upload URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateConversationMessageFileSignedUploadUrlResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Create signed upload URL for conversation message file",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/conversations/{id}/message-files/{fileId}/signed-url": {
      "get": {
        "description": "Returns a signed URL to download a specific conversation message file. The file must belong to the conversation and agent specified by API key.",
        "operationId": "ExternalApiConversationsController_getConversationMessageFileSignedUrl",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "fileId",
            "required": true,
            "in": "path",
            "description": "The ID of the conversation message file.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully generated signed download URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetConversationMessageFileSignedUrlResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get signed download URL for conversation message file",
        "tags": [
          "Conversations",
          "Agent API Key"
        ]
      }
    },
    "/external/prompts": {
      "post": {
        "description": "Processes a user prompt and returns an AI-generated response. The request must contain a valid API key.",
        "operationId": "ExternalApiPromptsController_processPromptSync",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Provide the prompt text to process.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProcessPromptBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully processed the prompt and returned a response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProcessPromptResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Process a prompt request",
        "tags": [
          "Prompts",
          "Agent API Key"
        ]
      }
    },
    "/external/prompts/async": {
      "post": {
        "description": "Creates a user prompt and returns an ID. The request must contain a valid API key.",
        "operationId": "ExternalApiPromptsController_createPromptJob",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Provide the prompt text to process.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePromptBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully created the prompt and returned an ID.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatePromptResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Create a prompt request",
        "tags": [
          "Prompts",
          "Agent API Key"
        ]
      }
    },
    "/external/prompts/{id}/response-on": {
      "get": {
        "description": "Returns a response on a user prompt by ID. The request must contain a valid API key.",
        "operationId": "ExternalApiPromptsController_getResponseOnPrompt",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Provide the prompt ID to process.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully returned a response on the prompt. Returns null if the prompt is not ready.",
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/GetResponseOnPromptResponseDTO"
                },
                {
                  "type": "null"
                }
              ]
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetResponseOnPromptResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get a response on prompt request",
        "tags": [
          "Prompts",
          "Agent API Key"
        ]
      }
    },
    "/external/prompts/upload-url": {
      "post": {
        "description": "Creates a signed URL that allows uploading a file that can later be attached to a prompt via the create prompt API (use returned storagePath in body.files).",
        "operationId": "ExternalApiPromptsController_createPromptFileSignedUploadUrl",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Provide fileName and contentType.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePromptFileSignedUploadUrlBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully created signed upload URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatePromptFileSignedUploadUrlResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Create signed upload URL for prompt file",
        "tags": [
          "Prompts",
          "Agent API Key"
        ]
      }
    },
    "/external/agents": {
      "get": {
        "description": "Fetches all agents across all organizations by admin API key, with optional filtering by status and search keyword. The response includes agent details with the owning organization, paginated.",
        "operationId": "ExternalApiAgentsController_getAllAgents",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Page size",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "orderBy",
            "required": false,
            "in": "query",
            "description": "Order by",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "name",
                "publicName",
                "updatedAt"
              ]
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Order direction",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          },
          {
            "name": "searchKeyword",
            "required": false,
            "in": "query",
            "description": "Case-insensitive keyword matched against the agent name or public name.",
            "schema": {
              "example": "Support",
              "type": "string"
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Agent status.",
            "schema": {
              "example": "active",
              "type": "string",
              "enum": [
                "active",
                "inactive",
                "draft"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved agents.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiGetAllAgentsResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Super-Admin-Secret-Key": []
          }
        ],
        "summary": "Get all agents via admin API key",
        "tags": [
          "Super Admin API Key",
          "Agents"
        ]
      },
      "post": {
        "description": "Creates an agent by organization API key. When model is omitted, the organization default model is used. The response includes the agent details.",
        "operationId": "ExternalApiAgentsController_createAgentByApiKey",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentByApiKeyBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateAgentResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Create agent via organization API key",
        "tags": [
          "Organization API Key",
          "Agents"
        ]
      }
    },
    "/external/agents/{id}/users": {
      "get": {
        "description": "Fetches agent users by agent ID and Organization API key. The response includes the agent users details.",
        "operationId": "ExternalApiAgentsController_getOrganizationAgentUsers",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Page size",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "orderBy",
            "required": false,
            "in": "query",
            "description": "Order by",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt"
              ]
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Order direction",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved agent users.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetOrganizationAgentUsersResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get agent users by agent ID and Organization API key",
        "tags": [
          "Agents",
          "Organization API Key"
        ]
      }
    },
    "/external/agents/{id}/platform-users": {
      "get": {
        "description": "Fetches the platform users who have access to the agent, together with their agent-level and organization-level roles and statuses. Access includes direct user-to-agent assignments in any role and implicit access for organization owners and admins. The agent must belong to the organization resolved from the Organization API key.",
        "operationId": "ExternalApiAgentsController_getAgentPlatformUsers",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Page size",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "orderBy",
            "required": false,
            "in": "query",
            "description": "Order by",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt"
              ]
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Order direction",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved agent platform users.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAgentPlatformUsersResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get agent platform users by agent ID and Organization API key",
        "tags": [
          "Agents",
          "Organization API Key",
          "Platform Users"
        ]
      }
    },
    "/external/agents/users": {
      "get": {
        "description": "Fetches agent users by Agent API key. The response includes the agent users details.",
        "operationId": "ExternalApiAgentsController_getAgentUsersByApiKey",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Page size",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "orderBy",
            "required": false,
            "in": "query",
            "description": "Order by",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt"
              ]
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Order direction",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved agent users.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAgentUsersByApiKeyResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get agent users by Agent API key",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      }
    },
    "/external/agents/admin-users": {
      "get": {
        "description": "Fetches the platform users who administer the agent resolved by the provided Agent API key. Includes users with a direct owner or admin role on the agent, and active organization owners or admins of the organization that owns the agent. Each entry contains the user email together with agent-level and organization-level role, status, and access source.",
        "operationId": "ExternalApiAgentsController_getAgentAdminUsersByApiKey",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Page size",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "orderBy",
            "required": false,
            "in": "query",
            "description": "Order by",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt"
              ]
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Order direction",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved agent admin users.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAgentAdminUsersByApiKeyResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get agent admin users by Agent API key",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      }
    },
    "/external/agents/by-api-key": {
      "get": {
        "description": "Fetches an agent by API key. The response includes the agent details.",
        "operationId": "ExternalApiAgentsController_getAgentByApiKey",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successfully retrieved the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAgentByApiKeyResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get agent by API key",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      }
    },
    "/external/agents/statistic": {
      "get": {
        "description": "Fetches an agent statistic by API key. The response includes the agent statistic.",
        "operationId": "ExternalApiAgentsController_getAgentStatistic",
        "parameters": [
          {
            "name": "startDate",
            "required": false,
            "in": "query",
            "description": "Start date of statistics calculation.",
            "schema": {
              "format": "date-time",
              "example": "2024-03-20T12:00:00Z",
              "type": "string"
            }
          },
          {
            "name": "endDate",
            "required": false,
            "in": "query",
            "description": "End date of statistics calculation.",
            "schema": {
              "format": "date-time",
              "example": "2024-03-20T12:00:00Z",
              "type": "string"
            }
          },
          {
            "name": "fkId",
            "required": false,
            "in": "query",
            "description": "Conversation user fkId.",
            "schema": {
              "example": "",
              "type": "string"
            }
          },
          {
            "name": "fkUserId",
            "required": false,
            "in": "query",
            "description": "Conversation user fkUserId.",
            "schema": {
              "example": "",
              "type": "string"
            }
          },
          {
            "name": "userId",
            "required": false,
            "in": "query",
            "description": "Conversation user userId.",
            "schema": {
              "format": "uuid",
              "example": "",
              "type": "string"
            }
          },
          {
            "name": "conversationUserId",
            "required": false,
            "in": "query",
            "description": "Conversation user id.",
            "schema": {
              "format": "uuid",
              "example": "",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the agent statistic.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiGetAgentStatisticResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get agent statistic by API key",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      }
    },
    "/external/agents/webhooks": {
      "post": {
        "description": "Creates a new webhook for the agent identified by the API key.",
        "operationId": "ExternalApiAgentsController_createAgentWebhook",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentWebhookBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created the webhook.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateAgentWebhookResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Invalid webhook URL. The URL must use HTTPS and resolve only to public IP addresses.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Create agent webhook",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      }
    },
    "/external/agents/limits": {
      "get": {
        "description": "Fetches agent limits for the agent resolved by the provided Agent API key.",
        "operationId": "ExternalApiAgentsController_getAgentLimitsByApiKey",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successfully retrieved agent limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentLimitsResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get agent limits by Agent API key",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      },
      "post": {
        "description": "Creates agent limits for the agent resolved by the provided Agent API key.",
        "operationId": "ExternalApiAgentsController_createAgentLimitsByApiKey",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentLimitsBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created agent limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentLimitsResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Create agent limits by Agent API key",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      },
      "put": {
        "description": "Updates agent limits for the agent resolved by the provided Agent API key.",
        "operationId": "ExternalApiAgentsController_updateAgentLimitsByApiKey",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAgentLimitsBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated agent limits.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentLimitsResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Update agent limits by Agent API key",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      },
      "delete": {
        "description": "Deletes agent limits for the agent resolved by the provided Agent API key.",
        "operationId": "ExternalApiAgentsController_deleteAgentLimitsByApiKey",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successfully deleted agent limits."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Delete agent limits by Agent API key",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      }
    },
    "/external/agents/usage": {
      "get": {
        "description": "Fetches agent usage for the agent resolved by the provided Agent API key.",
        "operationId": "ExternalApiAgentsController_getAgentUsageByApiKey",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successfully retrieved agent usage.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentUsageResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get agent usage by Agent API key",
        "tags": [
          "Agents",
          "Agent API Key"
        ]
      }
    },
    "/external/agents/{id}": {
      "get": {
        "description": "Fetches an agent by ID using an organization API key. The response includes the agent details.",
        "operationId": "ExternalApiAgentsController_getAgentByOrgKeyAndId",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAgentByApiKeyResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get agent by ID via organization API key",
        "tags": [
          "Organization API Key",
          "Agents"
        ]
      },
      "put": {
        "description": "Updates an agent by organization API key. The response includes the updated agent details.",
        "operationId": "ExternalApiAgentsController_updateAgentByApiKey",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAgentByApiKeyBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAgentByApiKeyResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Update agent via organization API key",
        "tags": [
          "Organization API Key",
          "Agents"
        ]
      }
    },
    "/external/agent-scraps/{id}/scraping": {
      "get": {
        "description": "Returns all scraping configurations for an agent.",
        "operationId": "ExternalApiAgentScrapingController_getAgentScraps",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of scraping configurations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AgentScrapResponseDTO"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "List scraping configurations",
        "tags": [
          "Organization API Key",
          "Agent Scraping"
        ]
      },
      "post": {
        "description": "Creates a new scraping configuration and triggers an initial crawl immediately. Subsequent crawls run automatically on the configured frequency.",
        "operationId": "ExternalApiAgentScrapingController_createAgentScrap",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentScrapBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Scraping configuration created. Initial crawl triggered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentScrapResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "500": {
            "description": "Scraping skill is not enabled on this agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Create scraping configuration",
        "tags": [
          "Organization API Key",
          "Agent Scraping"
        ]
      }
    },
    "/external/agent-scraps/{id}/scraping/{scrapingId}": {
      "get": {
        "description": "Returns a single scraping configuration by ID.",
        "operationId": "ExternalApiAgentScrapingController_getAgentScrapById",
        "parameters": [
          {
            "name": "scrapingId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the scraping configuration.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scraping configuration found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentScrapResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent or scraping configuration not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get scraping configuration",
        "tags": [
          "Organization API Key",
          "Agent Scraping"
        ]
      },
      "put": {
        "description": "Updates a scraping configuration. All fields are optional. Any update triggers a new crawl immediately.",
        "operationId": "ExternalApiAgentScrapingController_updateAgentScrap",
        "parameters": [
          {
            "name": "scrapingId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the scraping configuration.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAgentScrapBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scraping configuration updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentScrapResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent or scraping configuration not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Update scraping configuration",
        "tags": [
          "Organization API Key",
          "Agent Scraping"
        ]
      },
      "delete": {
        "description": "Deletes a scraping configuration and removes all associated crawled files from the agent knowledge base.",
        "operationId": "ExternalApiAgentScrapingController_deleteAgentScrap",
        "parameters": [
          {
            "name": "scrapingId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the scraping configuration.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Scraping configuration deleted."
          },
          "404": {
            "description": "Agent or scraping configuration not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Delete scraping configuration",
        "tags": [
          "Organization API Key",
          "Agent Scraping"
        ]
      }
    },
    "/external/agent-scraps/{id}/scraping/{scrapingId}/run": {
      "post": {
        "description": "Triggers an immediate crawl for a scraping configuration outside the scheduled frequency.",
        "operationId": "ExternalApiAgentScrapingController_runAgentScrap",
        "parameters": [
          {
            "name": "scrapingId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the scraping configuration.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Crawl triggered. crawlingStatus updated to in_progress.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentScrapResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent or scraping configuration not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Trigger manual crawl",
        "tags": [
          "Organization API Key",
          "Agent Scraping"
        ]
      }
    },
    "/external/agent-scraps/{id}/scraping/{scrapingId}/cancel": {
      "post": {
        "description": "Cancels a crawl that is currently in progress.",
        "operationId": "ExternalApiAgentScrapingController_cancelAgentScrap",
        "parameters": [
          {
            "name": "scrapingId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the scraping configuration.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Crawl cancelled. crawlingStatus updated to canceled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentScrapResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent or scraping configuration not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Cancel in-progress crawl",
        "tags": [
          "Organization API Key",
          "Agent Scraping"
        ]
      }
    },
    "/external/agent-api-keys/{id}": {
      "post": {
        "description": "Creates an API key for an agent. The full key is returned once — store it securely as it cannot be retrieved again.",
        "operationId": "ExternalApiAgentApiKeysController_createApiKey",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentApiKeyBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created. The agentApiKey field is returned once only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateAgentApiKeyResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "500": {
            "description": "API skill is not enabled on this agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Create agent API key",
        "tags": [
          "Organization API Key",
          "Agent API Keys"
        ]
      },
      "get": {
        "description": "Returns all API keys for an agent. An agent may have more than one key. The full key value is never returned — only a masked preview.",
        "operationId": "ExternalApiAgentApiKeysController_listApiKeys",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API key metadata for the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AgentApiKeyResponseDTO"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "List agent API keys",
        "tags": [
          "Organization API Key",
          "Agent API Keys"
        ]
      }
    },
    "/external/agent-api-keys/{id}/api-key/{keyId}": {
      "get": {
        "description": "Returns metadata for a single API key. The full key value is never returned — only a masked preview.",
        "operationId": "ExternalApiAgentApiKeysController_getApiKey",
        "parameters": [
          {
            "name": "keyId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the API key.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API key metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentApiKeyResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent or API key not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get agent API key",
        "tags": [
          "Organization API Key",
          "Agent API Keys"
        ]
      },
      "delete": {
        "description": "Revokes the specified API key. The key is immediately invalidated. Use POST /rotate to revoke and replace in a single operation.",
        "operationId": "ExternalApiAgentApiKeysController_deleteApiKey",
        "parameters": [
          {
            "name": "keyId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the API key to revoke.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "API key revoked."
          },
          "404": {
            "description": "Agent or API key not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Revoke agent API key",
        "tags": [
          "Organization API Key",
          "Agent API Keys"
        ]
      }
    },
    "/external/agent-api-keys/{id}/api-key/{keyId}/rotate": {
      "post": {
        "description": "Revokes the specified API key and creates a new one. The new key is returned once — store it securely as it cannot be retrieved again. The previous key is immediately invalidated.",
        "operationId": "ExternalApiAgentApiKeysController_rotateApiKey",
        "parameters": [
          {
            "name": "keyId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the API key to rotate.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentApiKeyBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "New API key created. Previous key revoked. The agentApiKey field is returned once only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateAgentApiKeyResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent or API key not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Rotate agent API key",
        "tags": [
          "Organization API Key",
          "Agent API Keys"
        ]
      }
    },
    "/external/agent-files/upload": {
      "post": {
        "description": "This endpoint uploads an agent file associated with the provided API key.",
        "operationId": "ExternalApiAgentFilesController_uploadAgentFile",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Upload agent file",
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/UploadAgentFileBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully uploaded agent file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadAgentFileResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "File is required.\n\nFailed to upload agent file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Upload agent file",
        "tags": [
          "Agent-files",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-files/by-api-key": {
      "get": {
        "deprecated": true,
        "description": "Deprecated. Use GET /external/agent-files/by-api-key/paginated instead. This endpoint retrieves all agent files associated with the provided API key.",
        "operationId": "ExternalApiAgentFilesController_getAgentFilesByApiKey",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successfully retrieved agent files with details.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AgentFileResponseDTO"
                  }
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent files not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get agent files by API key",
        "tags": [
          "Agent-files",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-files/by-api-key/paginated": {
      "get": {
        "description": "This endpoint retrieves a paginated and sorted list of files associated with the provided Agent API key.",
        "operationId": "ExternalApiAgentFilesController_getAgentFilesPaginatedByApiKey",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Zero-based page number.",
            "schema": {
              "minimum": 0,
              "default": 0,
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Number of files per page.",
            "schema": {
              "minimum": 1,
              "maximum": 100,
              "default": 10,
              "type": "number"
            }
          },
          {
            "name": "orderBy",
            "required": false,
            "in": "query",
            "description": "File field used for sorting.",
            "schema": {
              "default": "createdAt",
              "type": "string",
              "enum": [
                "createdAt",
                "fileName"
              ]
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Sort direction.",
            "schema": {
              "default": "DESC",
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved a page of agent files.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAgentFilesPaginatedByApiKeyResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Invalid pagination or sorting query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get paginated agent files by API key",
        "tags": [
          "Agent-files",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-files/{id}": {
      "get": {
        "description": "This endpoint retrieves a single agent file by ID. The file must belong to the agent associated with the provided API key.",
        "operationId": "ExternalApiAgentFilesController_getAgentFileById",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent file.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the agent file with details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentFileResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent file not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Get agent file by ID",
        "tags": [
          "Agent-files",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-files": {
      "delete": {
        "description": "This endpoint deletes the agent files by ids",
        "operationId": "ExternalApiAgentFilesController_deleteAgentFiles",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Request body for deleting agent files.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeleteAgentFilesBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully deleted agent files."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Delete agent files by IDs",
        "tags": [
          "Agent-files",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-files/{id}/delete": {
      "delete": {
        "description": "This endpoint deletes the agent file by id",
        "operationId": "ExternalApiAgentFilesController_deleteAgentFile",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the agent file to delete.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully deleted agent file."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent file not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Delete agent file by ID",
        "tags": [
          "Agent-files",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-files/{id}/delete-from-vector-store": {
      "delete": {
        "description": "This endpoint deletes the agent file from vector store by id",
        "operationId": "ExternalApiAgentFilesController_deleteAgentFileFromVectorStore",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the agent file to delete from vector store.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully deleted agent file from vector store."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent file not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Delete agent file from vector store by ID",
        "tags": [
          "Agent-files",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-files/{id}/add-to-vector-store": {
      "put": {
        "description": "This endpoint adds the agent file to vector store by id",
        "operationId": "ExternalApiAgentFilesController_addFileToVectorStore",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the agent file to add to vector store.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully added agent file to vector store."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent file not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Add agent file to vector store by ID",
        "tags": [
          "Agent-files",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-files/{id}/add-to-vector-store/async": {
      "put": {
        "description": "This endpoint starts adding the agent file to the vector store and returns before processing is complete.",
        "operationId": "ExternalApiAgentFilesController_addFileToVectorStoreAsync",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "The ID of the agent file to add to vector store.",
            "schema": {
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully started adding agent file to vector store."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent file not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Add agent file to vector store asynchronously by ID",
        "tags": [
          "Agent-files",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-functions/{id}/functions": {
      "get": {
        "description": "Returns all functions registered on an agent.",
        "operationId": "ExternalApiAgentFunctionsController_getAgentFunctions",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of agent functions.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/AgentFunctionResponseDTO"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "List agent functions",
        "tags": [
          "Organization API Key",
          "Agent Functions"
        ]
      },
      "post": {
        "description": "Registers a new function on an agent. The agent can invoke this function mid-conversation using GET query parameters or a POST JSON body. Header values are write-only and never returned in GET responses.",
        "operationId": "ExternalApiAgentFunctionsController_createAgentFunction",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentFunctionBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Function created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentFunctionResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "409": {
            "description": "A function with this name already exists on the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Create agent function",
        "tags": [
          "Organization API Key",
          "Agent Functions"
        ]
      }
    },
    "/external/agent-functions/{id}/functions/{functionId}": {
      "get": {
        "description": "Returns a single function by ID. Header values are never returned.",
        "operationId": "ExternalApiAgentFunctionsController_getAgentFunctionById",
        "parameters": [
          {
            "name": "functionId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the function.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Agent function details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentFunctionResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent or function not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get agent function",
        "tags": [
          "Organization API Key",
          "Agent Functions"
        ]
      },
      "put": {
        "description": "Updates a function. All fields are optional — only supplied fields are updated. Supplying headers replaces all existing headers. Pass headers: {} to clear all headers.",
        "operationId": "ExternalApiAgentFunctionsController_updateAgentFunction",
        "parameters": [
          {
            "name": "functionId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the function.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAgentFunctionBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated function.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentFunctionResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent or function not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Update agent function",
        "tags": [
          "Organization API Key",
          "Agent Functions"
        ]
      },
      "delete": {
        "description": "Soft-deletes a function. The agent will no longer be able to invoke it.",
        "operationId": "ExternalApiAgentFunctionsController_deleteAgentFunction",
        "parameters": [
          {
            "name": "functionId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the function.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Function deleted."
          },
          "404": {
            "description": "Agent or function not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Delete agent function",
        "tags": [
          "Organization API Key",
          "Agent Functions"
        ]
      }
    },
    "/external/live-chat-skill/{agentId}": {
      "get": {
        "description": "Returns the live chat skill configuration for an agent.",
        "operationId": "ExternalApiAgentLiveChatController_getAgentLiveChat",
        "parameters": [
          {
            "name": "agentId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Live chat configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentLiveChatResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get live chat configuration",
        "tags": [
          "Organization API Key",
          "Live Chat"
        ]
      },
      "put": {
        "description": "Updates the live chat skill configuration. All fields are optional.",
        "operationId": "ExternalApiAgentLiveChatController_updateAgentLiveChat",
        "parameters": [
          {
            "name": "agentId",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the agent.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAgentLiveChatBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated live chat configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentLiveChatResponseDTO"
                }
              }
            }
          },
          "404": {
            "description": "Agent not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Update live chat configuration",
        "tags": [
          "Organization API Key",
          "Live Chat"
        ]
      }
    },
    "/external/live-chat-skill/images/upload-url": {
      "post": {
        "description": "Generates a signed URL for uploading an agent avatar or live chat image. The returned storagePath can be supplied as avatarStoragePath to the live chat update endpoint once the upload completes.",
        "operationId": "ExternalApiAgentLiveChatController_createImageUploadUrl",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentImageUploadUrlBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Signed upload URL created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentImageUploadUrlResponseDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Create agent image upload URL",
        "tags": [
          "Organization API Key",
          "Agent Images"
        ]
      }
    },
    "/external/resource-usage": {
      "post": {
        "description": "Add new resource usage log using type, amount, and optional model usage metadata.",
        "operationId": "ExternalApiResourceConsumptionLogsController_createResourceConsumptionLog",
        "parameters": [],
        "requestBody": {
          "required": true,
          "description": "Provide the resource type, amount, and optional model usage metadata.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateResourceUsageLogsBodyDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully add resource usage log."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Add new resource usage log.",
        "tags": [
          "Resource Usage Logs",
          "Agent API Key"
        ]
      }
    },
    "/external/agent-roles/by-api-key": {
      "get": {
        "description": "Fetches agent roles by organization API key. The response includes agent roles details.",
        "operationId": "ExternalApiAgentRolesController_getAgentRolesByApiKey",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successfully retrieved agent roles.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAgentRoleByApiKeyResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get agent roles by organization API key",
        "tags": [
          "Organization API Key",
          "Agent Roles"
        ]
      }
    },
    "/external/organizations/llm-models": {
      "get": {
        "description": "Retrieves the organization model access records whose global model is active. The optional status filter can be used to limit results to active or archived organization model access records.",
        "operationId": "ExternalApiOrganizationsController_getAccessibleLlmModels",
        "parameters": [
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Optional organization model access status filter. If omitted, both active and archived records are returned.",
            "schema": {
              "example": "active",
              "type": "string",
              "enum": [
                "active",
                "archived"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved accessible models.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ExternalApiOrganizationLlmModelResponseDTO"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid model status filter.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get accessible models for the current organization",
        "tags": [
          "Organization API Key",
          "Organizations"
        ]
      }
    },
    "/external/organizations/llm-models/{id}/default": {
      "put": {
        "description": "Sets an active accessible model as the current organization's default model. The model ID is the organization model access record ID returned by the accessible models endpoint.",
        "operationId": "ExternalApiOrganizationsController_setDefaultLlmModel",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Organization model access record ID.",
            "schema": {
              "format": "uuid",
              "example": "123e4567-e89b-12d3-a456-426614174000",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully set the organization default model.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiOrganizationLlmModelResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "The selected model must be active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Organization model access record not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Set the default model for the current organization",
        "tags": [
          "Organization API Key",
          "Organizations"
        ]
      }
    },
    "/external/organizations": {
      "get": {
        "description": "Fetches all organizations by admin API key, with optional filtering by status and search keyword. The response includes organization details with the subscription and agent count, paginated.",
        "operationId": "ExternalApiOrganizationsController_getAllOrganizations",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Page number",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Page size",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "orderBy",
            "required": false,
            "in": "query",
            "description": "Order by",
            "schema": {
              "type": "string",
              "enum": [
                "createdAt",
                "name",
                "updatedAt"
              ]
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Order direction",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          },
          {
            "name": "searchKeyword",
            "required": false,
            "in": "query",
            "description": "Case-insensitive keyword matched against the organization name or ID.",
            "schema": {
              "example": "Acme",
              "type": "string"
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Organization status.",
            "schema": {
              "example": "active",
              "type": "string",
              "enum": [
                "active",
                "pending",
                "archived",
                "blocked"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved organizations.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiGetAllOrganizationsResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Super-Admin-Secret-Key": []
          }
        ],
        "summary": "Get all organizations via admin API key",
        "tags": [
          "Super Admin API Key",
          "Organizations"
        ]
      },
      "post": {
        "description": "Creates an organization by admin API key. The response includes organization details.",
        "operationId": "ExternalApiOrganizationsController_createOrganizationByApiKey",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalApiCreateOrganizationByApiKeyBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created the organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiGetOrganizationResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Subscription not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Super-Admin-Secret-Key": []
          }
        ],
        "summary": "Create organization via admin API key",
        "tags": [
          "Super Admin API Key",
          "Organizations"
        ]
      }
    },
    "/external/organizations/by-organization-api-key": {
      "post": {
        "description": "Creates a new organization under the provided license key, exactly like creating an organization in the application. The license key is validated by the raia license service and a subscription (or trial) is attached. When ownerUserId is provided, that user must belong to the calling organization and becomes the owner; otherwise, the creator of the calling organization becomes the owner.",
        "operationId": "ExternalApiOrganizationsController_createOrganizationByOrganizationApiKey",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalApiCreateOrganizationByOrganizationApiKeyBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created the organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiGetOrganizationResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Invalid license key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Requested owner is not a member of the calling organization, or the calling organization creator was not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Create organization via organization API key",
        "tags": [
          "Organization API Key",
          "Organizations"
        ]
      }
    },
    "/external/subscriptions": {
      "get": {
        "description": "Fetches subscriptions by admin API key. The response includes the subscriptions details.",
        "operationId": "ExternalApiSubscriptionsController_findAllPaginated",
        "parameters": [
          {
            "name": "visibility",
            "required": false,
            "in": "query",
            "description": "Subscription visibility.",
            "schema": {
              "example": "public",
              "type": "string",
              "enum": [
                "public",
                "private"
              ]
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Subscription status.",
            "schema": {
              "example": "active",
              "type": "string",
              "enum": [
                "active",
                "inactive"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved subscriptions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiSubscriptionResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Super-Admin-Secret-Key": []
          }
        ],
        "summary": "Get subscriptions by admin API key",
        "tags": [
          "Super Admin API Key",
          "Subscriptions"
        ]
      }
    },
    "/external/conversation-message-feedbacks": {
      "post": {
        "description": "Create or update existing conversation message feedback. The response includes the conversation message feedback.",
        "operationId": "ExternalApiConversationMessageFeedbacksController_createOrUpdateFeedback",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExternalApiCrateOrUpdateConversationMessageFeedbackBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Conversation message feedback successfully created or updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalApiCrateOrUpdateConversationMessageFeedbackResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Agent-Secret-Key": []
          }
        ],
        "summary": "Create or update conversation message feedback",
        "tags": [
          "Conversation Message Feedbacks",
          "Agent API Key"
        ]
      }
    },
    "/external/platform-users": {
      "get": {
        "description": "Retrieves all platform users for the current organization, including their organization-level role and membership status. Optionally filter by role and/or status.",
        "operationId": "ExternalApiPlatformUsersController_getAllOrganizationPlatformUsers",
        "parameters": [
          {
            "name": "role",
            "required": false,
            "in": "query",
            "description": "Platform user organization role.",
            "schema": {
              "example": "user",
              "type": "string",
              "enum": [
                "owner",
                "admin",
                "manager",
                "user",
                "copilot_user",
                "copilot_admin",
                "guest"
              ]
            }
          },
          {
            "name": "status",
            "required": false,
            "in": "query",
            "description": "Status of the user's membership in the organization.",
            "schema": {
              "example": "active",
              "type": "string",
              "enum": [
                "active",
                "inactive"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved all platform users for the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAllOrganizationPlatformUsersResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get all platform users for the current organization.",
        "tags": [
          "Organization API Key",
          "Platform Users"
        ]
      }
    },
    "/external/platform-users/agents": {
      "get": {
        "description": "Fetches all agents a platform user has access to within the current organization, together with the role granting that access. Identify the user by exactly one of userId or email; the user must belong to the organization resolved from the Organization API key. Access includes direct user-to-agent assignments and, for active organization owners and admins, implicit access to every agent in the organization.",
        "operationId": "ExternalApiPlatformUsersController_getAgentsByPlatformUser",
        "parameters": [
          {
            "name": "userId",
            "required": false,
            "in": "query",
            "description": "Platform user ID. Provide exactly one of userId or email.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "email",
            "required": false,
            "in": "query",
            "description": "Platform user email. Provide exactly one of userId or email.",
            "schema": {
              "example": "user@example.com",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the agents the user has access to.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAgentsByPlatformUserResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Provide exactly one of userId or email.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "User not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get agents by platform user via organization API key",
        "tags": [
          "Organization API Key",
          "Platform Users",
          "Agents"
        ]
      }
    },
    "/external/platform-users/{userId}": {
      "patch": {
        "description": "Updates the organization-level role and/or membership status of a platform user in the current organization. Provide at least one of role or status. Setting status to inactive suspends the user's access to the organization without removing assignments or history; setting it back to active restores access. The owner role can be neither assigned nor modified through the external API, and the user who created the Organization API key in use cannot be modified with it.",
        "operationId": "ExternalApiPlatformUsersController_updateOrganizationPlatformUser",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "path",
            "description": "Platform user ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateOrganizationPlatformUserBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated the platform user.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateOrganizationPlatformUserResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Provide at least one of role or status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "User not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Update a platform user role or status via organization API key",
        "tags": [
          "Organization API Key",
          "Platform Users"
        ]
      }
    },
    "/external/packs": {
      "post": {
        "description": "Creates a new pack in the organization resolved from the Organization API key. Packs store shared instructions (core training) that can be linked to and imported by multiple agents. The pack is owned by the organization member who created the API key.",
        "operationId": "ExternalApiAgentPacksController_createPack",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePackBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created the pack.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackWithFilesResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Create a pack via organization API key",
        "tags": [
          "Organization API Key",
          "Packs"
        ]
      },
      "get": {
        "description": "Retrieves a paginated list of the organization's packs. Optionally filter by name and include inactive packs.",
        "operationId": "ExternalApiAgentPacksController_getPacks",
        "parameters": [
          {
            "name": "page",
            "required": false,
            "in": "query",
            "description": "Zero-based page number.",
            "schema": {
              "default": 0,
              "example": 0,
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "description": "Number of packs per page.",
            "schema": {
              "default": 10,
              "example": 10,
              "type": "number"
            }
          },
          {
            "name": "searchKeyword",
            "required": false,
            "in": "query",
            "description": "Filter packs whose name contains this keyword.",
            "schema": {
              "example": "support",
              "type": "string"
            }
          },
          {
            "name": "includeInactive",
            "required": false,
            "in": "query",
            "description": "Include inactive packs in the result. Requires the Organization API key owner to have permission to read inactive packs.",
            "schema": {
              "default": false,
              "example": false,
              "type": "boolean"
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Sort direction by creation date.",
            "schema": {
              "default": "DESC",
              "example": "DESC",
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the packs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedPacksResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "List packs via organization API key",
        "tags": [
          "Organization API Key",
          "Packs"
        ]
      }
    },
    "/external/packs/{id}": {
      "get": {
        "description": "Retrieves a single pack by id, including its attached documents with signed download URLs. The pack must belong to the API key's organization.",
        "operationId": "ExternalApiAgentPacksController_getPackById",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Pack ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the pack.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackWithFilesResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Pack not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get a pack via organization API key",
        "tags": [
          "Organization API Key",
          "Packs"
        ]
      },
      "put": {
        "description": "Updates a pack's name, description, instructions, privacy or status. Provide at least one field. The pack must belong to the API key's organization.",
        "operationId": "ExternalApiAgentPacksController_updatePack",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Pack ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePackBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated the pack.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackWithFilesResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Provide at least one field to update.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Pack not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Update a pack via organization API key",
        "tags": [
          "Organization API Key",
          "Packs"
        ]
      },
      "delete": {
        "description": "Soft-deletes a pack. A pack that is still linked to one or more agents cannot be deleted. The pack must belong to the API key's organization.",
        "operationId": "ExternalApiAgentPacksController_deletePack",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Pack ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully deleted the pack."
          },
          "400": {
            "description": "The pack is still linked to one or more agents.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Pack not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Delete a pack via organization API key",
        "tags": [
          "Organization API Key",
          "Packs"
        ]
      }
    },
    "/external/packs/documents/upload-url": {
      "post": {
        "description": "Creates a time-limited signed URL for uploading a pack document. Upload the file with an HTTP PUT to the returned signedUrl, then attach it to a pack (on create, or via the attach-document endpoint) using the returned storagePath and the file name.",
        "operationId": "ExternalApiAgentPacksController_createDocumentUploadUrl",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePackDocumentUploadUrlBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created the signed upload URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatePackDocumentUploadUrlResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Invalid file name or unsupported content type.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Create a pack document upload URL via organization API key",
        "tags": [
          "Organization API Key",
          "Packs"
        ]
      }
    },
    "/external/packs/{id}/documents": {
      "post": {
        "description": "Attaches a previously uploaded document to a pack. Upload the file to a signed URL first (see the pack document upload-url endpoint), then pass the returned fileName and storagePath. The pack must belong to the API key's organization.",
        "operationId": "ExternalApiAgentPacksController_attachDocument",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Pack ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PackDocumentInputDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully attached the document to the pack.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackWithFilesResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Pack not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Attach a document to a pack via organization API key",
        "tags": [
          "Organization API Key",
          "Packs"
        ]
      }
    },
    "/external/packs/{id}/documents/{fileId}": {
      "delete": {
        "description": "Removes a document from a pack by its file id. The pack must belong to the API key's organization.",
        "operationId": "ExternalApiAgentPacksController_removeDocument",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Pack ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "fileId",
            "required": true,
            "in": "path",
            "description": "Document (file) ID to remove from the pack.",
            "schema": {
              "format": "uuid",
              "example": "6a8c2c4c-4c4c-5c4c-4c4c-4c4c4c4c4c4c",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully removed the document from the pack.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackWithFilesResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Pack not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Remove a document from a pack via organization API key",
        "tags": [
          "Organization API Key",
          "Packs"
        ]
      }
    },
    "/external/packs/{id}/link/{agentId}": {
      "post": {
        "description": "Links a pack to an agent, copying the pack's shared instructions and documents onto the agent. The pack and agent must both belong to the organization resolved from the Organization API key.",
        "operationId": "ExternalApiAgentPacksController_linkPackToAgent",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Pack ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "agentId",
            "required": true,
            "in": "path",
            "description": "Agent ID.",
            "schema": {
              "format": "uuid",
              "example": "6a8c2c4c-4c4c-5c4c-4c4c-4c4c4c4c4c4c",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully linked the pack to the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LinkPackToAgentResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Pack or agent not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Link a pack to an agent",
        "tags": [
          "Organization API Key",
          "Packs",
          "Agents"
        ]
      },
      "delete": {
        "description": "Removes the link between a pack and an agent. The pack and agent must both belong to the organization resolved from the Organization API key.",
        "operationId": "ExternalApiAgentPacksController_unlinkPackFromAgent",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Pack ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "agentId",
            "required": true,
            "in": "path",
            "description": "Agent ID.",
            "schema": {
              "format": "uuid",
              "example": "6a8c2c4c-4c4c-5c4c-4c4c-4c4c4c4c4c4c",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully unlinked the pack from the agent."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Pack or agent not found, or the pack is not linked to the agent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Unlink a pack from an agent",
        "tags": [
          "Organization API Key",
          "Packs",
          "Agents"
        ]
      }
    },
    "/external/functions": {
      "post": {
        "description": "Creates a function in the organization resolved from the Organization API key, owned by the supplied userId. Set isPrivate to true to make the function private to that user (\"only for me\"); set it to false to make it available to the whole organization. The owner must be a member of the organization and have permission to create functions.",
        "operationId": "ExternalApiFunctionsController_createFunction",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateFunctionBodyDTO"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully created the function.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FunctionResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Owner user not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Create a function via organization API key",
        "tags": [
          "Organization API Key",
          "Functions"
        ]
      },
      "get": {
        "description": "Retrieves a paginated list of the functions visible to the supplied userId: the organization's shared functions plus that user's own private functions. Optionally filter by name and include inactive functions.",
        "operationId": "ExternalApiFunctionsController_getFunctions",
        "parameters": [
          {
            "name": "userId",
            "required": true,
            "in": "query",
            "description": "ID of the organization member whose visible functions are listed (their private functions plus the organization-wide ones). Must belong to the API key organization.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "page",
            "required": false,
            "in": "query",
            "schema": {
              "default": 0,
              "example": 0,
              "type": "number"
            }
          },
          {
            "name": "pageSize",
            "required": false,
            "in": "query",
            "schema": {
              "default": 10,
              "example": 10,
              "type": "number"
            }
          },
          {
            "name": "searchKeyword",
            "required": false,
            "in": "query",
            "description": "Filter functions whose name contains this keyword.",
            "schema": {
              "example": "order",
              "type": "string"
            }
          },
          {
            "name": "includeInactive",
            "required": false,
            "in": "query",
            "description": "Include inactive functions. Requires the acting user to have permission to read inactive functions.",
            "schema": {
              "default": false,
              "example": false,
              "type": "boolean"
            }
          },
          {
            "name": "orderDirection",
            "required": false,
            "in": "query",
            "description": "Sort direction by creation date.",
            "schema": {
              "default": "DESC",
              "example": "DESC",
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the functions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedFunctionsResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "User not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "List functions via organization API key",
        "tags": [
          "Organization API Key",
          "Functions"
        ]
      }
    },
    "/external/functions/{id}": {
      "get": {
        "description": "Retrieves a single function by id, as seen by the supplied userId. The function must belong to the API key's organization and be visible to that user.",
        "operationId": "ExternalApiFunctionsController_getFunctionById",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Function ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "userId",
            "required": true,
            "in": "query",
            "description": "ID of the organization member acting on the function. Must belong to the API key organization.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the function.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FunctionResponseDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Function or user not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Get a function via organization API key",
        "tags": [
          "Organization API Key",
          "Functions"
        ]
      },
      "patch": {
        "description": "Updates a function on behalf of the supplied userId. Provide at least one field to change. Only the owner can change a private function or toggle its privacy. The function must belong to the API key's organization.",
        "operationId": "ExternalApiFunctionsController_updateFunction",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Function ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateFunctionBodyDTO"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully updated the function.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FunctionResponseDTO"
                }
              }
            }
          },
          "400": {
            "description": "Provide at least one field to update.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BadRequestErrorDTO"
                }
              }
            }
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Function or user not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Update a function via organization API key",
        "tags": [
          "Organization API Key",
          "Functions"
        ]
      },
      "delete": {
        "description": "Deletes a function on behalf of the supplied userId. Only the owner can delete a private function. The function must belong to the API key's organization.",
        "operationId": "ExternalApiFunctionsController_deleteFunction",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Function ID.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          },
          {
            "name": "userId",
            "required": true,
            "in": "query",
            "description": "ID of the organization member acting on the function. Must belong to the API key organization.",
            "schema": {
              "format": "uuid",
              "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successfully deleted the function."
          },
          "403": {
            "description": "Invalid API key or secret key. Ensure that you are using a valid authentication key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ForbiddenErrorDTO"
                }
              }
            }
          },
          "404": {
            "description": "Function or user not found in the current organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntityNotFoundErrorDTO"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."
          },
          "500": {
            "description": "Unexpected error occurred while processing the request. Please try again later.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InternalServerErrorDTO"
                }
              }
            }
          }
        },
        "security": [
          {
            "Organization-Secret-Key": []
          }
        ],
        "summary": "Delete a function via organization API key",
        "tags": [
          "Organization API Key",
          "Functions"
        ]
      }
    }
  },
  "info": {
    "title": "AI Agent API",
    "description": "API for creating users, conversations, and sending messages",
    "version": "1.0.0",
    "contact": {}
  },
  "tags": [],
  "servers": [
    {
      "url": "https://api.raia2.com",
      "description": "Production server"
    }
  ],
  "components": {
    "securitySchemes": {
      "Agent-Secret-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "Agent-Secret-Key",
        "description": "Custom authentication header"
      },
      "Organization-Secret-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "Organization-Secret-Key",
        "description": "Custom authentication header"
      },
      "Super-Admin-Secret-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "Super-Admin-Secret-Key",
        "description": "Custom authentication header"
      }
    },
    "schemas": {
      "ForbiddenErrorDTO": {
        "type": "object",
        "properties": {
          "status": {
            "type": "number",
            "default": 403
          },
          "name": {
            "type": "object",
            "default": "FORBIDDEN_ERROR"
          },
          "message": {
            "type": "string",
            "default": "INVALID_CREDENTIALS"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "status",
          "name",
          "message",
          "details"
        ]
      },
      "InternalServerErrorDTO": {
        "type": "object",
        "properties": {
          "status": {
            "type": "number",
            "default": 500
          },
          "message": {
            "type": "string",
            "default": "Internal Server Error"
          }
        },
        "required": [
          "status",
          "message"
        ]
      },
      "CreateUserWithPhoneNumberBodyDTO": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "User first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "User last name",
            "example": "Doe"
          },
          "context": {
            "type": "string",
            "description": "User context",
            "example": "Support"
          },
          "source": {
            "type": "string",
            "description": "User source",
            "example": "webchat"
          },
          "fkUserId": {
            "type": "string",
            "description": "User fkUserId",
            "example": "123456"
          },
          "customData": {
            "type": "object",
            "description": "Conversation user custom data",
            "example": {
              "key1": "value1",
              "key2": "value2"
            }
          },
          "skipPhoneNumberValidation": {
            "type": "boolean",
            "description": "Skip phone number validation",
            "example": false
          },
          "skipEmailValidation": {
            "type": "boolean",
            "description": "Skip email validation",
            "example": false
          },
          "phoneNumber": {
            "type": "string",
            "description": "User phone number",
            "example": "+1234567890"
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "test@test.com"
          },
          "fkId": {
            "type": "string",
            "description": "User fkId",
            "example": "123456"
          }
        },
        "required": [
          "firstName",
          "lastName",
          "phoneNumber"
        ]
      },
      "CreateUserWithEmailBodyDTO": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "User first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "User last name",
            "example": "Doe"
          },
          "context": {
            "type": "string",
            "description": "User context",
            "example": "Support"
          },
          "source": {
            "type": "string",
            "description": "User source",
            "example": "webchat"
          },
          "fkUserId": {
            "type": "string",
            "description": "User fkUserId",
            "example": "123456"
          },
          "customData": {
            "type": "object",
            "description": "Conversation user custom data",
            "example": {
              "key1": "value1",
              "key2": "value2"
            }
          },
          "skipPhoneNumberValidation": {
            "type": "boolean",
            "description": "Skip phone number validation",
            "example": false
          },
          "skipEmailValidation": {
            "type": "boolean",
            "description": "Skip email validation",
            "example": false
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "test@test.com"
          },
          "phoneNumber": {
            "type": "string",
            "description": "User phone number",
            "example": "+1234567890"
          },
          "fkId": {
            "type": "string",
            "description": "User fkId",
            "example": "123456"
          }
        },
        "required": [
          "firstName",
          "lastName",
          "email"
        ]
      },
      "CreateUserWithFkIdBodyDTO": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "User first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "User last name",
            "example": "Doe"
          },
          "context": {
            "type": "string",
            "description": "User context",
            "example": "Support"
          },
          "source": {
            "type": "string",
            "description": "User source",
            "example": "webchat"
          },
          "fkUserId": {
            "type": "string",
            "description": "User fkUserId",
            "example": "123456"
          },
          "customData": {
            "type": "object",
            "description": "Conversation user custom data",
            "example": {
              "key1": "value1",
              "key2": "value2"
            }
          },
          "skipPhoneNumberValidation": {
            "type": "boolean",
            "description": "Skip phone number validation",
            "example": false
          },
          "skipEmailValidation": {
            "type": "boolean",
            "description": "Skip email validation",
            "example": false
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "test@test.com"
          },
          "phoneNumber": {
            "type": "string",
            "description": "User phone number",
            "example": "+1234567890"
          },
          "fkId": {
            "type": "string",
            "description": "User fkId",
            "example": "123456"
          }
        },
        "required": [
          "firstName",
          "lastName",
          "fkId"
        ]
      },
      "ExternalApiUserResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "firstName": {
            "type": "string",
            "description": "User first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "User last name",
            "example": "Doe"
          },
          "context": {
            "type": "string",
            "description": "User context",
            "example": "Support"
          },
          "source": {
            "type": "string",
            "description": "User source",
            "example": "webchat"
          },
          "fkId": {
            "type": "string",
            "description": "User fkId",
            "example": "123456"
          },
          "fkUserId": {
            "type": "string",
            "description": "User fkUserId",
            "example": "123456"
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "test@test.com"
          },
          "phoneNumber": {
            "type": "string",
            "description": "User phone number",
            "example": "+1234567890"
          },
          "metadata": {
            "type": "object",
            "description": "Conversation user metadata",
            "example": {
              "customData": {
                "key1": "value1",
                "key2": "value2"
              }
            }
          },
          "isAnonymized": {
            "type": "boolean",
            "description": "Is anonymized",
            "example": false
          }
        },
        "required": [
          "id",
          "firstName",
          "lastName",
          "isAnonymized"
        ]
      },
      "BadRequestErrorDTO": {
        "type": "object",
        "properties": {
          "status": {
            "type": "number",
            "default": 500
          },
          "name": {
            "type": "object",
            "default": "BAD_REQUEST"
          },
          "message": {
            "type": "string",
            "default": "INVALID_REQUEST"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "status",
          "name",
          "message",
          "details"
        ]
      },
      "SearchConversationUserByContactsResponseDTO": {
        "type": "object",
        "properties": {
          "user": {
            "description": "User info",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiUserResponseDTO"
              }
            ]
          },
          "conversationIds": {
            "description": "Conversation ids",
            "example": [
              "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
              "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "user",
          "conversationIds"
        ]
      },
      "EntityNotFoundErrorDTO": {
        "type": "object",
        "properties": {
          "status": {
            "type": "number",
            "default": 404
          },
          "name": {
            "type": "object",
            "default": "ENTITY_NOT_FOUND_ERROR"
          },
          "message": {
            "type": "string",
            "default": "ENTITY_NOT_FOUND"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "status",
          "name",
          "message",
          "details"
        ]
      },
      "ConversationUserLimitsResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Conversation user limits ID"
          },
          "conversationUserId": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Conversation user ID"
          },
          "isOrganizationDefault": {
            "type": "boolean",
            "example": true,
            "description": "Is organization default"
          },
          "tokensAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Tokens amount per month"
          },
          "smsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "SMS amount per month"
          },
          "emailsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Emails amount per month"
          },
          "secondsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Seconds amount per month"
          }
        },
        "required": [
          "id",
          "conversationUserId",
          "isOrganizationDefault",
          "tokensAmountPerMonth",
          "smsAmountPerMonth",
          "emailsAmountPerMonth",
          "secondsAmountPerMonth"
        ]
      },
      "CreateConversationUserLimitsBodyDTO": {
        "type": "object",
        "properties": {
          "tokensAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Tokens amount per month"
          },
          "smsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "SMS amount per month"
          },
          "emailsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Emails amount per month"
          },
          "secondsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Seconds amount per month"
          }
        },
        "required": [
          "tokensAmountPerMonth",
          "smsAmountPerMonth",
          "emailsAmountPerMonth",
          "secondsAmountPerMonth"
        ]
      },
      "UpdateConversationUserLimitsBodyDTO": {
        "type": "object",
        "properties": {
          "tokensAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Tokens amount per month"
          },
          "smsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "SMS amount per month"
          },
          "emailsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Emails amount per month"
          },
          "secondsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Seconds amount per month"
          }
        },
        "required": [
          "tokensAmountPerMonth",
          "smsAmountPerMonth",
          "emailsAmountPerMonth",
          "secondsAmountPerMonth"
        ]
      },
      "StartEmailConversationBodyDTO": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Conversation user first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "Conversation user last name",
            "example": "Doe"
          },
          "context": {
            "type": "string",
            "description": "Conversation user context",
            "example": "Support"
          },
          "conversationContext": {
            "type": "string",
            "description": "Conversation context",
            "example": "Support"
          },
          "source": {
            "type": "string",
            "description": "Conversation user source",
            "example": "webchat"
          },
          "fkId": {
            "type": "string",
            "description": "Conversation user fkId",
            "example": "123456"
          },
          "fkUserId": {
            "type": "string",
            "description": "Conversation user fkUserId",
            "example": "123456"
          },
          "customData": {
            "type": "object",
            "description": "Conversation custom data",
            "example": {
              "key1": "value1",
              "key2": "value2"
            }
          },
          "conversationStateId": {
            "type": "string",
            "description": "Conversation state ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "authorId": {
            "type": "string",
            "description": "Author platform ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "skipPhoneNumberValidation": {
            "type": "boolean",
            "description": "Skip phone number validation",
            "example": false
          },
          "skipEmailValidation": {
            "type": "boolean",
            "description": "Skip email validation",
            "example": false
          },
          "channel": {
            "type": "string",
            "description": "Conversation user preferred channel",
            "example": "email",
            "enum": [
              "email"
            ]
          },
          "email": {
            "type": "string",
            "description": "Conversation user email",
            "example": "test@test.com"
          },
          "emailSubject": {
            "type": "string",
            "description": "Conversation user email subject",
            "example": "New Conversation"
          },
          "emailIntroduction": {
            "type": "string",
            "description": "Conversation user email introduction",
            "example": "New Conversation"
          },
          "includeSignatureInEmail": {
            "type": "boolean",
            "description": "Include email signature in the email",
            "example": false
          },
          "phoneNumber": {
            "type": "string",
            "description": "User phone number",
            "example": "+1234567890"
          },
          "resetConversation": {
            "type": "boolean",
            "description": "Archive current conversation and launch a new one",
            "default": false
          }
        },
        "required": [
          "firstName",
          "lastName",
          "channel",
          "email",
          "emailSubject",
          "emailIntroduction"
        ]
      },
      "StartSmsConversationBodyDTO": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Conversation user first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "Conversation user last name",
            "example": "Doe"
          },
          "context": {
            "type": "string",
            "description": "Conversation user context",
            "example": "Support"
          },
          "conversationContext": {
            "type": "string",
            "description": "Conversation context",
            "example": "Support"
          },
          "source": {
            "type": "string",
            "description": "Conversation user source",
            "example": "webchat"
          },
          "fkId": {
            "type": "string",
            "description": "Conversation user fkId",
            "example": "123456"
          },
          "fkUserId": {
            "type": "string",
            "description": "Conversation user fkUserId",
            "example": "123456"
          },
          "customData": {
            "type": "object",
            "description": "Conversation custom data",
            "example": {
              "key1": "value1",
              "key2": "value2"
            }
          },
          "conversationStateId": {
            "type": "string",
            "description": "Conversation state ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "authorId": {
            "type": "string",
            "description": "Author platform ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "skipPhoneNumberValidation": {
            "type": "boolean",
            "description": "Skip phone number validation",
            "example": false
          },
          "skipEmailValidation": {
            "type": "boolean",
            "description": "Skip email validation",
            "example": false
          },
          "channel": {
            "type": "string",
            "description": "Conversation user preferred channel",
            "example": "sms",
            "enum": [
              "sms"
            ]
          },
          "phoneNumber": {
            "type": "string",
            "description": "Conversation user phone number",
            "example": "+1234567890"
          },
          "smsIntroduction": {
            "type": "string",
            "description": "Conversation user sms introduction",
            "example": "New Conversation"
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "test@test.com"
          },
          "resetConversation": {
            "type": "boolean",
            "description": "Archive current conversation and launch a new one",
            "default": false
          },
          "includeSignatureInSms": {
            "type": "boolean",
            "description": "Include signature in SMS",
            "default": false
          }
        },
        "required": [
          "firstName",
          "lastName",
          "channel",
          "phoneNumber",
          "smsIntroduction"
        ]
      },
      "StartVoiceConversationBodyDTO": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "Conversation user first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "Conversation user last name",
            "example": "Doe"
          },
          "context": {
            "type": "string",
            "description": "Conversation user context",
            "example": "Support"
          },
          "conversationContext": {
            "type": "string",
            "description": "Conversation context",
            "example": "Support"
          },
          "source": {
            "type": "string",
            "description": "Conversation user source",
            "example": "webchat"
          },
          "fkId": {
            "type": "string",
            "description": "Conversation user fkId",
            "example": "123456"
          },
          "fkUserId": {
            "type": "string",
            "description": "Conversation user fkUserId",
            "example": "123456"
          },
          "customData": {
            "type": "object",
            "description": "Conversation custom data",
            "example": {
              "key1": "value1",
              "key2": "value2"
            }
          },
          "conversationStateId": {
            "type": "string",
            "description": "Conversation state ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "authorId": {
            "type": "string",
            "description": "Author platform ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "skipPhoneNumberValidation": {
            "type": "boolean",
            "description": "Skip phone number validation",
            "example": false
          },
          "skipEmailValidation": {
            "type": "boolean",
            "description": "Skip email validation",
            "example": false
          },
          "channel": {
            "type": "string",
            "description": "Conversation user preferred channel",
            "example": "voice",
            "enum": [
              "voice"
            ]
          },
          "phoneNumber": {
            "type": "string",
            "description": "Conversation user phone number",
            "example": "+1234567890"
          },
          "firstMessage": {
            "type": "string",
            "description": "Assistant first message",
            "example": "Hello, how can I help you?"
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "test@test.com"
          }
        },
        "required": [
          "firstName",
          "lastName",
          "channel",
          "phoneNumber",
          "firstMessage"
        ]
      },
      "AssignedUserResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Assigned user ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "firstName": {
            "type": "string",
            "description": "Assigned user first name",
            "example": "Jane"
          },
          "lastName": {
            "type": "string",
            "description": "Assigned user last name",
            "example": "Doe"
          },
          "avatarUrl": {
            "type": "string",
            "description": "Assigned user avatar URL",
            "nullable": true
          },
          "email": {
            "type": "string",
            "description": "Assigned user email",
            "example": "jane.doe@example.com"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Assigned user phone number",
            "nullable": true
          }
        },
        "required": [
          "id",
          "firstName",
          "lastName",
          "email"
        ]
      },
      "FeedbackResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Feedback ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "voteType": {
            "type": "string",
            "description": "Feedback vote type",
            "example": "down",
            "enum": [
              "up",
              "down"
            ]
          },
          "question": {
            "type": "string",
            "description": "Feedback question",
            "nullable": true
          },
          "answer": {
            "type": "string",
            "description": "Feedback answer",
            "nullable": true
          },
          "comment": {
            "type": "string",
            "description": "Feedback comment",
            "nullable": true
          },
          "userEmail": {
            "type": "string",
            "description": "Email of the user who provided the feedback",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "description": "Feedback created at",
            "example": "2023-01-01T00:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "description": "Feedback updated at",
            "example": "2023-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "id",
          "voteType",
          "question",
          "answer",
          "comment",
          "createdAt",
          "updatedAt"
        ]
      },
      "ConversationWithFeedbacksResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "New conversation ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "conversationUserId": {
            "type": "string",
            "description": "Conversation user ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "title": {
            "type": "string",
            "description": "Conversation title",
            "example": "Conversation Title"
          },
          "score": {
            "type": "number",
            "description": "Conversation score",
            "example": 4
          },
          "summary": {
            "type": "string",
            "description": "Conversation summary",
            "example": "This is a summary of the conversation."
          },
          "analysisStatus": {
            "type": "string",
            "enum": [
              "not_started",
              "processing",
              "skipped_skill_disabled",
              "completed",
              "failed"
            ],
            "description": "Conversation analysis status",
            "example": "completed"
          },
          "analyzedAt": {
            "type": "string",
            "description": "Date the conversation analysis completed",
            "example": "2023-10-01T12:00:00Z",
            "format": "date-time",
            "nullable": true
          },
          "metadata": {
            "type": "object",
            "description": "Conversation metadata",
            "example": {
              "customData": {
                "key1": "value1",
                "key2": "value2"
              }
            }
          },
          "aiCallId": {
            "type": "string",
            "description": "AI call ID",
            "example": "call_h435hi34h5i43i5"
          },
          "mode": {
            "type": "string",
            "description": "Conversation mode",
            "example": "manual",
            "enum": [
              "manual",
              "ai"
            ]
          },
          "conversationStateId": {
            "type": "string",
            "description": "Conversation state ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "user": {
            "description": "Conversation user",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiUserResponseDTO"
              }
            ]
          },
          "createdAt": {
            "type": "string",
            "example": "2023-10-01T12:00:00Z",
            "description": "Date the conversation was created",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "example": "2023-10-01T12:00:00Z",
            "description": "Date the conversation was updated",
            "format": "date-time"
          },
          "assignedUser": {
            "description": "User the conversation is assigned to",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/AssignedUserResponseDTO"
              }
            ]
          },
          "isAnonymized": {
            "type": "boolean",
            "description": "Is anonymized",
            "example": false
          },
          "feedbacks": {
            "description": "Conversation feedbacks",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeedbackResponseDTO"
            }
          }
        },
        "required": [
          "id",
          "conversationUserId",
          "analysisStatus",
          "analyzedAt",
          "user",
          "createdAt",
          "updatedAt",
          "isAnonymized"
        ]
      },
      "GetConversationWithFeedbacksResponseDTO": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "number",
            "description": "Current page"
          },
          "pageSize": {
            "type": "number",
            "description": "Page size"
          },
          "totalItems": {
            "type": "number",
            "description": "Total items"
          },
          "totalPages": {
            "type": "number",
            "description": "Total pages"
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Has next page"
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Has previous page"
          },
          "data": {
            "description": "List of conversations",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationWithFeedbacksResponseDTO"
            }
          }
        },
        "required": [
          "currentPage",
          "pageSize",
          "totalItems",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage",
          "data"
        ]
      },
      "ExternalApiGetConversationStateResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Conversation state ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Conversation state name"
          },
          "description": {
            "type": "string",
            "description": "Conversation state description",
            "nullable": true
          },
          "color": {
            "type": "string",
            "description": "Conversation state color hex",
            "nullable": true
          },
          "isPersistent": {
            "type": "boolean",
            "description": "True if conversation state is persistent"
          },
          "createdAt": {
            "type": "string",
            "description": "Conversation state created at",
            "example": "2023-01-01T00:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "description": "Conversation state created at",
            "example": "2023-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "color",
          "isPersistent",
          "createdAt",
          "updatedAt"
        ]
      },
      "StartConversationResponseDTO": {
        "type": "object",
        "properties": {
          "conversationId": {
            "type": "string",
            "description": "New conversation ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          }
        },
        "required": [
          "conversationId"
        ]
      },
      "BaseFeedbackResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Feedback ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "voteType": {
            "type": "string",
            "description": "Feedback vote type",
            "example": "down",
            "enum": [
              "up",
              "down"
            ]
          },
          "question": {
            "type": "string",
            "description": "Feedback question",
            "nullable": true
          },
          "answer": {
            "type": "string",
            "description": "Feedback answer",
            "nullable": true
          },
          "comment": {
            "type": "string",
            "description": "Feedback comment",
            "nullable": true
          },
          "userEmail": {
            "type": "string",
            "description": "Email of the user who provided the feedback",
            "nullable": true
          }
        },
        "required": [
          "id",
          "voteType",
          "question",
          "answer",
          "comment"
        ]
      },
      "UrlCitationDTO": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "URL",
            "example": "https://example.com"
          },
          "title": {
            "type": "string",
            "description": "Title",
            "example": "Example"
          }
        },
        "required": [
          "url",
          "title"
        ]
      },
      "FileCitationDTO": {
        "type": "object",
        "properties": {
          "fileId": {
            "type": "string",
            "description": "File ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "filename": {
            "type": "string",
            "description": "Filename",
            "example": "example.txt"
          }
        },
        "required": [
          "fileId",
          "filename"
        ]
      },
      "FullAIResponseDTO": {
        "type": "object",
        "properties": {
          "reasoning": {
            "description": "Reasoning summaries",
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "outputText": {
            "type": "string",
            "description": "Output text",
            "nullable": true
          },
          "urlCitations": {
            "description": "URL citations",
            "nullable": true,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UrlCitationDTO"
            }
          },
          "fileCitations": {
            "description": "File citations",
            "nullable": true,
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FileCitationDTO"
            }
          }
        }
      },
      "ConversationMessageModelUsageResponseDTO": {
        "type": "object",
        "properties": {
          "totalTokens": {
            "type": "number",
            "description": "Total tokens used for this AI response"
          },
          "inputTokens": {
            "type": "number",
            "description": "Input tokens used for this AI response"
          },
          "outputTokens": {
            "type": "number",
            "description": "Output tokens used for this AI response"
          },
          "reasoningTokens": {
            "type": "number",
            "description": "Reasoning tokens included in the output token count"
          },
          "modelProvider": {
            "type": "string",
            "nullable": true,
            "description": "Provider of the last model used"
          },
          "model": {
            "type": "string",
            "nullable": true,
            "description": "Last model used"
          },
          "reasoningEffort": {
            "type": "string",
            "nullable": true,
            "description": "Reasoning effort of the last model used"
          },
          "reasoningMode": {
            "type": "string",
            "nullable": true,
            "description": "Reasoning mode of the last model used"
          }
        },
        "required": [
          "totalTokens",
          "inputTokens",
          "outputTokens",
          "reasoningTokens",
          "modelProvider",
          "model",
          "reasoningEffort",
          "reasoningMode"
        ]
      },
      "ConversationMessageUsedFunctionResponseDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Function name"
          },
          "publicName": {
            "type": "string",
            "description": "Function display name"
          }
        },
        "required": [
          "name",
          "publicName"
        ]
      },
      "ConversationMessageFileResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "File ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "fileName": {
            "type": "string",
            "description": "File name",
            "example": "example.txt"
          },
          "openAIFileId": {
            "type": "string",
            "nullable": true,
            "description": "OpenAI file ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "size": {
            "type": "number",
            "description": "File size",
            "nullable": true,
            "example": 1024
          },
          "source": {
            "type": "string",
            "enum": [
              "user",
              "model"
            ],
            "description": "How the file was added to the conversation message",
            "example": "user"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Updated at",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Created at",
            "example": "2025-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "id",
          "fileName",
          "openAIFileId",
          "source",
          "updatedAt",
          "createdAt"
        ]
      },
      "ConversationMessageResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Conversation message ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "message": {
            "type": "string",
            "description": "Conversation message content",
            "example": "Hello, how can I help you?"
          },
          "rawMessage": {
            "type": "string",
            "description": "Raw message content",
            "example": "Raw message example"
          },
          "conversationId": {
            "type": "string",
            "description": "Conversation ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "senderRole": {
            "type": "string",
            "enum": [
              "conversation_user",
              "assistant",
              "manual_assistant"
            ],
            "description": "Sender role in the conversation",
            "example": "conversation_user"
          },
          "conversationMessageId": {
            "type": "string",
            "description": "Question message ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "source": {
            "type": "string",
            "enum": [
              "email",
              "sms",
              "live_chat",
              "copilot",
              "api",
              "voice",
              "slack",
              "ms_teams"
            ],
            "description": "Conversation source",
            "example": "api"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Message create date",
            "example": "2022-01-01T00:00:00.000Z"
          },
          "conversationMessageFeedbacks": {
            "description": "List of conversation message feedbacks",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BaseFeedbackResponseDTO"
            }
          },
          "fullAIResponse": {
            "description": "Full AI response",
            "allOf": [
              {
                "$ref": "#/components/schemas/FullAIResponseDTO"
              }
            ]
          },
          "modelUsage": {
            "nullable": true,
            "description": "Token usage for this AI response, aggregated across its model calls. Model metadata describes the last model used. Null for messages without recorded usage.",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ConversationMessageModelUsageResponseDTO"
              }
            ]
          },
          "usedFunctions": {
            "nullable": true,
            "description": "Functions called while generating this assistant message. Execution status is not included.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationMessageUsedFunctionResponseDTO"
            }
          },
          "subagentId": {
            "type": "string",
            "nullable": true,
            "description": "Subagent selected by automatic orchestration for this assistant message."
          },
          "expandedMessage": {
            "type": "string",
            "nullable": true,
            "description": "Expanded version of the message produced by Enhanced Prompting, if the skill is attached to the agent. Null when the skill is not attached or expansion was skipped."
          },
          "files": {
            "description": "Conversation message files",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationMessageFileResponseDTO"
            }
          },
          "isAnonymized": {
            "type": "boolean",
            "description": "Is anonymized",
            "example": false
          }
        },
        "required": [
          "id",
          "message",
          "conversationId",
          "senderRole",
          "conversationMessageId",
          "source",
          "createdAt",
          "isAnonymized"
        ]
      },
      "GetConversationMessagesResponseDTO": {
        "type": "object",
        "properties": {
          "messages": {
            "description": "List of conversation messages",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationMessageResponseDTO"
            }
          }
        },
        "required": [
          "messages"
        ]
      },
      "MessageFileBodyDTO": {
        "type": "object",
        "properties": {
          "fileName": {
            "type": "string",
            "description": "File name",
            "example": "test.png"
          },
          "storagePath": {
            "type": "string",
            "description": "Storage path",
            "example": "conversations/conv_h435hi34h5i43i5/test.png"
          }
        },
        "required": [
          "fileName",
          "storagePath"
        ]
      },
      "SendMessageBodyDTO": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The message that the user sends to the AI agent",
            "example": "How does quantum entanglement work?"
          },
          "context": {
            "type": "string",
            "description": "Context of the message",
            "example": "User is asking about quantum physics."
          },
          "files": {
            "description": "Files attached to the message",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessageFileBodyDTO"
            }
          }
        },
        "required": [
          "message"
        ]
      },
      "SendMessageResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Conversation message ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "message": {
            "type": "string",
            "description": "Conversation message content",
            "example": "Hello, how can I help you?"
          },
          "rawMessage": {
            "type": "string",
            "description": "Raw message content",
            "example": "Raw message example"
          },
          "conversationId": {
            "type": "string",
            "description": "Conversation ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "senderRole": {
            "type": "string",
            "enum": [
              "conversation_user",
              "assistant",
              "manual_assistant"
            ],
            "description": "Sender role in the conversation",
            "example": "conversation_user"
          },
          "conversationMessageId": {
            "type": "string",
            "description": "Question message ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "source": {
            "type": "string",
            "enum": [
              "email",
              "sms",
              "live_chat",
              "copilot",
              "api",
              "voice",
              "slack",
              "ms_teams"
            ],
            "description": "Conversation source",
            "example": "api"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Message create date",
            "example": "2022-01-01T00:00:00.000Z"
          },
          "conversationMessageFeedbacks": {
            "description": "List of conversation message feedbacks",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BaseFeedbackResponseDTO"
            }
          },
          "fullAIResponse": {
            "description": "Full AI response",
            "allOf": [
              {
                "$ref": "#/components/schemas/FullAIResponseDTO"
              }
            ]
          },
          "modelUsage": {
            "nullable": true,
            "description": "Token usage for this AI response, aggregated across its model calls. Model metadata describes the last model used. Null for messages without recorded usage.",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ConversationMessageModelUsageResponseDTO"
              }
            ]
          },
          "usedFunctions": {
            "nullable": true,
            "description": "Functions called while generating this assistant message. Execution status is not included.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationMessageUsedFunctionResponseDTO"
            }
          },
          "subagentId": {
            "type": "string",
            "nullable": true,
            "description": "Subagent selected by automatic orchestration for this assistant message."
          },
          "expandedMessage": {
            "type": "string",
            "nullable": true,
            "description": "Expanded version of the message produced by Enhanced Prompting, if the skill is attached to the agent. Null when the skill is not attached or expansion was skipped."
          },
          "files": {
            "description": "Conversation message files",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationMessageFileResponseDTO"
            }
          },
          "isAnonymized": {
            "type": "boolean",
            "description": "Is anonymized",
            "example": false
          }
        },
        "required": [
          "id",
          "message",
          "conversationId",
          "senderRole",
          "conversationMessageId",
          "source",
          "createdAt",
          "isAnonymized"
        ]
      },
      "GetResponseOnResponseDTO": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ],
            "description": "Response status",
            "example": "completed"
          },
          "message": {
            "description": "Response message",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ConversationMessageResponseDTO"
              }
            ]
          },
          "error": {
            "type": "string",
            "description": "Response error",
            "nullable": true
          }
        },
        "required": [
          "status",
          "message",
          "error"
        ]
      },
      "CreateConversationBodyDTO": {
        "type": "object",
        "properties": {
          "conversationUserId": {
            "type": "string",
            "description": "Conversation user ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "title": {
            "type": "string",
            "description": "Conversation title",
            "example": "New Conversation Title",
            "maxLength": 255
          },
          "context": {
            "type": "string",
            "description": "Conversation context",
            "example": "New conversation context",
            "maxLength": 256000
          },
          "customData": {
            "type": "object",
            "description": "Conversation custom data",
            "example": {
              "key1": "value1",
              "key2": "value2"
            }
          },
          "conversationStateId": {
            "type": "string",
            "description": "Conversation state ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          }
        },
        "required": [
          "conversationUserId"
        ]
      },
      "ConversationResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "New conversation ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "conversationUserId": {
            "type": "string",
            "description": "Conversation user ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "title": {
            "type": "string",
            "description": "Conversation title",
            "example": "Conversation Title"
          },
          "score": {
            "type": "number",
            "description": "Conversation score",
            "example": 4
          },
          "summary": {
            "type": "string",
            "description": "Conversation summary",
            "example": "This is a summary of the conversation."
          },
          "analysisStatus": {
            "type": "string",
            "enum": [
              "not_started",
              "processing",
              "skipped_skill_disabled",
              "completed",
              "failed"
            ],
            "description": "Conversation analysis status",
            "example": "completed"
          },
          "analyzedAt": {
            "type": "string",
            "description": "Date the conversation analysis completed",
            "example": "2023-10-01T12:00:00Z",
            "format": "date-time",
            "nullable": true
          },
          "metadata": {
            "type": "object",
            "description": "Conversation metadata",
            "example": {
              "customData": {
                "key1": "value1",
                "key2": "value2"
              }
            }
          },
          "aiCallId": {
            "type": "string",
            "description": "AI call ID",
            "example": "call_h435hi34h5i43i5"
          },
          "mode": {
            "type": "string",
            "description": "Conversation mode",
            "example": "manual",
            "enum": [
              "manual",
              "ai"
            ]
          },
          "conversationStateId": {
            "type": "string",
            "description": "Conversation state ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "user": {
            "description": "Conversation user",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiUserResponseDTO"
              }
            ]
          },
          "createdAt": {
            "type": "string",
            "example": "2023-10-01T12:00:00Z",
            "description": "Date the conversation was created",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "example": "2023-10-01T12:00:00Z",
            "description": "Date the conversation was updated",
            "format": "date-time"
          },
          "assignedUser": {
            "description": "User the conversation is assigned to",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/AssignedUserResponseDTO"
              }
            ]
          },
          "isAnonymized": {
            "type": "boolean",
            "description": "Is anonymized",
            "example": false
          }
        },
        "required": [
          "id",
          "conversationUserId",
          "analysisStatus",
          "analyzedAt",
          "user",
          "createdAt",
          "updatedAt",
          "isAnonymized"
        ]
      },
      "ProcessMessageBodyDTO": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The message that the user sends to the AI agent",
            "example": "How does quantum entanglement work?"
          },
          "context": {
            "type": "string",
            "description": "Context of the message",
            "example": "User is asking about quantum physics."
          },
          "files": {
            "description": "Files attached to the message",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessageFileBodyDTO"
            }
          }
        },
        "required": [
          "message"
        ]
      },
      "ProcessMessageResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Conversation message ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "message": {
            "type": "string",
            "description": "Conversation message content",
            "example": "Hello, how can I help you?"
          },
          "rawMessage": {
            "type": "string",
            "description": "Raw message content",
            "example": "Raw message example"
          },
          "conversationId": {
            "type": "string",
            "description": "Conversation ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "senderRole": {
            "type": "string",
            "enum": [
              "conversation_user",
              "assistant",
              "manual_assistant"
            ],
            "description": "Sender role in the conversation",
            "example": "conversation_user"
          },
          "conversationMessageId": {
            "type": "string",
            "description": "Question message ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "source": {
            "type": "string",
            "enum": [
              "email",
              "sms",
              "live_chat",
              "copilot",
              "api",
              "voice",
              "slack",
              "ms_teams"
            ],
            "description": "Conversation source",
            "example": "api"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Message create date",
            "example": "2022-01-01T00:00:00.000Z"
          },
          "conversationMessageFeedbacks": {
            "description": "List of conversation message feedbacks",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BaseFeedbackResponseDTO"
            }
          },
          "fullAIResponse": {
            "description": "Full AI response",
            "allOf": [
              {
                "$ref": "#/components/schemas/FullAIResponseDTO"
              }
            ]
          },
          "modelUsage": {
            "nullable": true,
            "description": "Token usage for this AI response, aggregated across its model calls. Model metadata describes the last model used. Null for messages without recorded usage.",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ConversationMessageModelUsageResponseDTO"
              }
            ]
          },
          "usedFunctions": {
            "nullable": true,
            "description": "Functions called while generating this assistant message. Execution status is not included.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationMessageUsedFunctionResponseDTO"
            }
          },
          "subagentId": {
            "type": "string",
            "nullable": true,
            "description": "Subagent selected by automatic orchestration for this assistant message."
          },
          "expandedMessage": {
            "type": "string",
            "nullable": true,
            "description": "Expanded version of the message produced by Enhanced Prompting, if the skill is attached to the agent. Null when the skill is not attached or expansion was skipped."
          },
          "files": {
            "description": "Conversation message files",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationMessageFileResponseDTO"
            }
          },
          "isAnonymized": {
            "type": "boolean",
            "description": "Is anonymized",
            "example": false
          }
        },
        "required": [
          "id",
          "message",
          "conversationId",
          "senderRole",
          "conversationMessageId",
          "source",
          "createdAt",
          "isAnonymized"
        ]
      },
      "DeleteUserConversationsBodyDTO": {
        "type": "object",
        "properties": {
          "conversationUserId": {
            "type": "string",
            "description": "Conversation user ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          }
        },
        "required": [
          "conversationUserId"
        ]
      },
      "UpdateConversationBodyDTO": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Conversation title",
            "example": "Updated Conversation Title",
            "maxLength": 255
          },
          "context": {
            "type": "string",
            "description": "Conversation context",
            "example": "Updated conversation context",
            "maxLength": 256000
          },
          "status": {
            "type": "string",
            "description": "Conversation status",
            "example": "active",
            "enum": [
              "active",
              "inactive",
              "archived"
            ]
          },
          "conversationStateId": {
            "type": "string",
            "description": "Conversation state ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          }
        }
      },
      "UpdateConversationModeBodyDTO": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "description": "Conversation mode",
            "example": "ai",
            "enum": [
              "manual",
              "ai"
            ]
          }
        }
      },
      "SendMessageToUserBodyDTO": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The message that will be sent to the user",
            "example": "Your appointment has been confirmed for tomorrow at 2pm."
          },
          "conversationMessageId": {
            "type": "string",
            "description": "The ID of the conversation message that the user sent to the AI agent",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "authorId": {
            "type": "string",
            "description": "Author platform ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "files": {
            "description": "Files attached to the message",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessageFileBodyDTO"
            }
          }
        },
        "required": [
          "message"
        ]
      },
      "CreateConversationMessageFileSignedUploadUrlBodyDTO": {
        "type": "object",
        "properties": {
          "fileName": {
            "type": "string",
            "description": "File name",
            "example": "image.png"
          },
          "contentType": {
            "type": "string",
            "description": "File content type",
            "example": "image/png"
          }
        },
        "required": [
          "fileName",
          "contentType"
        ]
      },
      "CreateConversationMessageFileSignedUploadUrlResponseDTO": {
        "type": "object",
        "properties": {
          "signedUrl": {
            "type": "string",
            "description": "Signed upload URL"
          },
          "storagePath": {
            "type": "string",
            "description": "Storage path that should be sent later in send message API"
          }
        },
        "required": [
          "signedUrl",
          "storagePath"
        ]
      },
      "GetConversationMessageFileSignedUrlResponseDTO": {
        "type": "object",
        "properties": {
          "signedUrl": {
            "type": "string",
            "description": "Signed download URL",
            "example": "https://example.com/download/test.png"
          },
          "fileId": {
            "type": "string",
            "description": "Conversation message file ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          }
        },
        "required": [
          "signedUrl",
          "fileId"
        ]
      },
      "PromptFileBodyDTO": {
        "type": "object",
        "properties": {
          "fileName": {
            "type": "string",
            "description": "File name",
            "example": "test.png"
          },
          "storagePath": {
            "type": "string",
            "description": "Storage path",
            "example": "prompt-files/conv_h435hi34h5i43i5/test.png"
          }
        },
        "required": [
          "fileName",
          "storagePath"
        ]
      },
      "ProcessPromptBodyDTO": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The question that the user sends to the AI agent",
            "example": "How does quantum entanglement work?"
          },
          "tokenTrackingId": {
            "type": "string",
            "description": "The ID of the token tracking",
            "example": "any-token-id-323jbb3242dwfwefew34234"
          },
          "files": {
            "description": "Files attached to the message",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PromptFileBodyDTO"
            }
          }
        },
        "required": [
          "prompt"
        ]
      },
      "PromptTokenUsageDTO": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string",
            "description": "Model reported for the prompt run. For multi-model runs, this is the last model used.",
            "example": "openai/gpt-5",
            "nullable": true
          },
          "modelProvider": {
            "type": "string",
            "description": "Provider of the reported model",
            "example": "openAI",
            "nullable": true
          },
          "reasoningEffort": {
            "type": "string",
            "description": "Reasoning effort used by the reported model",
            "example": "medium",
            "nullable": true
          },
          "reasoningMode": {
            "type": "string",
            "description": "Reasoning mode used by the reported model",
            "example": "enabled",
            "nullable": true
          },
          "inputTokens": {
            "type": "number",
            "description": "Aggregate number of input tokens used for the prompt run",
            "example": 8000
          },
          "outputTokens": {
            "type": "number",
            "description": "Aggregate number of output tokens used for the prompt run",
            "example": 3345
          },
          "reasoningTokens": {
            "type": "number",
            "description": "Aggregate number of reasoning tokens used for the prompt run. Returns 0 for non-reasoning models.",
            "example": 1000
          },
          "totalTokens": {
            "type": "number",
            "description": "Aggregate total number of tokens used for the prompt run",
            "example": 12345
          }
        },
        "required": [
          "model",
          "modelProvider",
          "reasoningEffort",
          "reasoningMode",
          "inputTokens",
          "outputTokens",
          "reasoningTokens",
          "totalTokens"
        ]
      },
      "ProcessPromptResponseDTO": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ],
            "description": "Response status",
            "example": "completed"
          },
          "totalTokens": {
            "type": "number",
            "description": "Total number of tokens used for the request",
            "example": 12345,
            "nullable": true
          },
          "usage": {
            "description": "Token usage for a completed prompt run. Token counts are aggregated across model calls; model metadata describes the last model used.",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PromptTokenUsageDTO"
              }
            ]
          },
          "response": {
            "type": "string",
            "description": "The AI-generated response to the user prompt",
            "example": "The theory of relativity explains how time and space are linked",
            "nullable": true
          },
          "error": {
            "type": "string",
            "description": "Response error",
            "nullable": true
          }
        },
        "required": [
          "status",
          "totalTokens",
          "usage",
          "response",
          "error"
        ]
      },
      "CreatePromptBodyDTO": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The question that the user sends to the AI agent",
            "example": "How does quantum entanglement work?"
          },
          "tokenTrackingId": {
            "type": "string",
            "description": "The ID of the token tracking",
            "example": "any-token-id-323jbb3242dwfwefew34234"
          },
          "files": {
            "description": "Files attached to the message",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PromptFileBodyDTO"
            }
          }
        },
        "required": [
          "prompt"
        ]
      },
      "CreatePromptResponseDTO": {
        "type": "object",
        "properties": {
          "promptId": {
            "type": "string",
            "description": "The ID of the prompt",
            "example": "1234567890"
          }
        },
        "required": [
          "promptId"
        ]
      },
      "GetResponseOnPromptResponseDTO": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ],
            "description": "Response status",
            "example": "completed"
          },
          "totalTokens": {
            "type": "number",
            "description": "Total number of tokens used for the request",
            "example": 12345,
            "nullable": true
          },
          "usage": {
            "description": "Token usage for a completed prompt run. Token counts are aggregated across model calls; model metadata describes the last model used.",
            "nullable": true,
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/PromptTokenUsageDTO"
              }
            ]
          },
          "response": {
            "type": "string",
            "description": "The AI-generated response to the user prompt",
            "example": "The theory of relativity explains how time and space are linked",
            "nullable": true
          },
          "error": {
            "type": "string",
            "description": "Response error",
            "nullable": true
          }
        },
        "required": [
          "status",
          "totalTokens",
          "usage",
          "response",
          "error"
        ]
      },
      "CreatePromptFileSignedUploadUrlBodyDTO": {
        "type": "object",
        "properties": {
          "fileName": {
            "type": "string",
            "description": "File name",
            "example": "image.png"
          },
          "contentType": {
            "type": "string",
            "description": "File content type",
            "example": "image/png"
          }
        },
        "required": [
          "fileName",
          "contentType"
        ]
      },
      "CreatePromptFileSignedUploadUrlResponseDTO": {
        "type": "object",
        "properties": {
          "signedUrl": {
            "type": "string",
            "description": "Signed upload URL"
          },
          "storagePath": {
            "type": "string",
            "description": "Storage path that should be sent later in send message API"
          }
        },
        "required": [
          "signedUrl",
          "storagePath"
        ]
      },
      "ExternalApiAgentAdminUserResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "admin@example.com"
          },
          "firstName": {
            "type": "string",
            "description": "User first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "User last name",
            "example": "Doe"
          },
          "avatarUrl": {
            "type": "string",
            "nullable": true,
            "description": "User avatar URL",
            "example": "https://storage.example.com/avatars/user.png"
          },
          "agentRole": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "editor",
              "user",
              "copilot_user",
              "copilot_admin"
            ],
            "nullable": true,
            "description": "Role assigned to the user directly on the agent. Null when the user has no direct agent assignment and access is granted by an organization-level role.",
            "example": "admin"
          },
          "agentAccessStatus": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "nullable": true,
            "description": "Status of the direct user-to-agent assignment. Null when the user has no direct agent assignment.",
            "example": "active"
          },
          "organizationRole": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "manager",
              "user",
              "copilot_user",
              "copilot_admin",
              "guest"
            ],
            "nullable": true,
            "description": "Role of the user in the agent's organization.",
            "example": "admin"
          },
          "organizationStatus": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "nullable": true,
            "description": "Status of the user's membership in the agent's organization.",
            "example": "active"
          },
          "accessSource": {
            "type": "string",
            "enum": [
              "agent",
              "organization"
            ],
            "description": "Whether admin access comes from a direct owner or admin role on the agent, or from an owner or admin role in the organization that owns the agent.",
            "example": "agent"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "User creation date",
            "example": "2024-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "id",
          "email",
          "firstName",
          "lastName",
          "accessSource",
          "createdAt"
        ]
      },
      "BaseSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          }
        },
        "required": [
          "systemName",
          "status"
        ]
      },
      "DataRetentionSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "retentionDays": {
            "type": "number",
            "description": "Retention days."
          },
          "anonymizeConversations": {
            "type": "boolean",
            "description": "Anonymize conversations."
          },
          "anonymizeConversationUsers": {
            "type": "boolean",
            "description": "Anonymize conversation users."
          }
        },
        "required": [
          "systemName",
          "status",
          "retentionDays",
          "anonymizeConversations",
          "anonymizeConversationUsers"
        ]
      },
      "LiveChatWidgetButtonThemeExternalDTO": {
        "type": "object",
        "properties": {
          "backgroundColor": {
            "type": "string",
            "description": "Launcher button background color (hex)."
          },
          "textColor": {
            "type": "string",
            "description": "Launcher button text and icon color (hex)."
          }
        },
        "required": [
          "backgroundColor",
          "textColor"
        ]
      },
      "LiveChatWidgetProactiveBubbleExternalDTO": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Proactive teaser copy (when launcherTeaser is proactive)."
          },
          "delaySeconds": {
            "type": "number",
            "description": "Delay in seconds before the proactive teaser (0–3600)."
          }
        },
        "required": [
          "message",
          "delaySeconds"
        ]
      },
      "LiveChatWidgetButtonExternalDTO": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "automatic",
              "on_hover"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "icon_only",
              "text_only",
              "icon_and_text"
            ]
          },
          "borderRadius": {
            "type": "string",
            "enum": [
              "0px",
              "8px",
              "100%"
            ]
          },
          "size": {
            "type": "string",
            "description": "Launcher size in pixels ",
            "example": "56px"
          },
          "selectedTheme": {
            "type": "string",
            "enum": [
              "light",
              "dark",
              "system"
            ],
            "description": "Light, dark, or system color resolution for the launcher. Required when launcherTheme is custom."
          },
          "lightThemeConfig": {
            "$ref": "#/components/schemas/LiveChatWidgetButtonThemeExternalDTO"
          },
          "darkThemeConfig": {
            "$ref": "#/components/schemas/LiveChatWidgetButtonThemeExternalDTO"
          },
          "launcherAttentionEffect": {
            "type": "string",
            "enum": [
              "none",
              "pulse"
            ]
          },
          "launcherTheme": {
            "type": "string",
            "enum": [
              "default",
              "solid",
              "gradient",
              "glassmorphism",
              "custom"
            ]
          },
          "logoFit": {
            "type": "string",
            "enum": [
              "cover",
              "contain"
            ]
          },
          "launcherTeaser": {
            "type": "string",
            "enum": [
              "suggestions",
              "proactive",
              "none"
            ]
          },
          "proactiveBubble": {
            "description": "Proactive teaser (when launcherTeaser is proactive).",
            "allOf": [
              {
                "$ref": "#/components/schemas/LiveChatWidgetProactiveBubbleExternalDTO"
              }
            ]
          }
        },
        "required": [
          "mode",
          "type",
          "borderRadius",
          "size",
          "lightThemeConfig",
          "darkThemeConfig",
          "launcherAttentionEffect",
          "launcherTheme",
          "logoFit",
          "launcherTeaser"
        ]
      },
      "LiveChatLinkExternalDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Label displayed for the link.",
            "example": "Privacy Policy"
          },
          "url": {
            "type": "string",
            "description": "Absolute URL opened when the link is selected.",
            "example": "https://example.com/privacy"
          }
        },
        "required": [
          "name",
          "url"
        ]
      },
      "LiveChatSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "color": {
            "type": "string",
            "description": "Color of the chat widget.",
            "example": "#5D6169"
          },
          "widgetButtonConfig": {
            "description": "Embedded chat launcher (widget button) settings with legacy fields normalized.",
            "allOf": [
              {
                "$ref": "#/components/schemas/LiveChatWidgetButtonExternalDTO"
              }
            ]
          },
          "titleLine1": {
            "type": "string",
            "description": "First line of the chat widget title.",
            "example": ""
          },
          "titleLine2": {
            "type": "string",
            "description": "Second line of the chat widget title.",
            "example": "Hello, how can I help you?"
          },
          "intro": {
            "type": "string",
            "description": "Default introduction message (same as titleLine2; kept for backwards compatibility).",
            "example": "Hello, how can I help you?"
          },
          "links": {
            "description": "List of links to be displayed in the chat widget.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LiveChatLinkExternalDTO"
            }
          },
          "disclaimer": {
            "type": "string",
            "description": "Disclaimer message.",
            "example": "This is a disclaimer message."
          },
          "chatFooterContent": {
            "type": "string",
            "description": "Chat footer content below the input (e.g. privacy policy)",
            "example": "By chatting with us, you agree to our [Privacy Policy](https://example.com/privacy)."
          },
          "suggestions": {
            "description": "List of suggestions for the chat widget.",
            "example": [
              "Suggestion 1",
              "Suggestion 2",
              "Suggestion 3"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "whitelistedIps": {
            "description": "List of IP addresses that are whitelisted.",
            "example": [
              "192.168.1.1",
              "192.168.1.2"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "restrictedCountries": {
            "description": "List of countries that are restricted.",
            "example": [
              "US",
              "CA",
              "GB"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "limitUnavailableDates": {
            "type": "boolean",
            "description": "Whether live chat should be unavailable on the configured unavailableDates (YYYY-MM-DD).",
            "example": false
          },
          "unavailableDates": {
            "description": "Dates (YYYY-MM-DD) when live chat is unavailable (e.g. holidays, maintenance).",
            "example": [
              "2026-01-01",
              "2026-12-25"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "unavailableDatesMessage": {
            "type": "string",
            "description": "Custom message to show when live chat is unavailable on unavailableDates.",
            "example": "Chat is unavailable today. Please come back tomorrow."
          }
        },
        "required": [
          "systemName",
          "status",
          "limitUnavailableDates",
          "unavailableDates",
          "unavailableDatesMessage"
        ]
      },
      "SmsSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "phoneNumber": {
            "type": "string",
            "description": "Phone number associated with the sms skill.",
            "example": "+1234567890"
          },
          "defaultSmsIntroduction": {
            "type": "object",
            "description": "Default SMS introduction.",
            "example": "Welcome to our service!"
          },
          "smsSignature": {
            "type": "object",
            "description": "SMS signature.",
            "example": "Thank you for your message!"
          },
          "responseDelaySeconds": {
            "type": "object",
            "description": "Delay in seconds before sending an SMS response (0–3600).",
            "nullable": true,
            "example": 0
          }
        },
        "required": [
          "systemName",
          "status",
          "phoneNumber"
        ]
      },
      "MsTeamsChannelScopeExternalDTO": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "ALL_ENABLED",
              "CUSTOM"
            ],
            "description": "ALL_ENABLED = agent responds in all channels; CUSTOM = only listed channelIds."
          },
          "channelIds": {
            "description": "Channel IDs the agent is enabled for (only used when mode is CUSTOM).",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "mode",
          "channelIds"
        ]
      },
      "MsTeamsTeamConfigExternalDTO": {
        "type": "object",
        "properties": {
          "teamId": {
            "type": "string",
            "description": "Microsoft Teams team ID."
          },
          "channels": {
            "$ref": "#/components/schemas/MsTeamsChannelScopeExternalDTO"
          }
        },
        "required": [
          "teamId",
          "channels"
        ]
      },
      "MsTeamsUserScopeExternalDTO": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "ALL_ENABLED",
              "CUSTOM"
            ],
            "description": "ALL_ENABLED = agent responds to all users; CUSTOM = only listed userIds."
          },
          "userIds": {
            "description": "User IDs the agent is enabled for (only used when mode is CUSTOM).",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "mode",
          "userIds"
        ]
      },
      "MsTeamsTenantConfigExternalDTO": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "description": "Microsoft Entra tenant GUID."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether this tenant is enabled for the MS Teams skill. When false, inbound Teams messages for this tenant are blocked."
          },
          "teams": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MsTeamsTeamConfigExternalDTO"
            }
          },
          "users": {
            "$ref": "#/components/schemas/MsTeamsUserScopeExternalDTO"
          }
        },
        "required": [
          "tenantId",
          "enabled",
          "teams",
          "users"
        ]
      },
      "MsTeamsSkillConfigExternalDTO": {
        "type": "object",
        "properties": {
          "isFileUploadEnabled": {
            "type": "boolean",
            "description": "Whether users can send file attachments to this agent through Microsoft Teams."
          },
          "tenants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MsTeamsTenantConfigExternalDTO"
            }
          }
        },
        "required": [
          "isFileUploadEnabled",
          "tenants"
        ]
      },
      "MsTeamsSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "config": {
            "description": "Microsoft Teams skill configuration.",
            "allOf": [
              {
                "$ref": "#/components/schemas/MsTeamsSkillConfigExternalDTO"
              }
            ]
          }
        },
        "required": [
          "systemName",
          "status",
          "config"
        ]
      },
      "EmailSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "email": {
            "type": "string",
            "description": "Email address associated with the email skill.",
            "example": "email@gmail.com"
          },
          "senderName": {
            "type": "string",
            "description": "Name of the email sender.",
            "example": "John Doe"
          },
          "defaultSubject": {
            "type": "string",
            "description": "Email subject.",
            "example": "Subject of the email"
          },
          "defaultEmailIntroduction": {
            "type": "string",
            "description": "Default email introduction.",
            "example": "Welcome to our service!"
          },
          "emailSignature": {
            "type": "string",
            "description": "Default email closing.",
            "example": "Thank you for your email!"
          },
          "responseDelaySeconds": {
            "type": "object",
            "description": "Delay in seconds before sending an email response (0–3600).",
            "nullable": true,
            "example": 0
          }
        },
        "required": [
          "systemName",
          "status",
          "email"
        ]
      },
      "WebhookResponseDTO": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Status of the webhook.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "title": {
            "type": "string",
            "description": "Webhook title.",
            "example": "Webhook Title"
          },
          "description": {
            "type": "string",
            "description": "Webhook description.",
            "example": "Description of the webhook"
          },
          "url": {
            "type": "string",
            "description": "Webhook URL.",
            "example": "https://example.com/webhook-url"
          },
          "triggerCondition": {
            "type": "string",
            "description": "Webhook trigger condition.",
            "enum": [
              "each_message",
              "end_dialog",
              "start_dialog",
              "chat_currently_unavailable",
              "auto_archive_conversation",
              "manual"
            ],
            "example": "each_message"
          },
          "headers": {
            "type": "object",
            "description": "Webhook headers.",
            "example": {
              "Authorization": "Bearer token",
              "Content-Type": "application/json"
            }
          }
        },
        "required": [
          "status",
          "title",
          "description",
          "url",
          "triggerCondition"
        ]
      },
      "WebhookSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "name": {
            "type": "string",
            "description": "Webhook skill name.",
            "example": "Webhook Skill Name"
          },
          "description": {
            "type": "string",
            "description": "Webhook skill description.",
            "example": "Description of the webhook skill"
          },
          "webhooks": {
            "description": "Webhook configs.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookResponseDTO"
            }
          }
        },
        "required": [
          "systemName",
          "status",
          "name",
          "description",
          "webhooks"
        ]
      },
      "FunctionsSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          }
        },
        "required": [
          "systemName",
          "status"
        ]
      },
      "ScoringSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "scoringPrompt": {
            "type": "string",
            "description": "Scoring prompt.",
            "example": "Please rate the service from 1 to 5."
          }
        },
        "required": [
          "systemName",
          "status"
        ]
      },
      "APISkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "apiKey": {
            "type": "string",
            "description": "API key for the skill.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          }
        },
        "required": [
          "systemName",
          "status",
          "apiKey"
        ]
      },
      "VoiceSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "vApiAssistantId": {
            "type": "string",
            "description": "Vapi assistant id."
          },
          "vApiPhoneNumberId": {
            "type": "string",
            "description": "Vapi phone number id."
          }
        },
        "required": [
          "systemName",
          "status",
          "vApiAssistantId",
          "vApiPhoneNumberId"
        ]
      },
      "MemorySkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "type": {
            "type": "string",
            "enum": [
              "BY_USER",
              "BY_AGENT"
            ],
            "description": "Memory skill type."
          },
          "retentionDuration": {
            "type": "number",
            "description": "Retention duration."
          }
        },
        "required": [
          "systemName",
          "status",
          "type",
          "retentionDuration"
        ]
      },
      "ReportSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "frequency": {
            "type": "string",
            "enum": [
              "DAILY",
              "WEEKLY",
              "MONTHLY"
            ],
            "description": "Agent report frequency."
          },
          "emails": {
            "description": "Agent report emails.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "systemName",
          "status",
          "frequency",
          "emails"
        ]
      },
      "ScrapingConfigResponseDTO": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "Scraping url."
          },
          "startCrawledAt": {
            "format": "date-time",
            "type": "string",
            "description": "Start crawled at.",
            "nullable": true
          },
          "endCrawledAt": {
            "format": "date-time",
            "type": "string",
            "description": "End crawled at.",
            "nullable": true
          },
          "crawlerType": {
            "type": "string",
            "enum": [
              "FIRECRAWL",
              "APIFY"
            ],
            "description": "Crawler type."
          },
          "crawlFormat": {
            "type": "string",
            "enum": [
              "JSON",
              "MARKDOWN",
              "HTML",
              "CONTENT"
            ],
            "description": "Crawl format."
          },
          "excludeUrls": {
            "description": "Excluded urls.",
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pageLimit": {
            "type": "number",
            "description": "Page limit."
          },
          "maxDepth": {
            "type": "number",
            "description": "Max depth."
          },
          "frequency": {
            "type": "string",
            "enum": [
              "manual",
              "daily",
              "weekly",
              "monthly"
            ],
            "description": "Scraping frequency."
          },
          "autoUpload": {
            "type": "boolean",
            "description": "Is auto upload enabled."
          },
          "crawlingStatus": {
            "type": "string",
            "enum": [
              "not_started",
              "in_progress",
              "completed",
              "failed",
              "canceled"
            ],
            "description": "Crawling status."
          }
        },
        "required": [
          "url",
          "startCrawledAt",
          "endCrawledAt",
          "crawlerType",
          "crawlFormat",
          "excludeUrls",
          "pageLimit",
          "maxDepth",
          "frequency",
          "autoUpload",
          "crawlingStatus"
        ]
      },
      "ScrapingSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "scrapingConfigs": {
            "description": "Agent scraping configs.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ScrapingConfigResponseDTO"
            }
          }
        },
        "required": [
          "systemName",
          "status",
          "scrapingConfigs"
        ]
      },
      "NotificationSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          }
        },
        "required": [
          "systemName",
          "status"
        ]
      },
      "ExternalRetrieverConfig": {
        "type": "object",
        "properties": {
          "apiKey": {
            "type": "string",
            "description": "External retriever API key."
          },
          "indexName": {
            "type": "string",
            "description": "External retriever index name."
          },
          "host": {
            "type": "string",
            "description": "External retriever host."
          },
          "fieldName": {
            "type": "string",
            "description": "External retriever field name."
          },
          "namespace": {
            "type": "string",
            "description": "External retriever namespace."
          },
          "topK": {
            "type": "number",
            "description": "External retriever topK."
          },
          "isEmbedded": {
            "type": "boolean",
            "description": "External retriever is embedded."
          },
          "dimensions": {
            "type": "number",
            "description": "External retriever dimensions."
          },
          "model": {
            "type": "string",
            "enum": [
              "text-embedding-ada-002",
              "text-embedding-3-large",
              "text-embedding-3-small"
            ],
            "description": "External retriever model."
          }
        },
        "required": [
          "apiKey",
          "indexName",
          "host",
          "fieldName",
          "namespace",
          "topK",
          "isEmbedded"
        ]
      },
      "ExternalRetrieverResponseDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Retriever name."
          },
          "type": {
            "type": "string",
            "enum": [
              "pinecone"
            ],
            "description": "Retriever type."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Retriever status."
          },
          "config": {
            "description": "Retriever config.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalRetrieverConfig"
              }
            ]
          }
        },
        "required": [
          "name",
          "type",
          "status",
          "config"
        ]
      },
      "ExternalRetrieversSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "externalRetrievers": {
            "description": "External retrievers.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalRetrieverResponseDTO"
            }
          }
        },
        "required": [
          "systemName",
          "status",
          "externalRetrievers"
        ]
      },
      "FeedbackSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "period": {
            "type": "string",
            "enum": [
              "last_30_days",
              "last_60_days",
              "last_90_days",
              "all_time"
            ],
            "description": "Feedback period."
          },
          "autoUpload": {
            "type": "boolean",
            "description": "Is auto upload enabled."
          },
          "generationMode": {
            "type": "string",
            "enum": [
              "manual",
              "auto"
            ],
            "description": "Feedback generation mode."
          }
        },
        "required": [
          "systemName",
          "status",
          "period",
          "autoUpload",
          "generationMode"
        ]
      },
      "EscalationRecipientsResponseDTO": {
        "type": "object",
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "sms",
              "email",
              "webhook"
            ],
            "description": "Notification channel."
          },
          "value": {
            "type": "string",
            "description": "Notification recipient."
          },
          "headers": {
            "type": "object",
            "description": "Optional headers to be sent with the webhook",
            "example": {
              "Authorization": "Bearer token"
            }
          }
        },
        "required": [
          "channel",
          "value"
        ]
      },
      "EscalationResponseDTO": {
        "type": "object",
        "properties": {
          "topic": {
            "type": "string",
            "description": "Escalation topic."
          },
          "escalationPrompt": {
            "type": "string",
            "description": "Escalation prompt."
          },
          "autoChangeConversationMode": {
            "type": "boolean",
            "description": "Is auto change conversation mode to manual enabled?"
          },
          "response": {
            "type": "string",
            "description": "Message to the user in case of escalation."
          },
          "recipients": {
            "description": "Send notification to the recipients in case of escalation.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EscalationRecipientsResponseDTO"
            }
          }
        },
        "required": [
          "topic",
          "escalationPrompt",
          "autoChangeConversationMode",
          "response",
          "recipients"
        ]
      },
      "EscalationSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "escalations": {
            "description": "Escalations.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EscalationResponseDTO"
            }
          }
        },
        "required": [
          "systemName",
          "status",
          "escalations"
        ]
      },
      "CalCalendarConfig": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "cal"
            ],
            "description": "Calendar type."
          },
          "apiKey": {
            "type": "string",
            "description": "Cal calendar API key."
          },
          "prompt": {
            "type": "string",
            "description": "Cal calendar prompt."
          }
        },
        "required": [
          "type",
          "apiKey",
          "prompt"
        ]
      },
      "CalendarSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "config": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/CalCalendarConfig"
              }
            ],
            "discriminator": {
              "propertyName": "type",
              "mapping": {
                "cal": "#/components/schemas/CalCalendarConfig"
              }
            },
            "allOf": [
              {
                "$ref": "#/components/schemas/CalCalendarConfig"
              }
            ]
          }
        },
        "required": [
          "systemName",
          "status",
          "config"
        ]
      },
      "SlackChannelScopeExternalDTO": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "ALL_ENABLED",
              "CUSTOM"
            ],
            "description": "ALL_ENABLED = agent responds in all channels; CUSTOM = only listed channelIds."
          },
          "channelIds": {
            "description": "Slack channel IDs (C…) the agent is enabled for (only used when mode is CUSTOM).",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requireKnownRaiaUser": {
            "type": "boolean",
            "description": "When true, only respond to senders whose Slack email maps to a Raia user."
          }
        },
        "required": [
          "mode",
          "channelIds",
          "requireKnownRaiaUser"
        ]
      },
      "SlackUserScopeExternalDTO": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "ALL_ENABLED",
              "CUSTOM"
            ],
            "description": "ALL_ENABLED = agent responds to all users in DMs/group DMs; CUSTOM = only listed userIds."
          },
          "userIds": {
            "description": "Slack user IDs (U…) the agent is enabled for (only used when mode is CUSTOM). Applies to DMs and group DMs.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requireKnownRaiaUser": {
            "type": "boolean",
            "description": "When true, only respond to senders whose Slack email maps to a Raia user."
          }
        },
        "required": [
          "mode",
          "userIds",
          "requireKnownRaiaUser"
        ]
      },
      "SlackWorkspaceConfigExternalDTO": {
        "type": "object",
        "properties": {
          "slackTeamId": {
            "type": "string",
            "description": "Slack workspace id (`T…`). Matches inbound `team_id`.",
            "example": "T01234567"
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether this workspace is enabled for the Slack skill. When false, inbound Slack messages for this workspace are blocked."
          },
          "channels": {
            "$ref": "#/components/schemas/SlackChannelScopeExternalDTO"
          },
          "users": {
            "$ref": "#/components/schemas/SlackUserScopeExternalDTO"
          }
        },
        "required": [
          "slackTeamId",
          "enabled",
          "channels",
          "users"
        ]
      },
      "SlackSkillConfigExternalDTO": {
        "type": "object",
        "properties": {
          "isFileUploadEnabled": {
            "type": "boolean",
            "description": "Whether users can send file attachments to this agent through Slack."
          },
          "workspaces": {
            "description": "Per-workspace Slack routing scope for this agent.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SlackWorkspaceConfigExternalDTO"
            }
          }
        },
        "required": [
          "isFileUploadEnabled",
          "workspaces"
        ]
      },
      "SlackSkillResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "config": {
            "description": "Slack skill configuration.",
            "allOf": [
              {
                "$ref": "#/components/schemas/SlackSkillConfigExternalDTO"
              }
            ]
          }
        },
        "required": [
          "systemName",
          "status",
          "config"
        ]
      },
      "ExternalApiAgentOrganizationResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Organization ID.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Organization name.",
            "example": "New Organization"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "pending",
              "archived",
              "blocked"
            ],
            "description": "Organization status.",
            "example": "active"
          }
        },
        "required": [
          "id",
          "name",
          "status"
        ]
      },
      "ExternalApiSuperAdminAgentResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Agent ID.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Agent name.",
            "example": "Support Agent"
          },
          "publicName": {
            "type": "string",
            "description": "Agent public name.",
            "example": "Support Assistant"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Agent description.",
            "example": "Answers customer support questions."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive",
              "draft"
            ],
            "description": "Agent status.",
            "example": "active"
          },
          "organizationId": {
            "type": "string",
            "description": "ID of the organization that owns the agent.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "organization": {
            "description": "Organization that owns the agent.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiAgentOrganizationResponseDTO"
              }
            ]
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Creation timestamp",
            "example": "2024-03-20T12:00:00Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Last update timestamp",
            "example": "2024-03-20T12:00:00Z"
          }
        },
        "required": [
          "id",
          "name",
          "publicName",
          "description",
          "status",
          "organizationId",
          "organization",
          "createdAt",
          "updatedAt"
        ]
      },
      "ExternalApiGetAllAgentsResponseDTO": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "number",
            "description": "Current page"
          },
          "pageSize": {
            "type": "number",
            "description": "Page size"
          },
          "totalItems": {
            "type": "number",
            "description": "Total items"
          },
          "totalPages": {
            "type": "number",
            "description": "Total pages"
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Has next page"
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Has previous page"
          },
          "data": {
            "description": "Agents for the requested page.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalApiSuperAdminAgentResponseDTO"
            }
          }
        },
        "required": [
          "currentPage",
          "pageSize",
          "totalItems",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage",
          "data"
        ]
      },
      "CreateAgentByApiKeyBodyDTO": {
        "type": "object",
        "properties": {
          "roleId": {
            "type": "string",
            "description": "Agent role ID.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Name of the agent.",
            "example": "My agent"
          },
          "publicName": {
            "type": "string",
            "description": "Public name of the agent.",
            "example": "My agent"
          },
          "description": {
            "type": "string",
            "description": "Description of the agent.",
            "example": "My agent description"
          },
          "instructions": {
            "type": "string",
            "description": "Instructions of the agent.",
            "example": "My agent instructions"
          },
          "model": {
            "type": "string",
            "description": "Model of the agent.",
            "example": "openai/gpt-5.1"
          },
          "topP": {
            "type": "number",
            "description": "TopP of the agent.",
            "example": 1
          },
          "temperature": {
            "type": "number",
            "description": "Temperature of the agent.",
            "example": 1
          },
          "isFileSearchEnabled": {
            "type": "boolean",
            "description": "Is file search enabled by default.",
            "example": false
          },
          "isCodeInterpreterEnabled": {
            "type": "boolean",
            "description": "Is code interpreter enabled by default.",
            "example": false
          },
          "fileSearchMaxNumResults": {
            "type": "number",
            "description": "File search max number of results. Required when isFileSearchEnabled is true.",
            "example": 10,
            "default": 10
          },
          "reasoningEffort": {
            "type": "string",
            "enum": [
              "none",
              "minimal",
              "low",
              "medium",
              "high",
              "xhigh",
              "max"
            ],
            "description": "Reasoning effort of the agent. Required only when mode is reasoning.",
            "example": "medium"
          },
          "reasoningMode": {
            "type": "string",
            "enum": [
              "standard",
              "pro"
            ],
            "description": "Reasoning mode of the agent.",
            "example": "standard"
          },
          "isApiSkillEnabled": {
            "type": "boolean",
            "description": "Is agent API skill enabled by default.",
            "example": true
          },
          "isOutputJsonSchemaEnabled": {
            "type": "boolean",
            "description": "Is output JSON schema enabled by default.",
            "example": false
          },
          "outputJsonSchema": {
            "type": "string",
            "description": "Output JSON schema of the agent.",
            "example": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}"
          },
          "tags": {
            "description": "Tags of the agent.",
            "example": "[\"Sales\", \"Support\"]",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "restrictDocumentsToOwnerOnly": {
            "type": "boolean",
            "description": "Restrict documents to owner only.",
            "example": false
          }
        },
        "required": [
          "roleId",
          "name",
          "publicName",
          "outputJsonSchema",
          "tags"
        ]
      },
      "AIConfigResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Agent AI config ID.",
            "example": "asst_1234567890"
          },
          "model": {
            "type": "string",
            "description": "Open AI model.",
            "example": "openai/gpt-5.1"
          },
          "temperature": {
            "type": "number",
            "description": "OpenAI temperature.",
            "example": 1
          },
          "topP": {
            "type": "number",
            "description": "OpenAI top_p.",
            "example": 1
          },
          "instructions": {
            "type": "string",
            "description": "OpenAI instructions."
          },
          "isCodeInterpreterEnabled": {
            "type": "boolean",
            "description": "Is code interpreter enabled.",
            "example": true
          },
          "isFileSearchEnabled": {
            "type": "boolean",
            "description": "Is file search enabled.",
            "example": true
          },
          "fileSearchMaxNumResults": {
            "type": "number",
            "description": "File search max number of results.",
            "example": 10
          },
          "reasoningEffort": {
            "type": "string",
            "enum": [
              "none",
              "minimal",
              "low",
              "medium",
              "high",
              "xhigh",
              "max"
            ],
            "description": "Reasoning effort of the agent.",
            "example": "medium",
            "nullable": true
          },
          "reasoningMode": {
            "type": "string",
            "enum": [
              "standard",
              "pro"
            ],
            "description": "Reasoning mode of the agent.",
            "example": "standard",
            "nullable": true
          },
          "isOutputJsonSchemaEnabled": {
            "type": "boolean",
            "description": "Is output JSON schema enabled.",
            "example": true
          },
          "outputJsonSchema": {
            "type": "string",
            "description": "Output JSON schema of the agent.",
            "example": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}"
          }
        },
        "required": [
          "id",
          "model",
          "temperature",
          "topP",
          "instructions",
          "isCodeInterpreterEnabled",
          "isFileSearchEnabled",
          "fileSearchMaxNumResults",
          "outputJsonSchema"
        ]
      },
      "CreateAgentResponseDTO": {
        "type": "object",
        "properties": {
          "organizationId": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Unique identifier for the organization.",
            "format": "uuid"
          },
          "organizationName": {
            "type": "string",
            "description": "Name of the organization."
          },
          "id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Unique identifier for the agent.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Name of the agent."
          },
          "publicName": {
            "type": "string",
            "description": "Public name of the agent."
          },
          "role": {
            "type": "string",
            "description": "Role of the agent."
          },
          "description": {
            "type": "string",
            "description": "Description of the agent."
          },
          "vectorStoreId": {
            "type": "string",
            "description": "OpenAI vector store ID.",
            "example": "vs_1234567890"
          },
          "aiConfig": {
            "description": "Agent AI config.",
            "allOf": [
              {
                "$ref": "#/components/schemas/AIConfigResponseDTO"
              }
            ]
          },
          "avatarUrl": {
            "type": "string",
            "description": "Avatar URL of the agent.",
            "example": "https://example.com/avatar.jpg"
          },
          "status": {
            "type": "string",
            "description": "Status of the agent.",
            "enum": [
              "active",
              "inactive",
              "draft"
            ]
          },
          "tags": {
            "description": "Agent tags.",
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "skills": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/BaseSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/LiveChatSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/SmsSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/EmailSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/WebhookSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/FunctionsSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/ScoringSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/APISkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/VoiceSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/MemorySkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/ReportSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/ScrapingSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/NotificationSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/ExternalRetrieversSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/FeedbackSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/EscalationSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/CalendarSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/DataRetentionSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/MsTeamsSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/SlackSkillResponseDTO"
                }
              ]
            },
            "description": "List of skills associated with the agent."
          },
          "restrictDocumentsToOwnerOnly": {
            "type": "boolean",
            "description": "Restrict documents to owner only.",
            "example": false
          },
          "agentApiKey": {
            "type": "string",
            "nullable": true,
            "description": "Deprecated: API keys are now managed separately via the agent API key endpoints"
          }
        },
        "required": [
          "organizationId",
          "organizationName",
          "id",
          "name",
          "publicName",
          "role",
          "vectorStoreId",
          "aiConfig",
          "status",
          "skills"
        ]
      },
      "GetOrganizationAgentUsersResponseDTO": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "number",
            "description": "Current page"
          },
          "pageSize": {
            "type": "number",
            "description": "Page size"
          },
          "totalItems": {
            "type": "number",
            "description": "Total items"
          },
          "totalPages": {
            "type": "number",
            "description": "Total pages"
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Has next page"
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Has previous page"
          },
          "data": {
            "description": "List of users",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalApiUserResponseDTO"
            }
          }
        },
        "required": [
          "currentPage",
          "pageSize",
          "totalItems",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage",
          "data"
        ]
      },
      "ExternalApiAgentPlatformUserResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "admin@example.com"
          },
          "firstName": {
            "type": "string",
            "description": "User first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "User last name",
            "example": "Doe"
          },
          "avatarUrl": {
            "type": "string",
            "nullable": true,
            "description": "User avatar URL",
            "example": "https://storage.example.com/avatars/user.png"
          },
          "agentRole": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "editor",
              "user",
              "copilot_user",
              "copilot_admin"
            ],
            "nullable": true,
            "description": "Role assigned to the user directly on the agent. Null when the user has no direct agent assignment and access is granted by an organization-level role.",
            "example": "admin"
          },
          "agentAccessStatus": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "nullable": true,
            "description": "Status of the direct user-to-agent assignment. Null when the user has no direct agent assignment.",
            "example": "active"
          },
          "organizationRole": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "manager",
              "user",
              "copilot_user",
              "copilot_admin",
              "guest"
            ],
            "nullable": true,
            "description": "Role of the user in the agent's organization.",
            "example": "admin"
          },
          "organizationStatus": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "nullable": true,
            "description": "Status of the user's membership in the agent's organization.",
            "example": "active"
          },
          "accessSource": {
            "type": "string",
            "enum": [
              "agent",
              "organization"
            ],
            "description": "Whether access comes from a direct role on the agent or from an owner or admin role in the organization that owns the agent.",
            "example": "agent"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "User creation date",
            "example": "2024-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "id",
          "email",
          "firstName",
          "lastName",
          "accessSource",
          "createdAt"
        ]
      },
      "GetAgentPlatformUsersResponseDTO": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "number",
            "description": "Current page"
          },
          "pageSize": {
            "type": "number",
            "description": "Page size"
          },
          "totalItems": {
            "type": "number",
            "description": "Total items"
          },
          "totalPages": {
            "type": "number",
            "description": "Total pages"
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Has next page"
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Has previous page"
          },
          "data": {
            "description": "Platform users with access to the agent, with their agent and organization roles.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalApiAgentPlatformUserResponseDTO"
            }
          }
        },
        "required": [
          "currentPage",
          "pageSize",
          "totalItems",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage",
          "data"
        ]
      },
      "GetAgentUsersByApiKeyResponseDTO": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "number",
            "description": "Current page"
          },
          "pageSize": {
            "type": "number",
            "description": "Page size"
          },
          "totalItems": {
            "type": "number",
            "description": "Total items"
          },
          "totalPages": {
            "type": "number",
            "description": "Total pages"
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Has next page"
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Has previous page"
          },
          "data": {
            "description": "List of users",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalApiUserResponseDTO"
            }
          }
        },
        "required": [
          "currentPage",
          "pageSize",
          "totalItems",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage",
          "data"
        ]
      },
      "GetAgentAdminUsersByApiKeyResponseDTO": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "number",
            "description": "Current page"
          },
          "pageSize": {
            "type": "number",
            "description": "Page size"
          },
          "totalItems": {
            "type": "number",
            "description": "Total items"
          },
          "totalPages": {
            "type": "number",
            "description": "Total pages"
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Has next page"
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Has previous page"
          },
          "data": {
            "description": "List of agent admin users",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalApiAgentAdminUserResponseDTO"
            }
          }
        },
        "required": [
          "currentPage",
          "pageSize",
          "totalItems",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage",
          "data"
        ]
      },
      "GetAgentByApiKeyResponseDTO": {
        "type": "object",
        "properties": {
          "organizationId": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Unique identifier for the organization.",
            "format": "uuid"
          },
          "organizationName": {
            "type": "string",
            "description": "Name of the organization."
          },
          "id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Unique identifier for the agent.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Name of the agent."
          },
          "publicName": {
            "type": "string",
            "description": "Public name of the agent."
          },
          "role": {
            "type": "string",
            "description": "Role of the agent."
          },
          "description": {
            "type": "string",
            "description": "Description of the agent."
          },
          "vectorStoreId": {
            "type": "string",
            "description": "OpenAI vector store ID.",
            "example": "vs_1234567890"
          },
          "aiConfig": {
            "description": "Agent AI config.",
            "allOf": [
              {
                "$ref": "#/components/schemas/AIConfigResponseDTO"
              }
            ]
          },
          "avatarUrl": {
            "type": "string",
            "description": "Avatar URL of the agent.",
            "example": "https://example.com/avatar.jpg"
          },
          "status": {
            "type": "string",
            "description": "Status of the agent.",
            "enum": [
              "active",
              "inactive",
              "draft"
            ]
          },
          "tags": {
            "description": "Agent tags.",
            "nullable": true,
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "skills": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/BaseSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/LiveChatSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/SmsSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/EmailSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/WebhookSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/FunctionsSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/ScoringSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/APISkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/VoiceSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/MemorySkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/ReportSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/ScrapingSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/NotificationSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/ExternalRetrieversSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/FeedbackSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/EscalationSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/CalendarSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/DataRetentionSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/MsTeamsSkillResponseDTO"
                },
                {
                  "$ref": "#/components/schemas/SlackSkillResponseDTO"
                }
              ]
            },
            "description": "List of skills associated with the agent."
          },
          "restrictDocumentsToOwnerOnly": {
            "type": "boolean",
            "description": "Restrict documents to owner only.",
            "example": false
          }
        },
        "required": [
          "organizationId",
          "organizationName",
          "id",
          "name",
          "publicName",
          "role",
          "vectorStoreId",
          "aiConfig",
          "status",
          "skills"
        ]
      },
      "ExternalApiGetAgentStatisticResponseDTO": {
        "type": "object",
        "properties": {
          "tokensUsed": {
            "type": "number",
            "description": "Total number of tokens used by the agent in the given period."
          },
          "tokensPerConversation": {
            "type": "number",
            "description": "Number of tokens per conversations by the agent in the given period."
          },
          "vapiSecondsUsed": {
            "type": "number",
            "description": "Total number of vapi seconds used by the agent in the given period."
          },
          "averageCallDuration": {
            "type": "number",
            "description": "Number of vapi seconds per conversations by the agent in the given period."
          },
          "smsUsed": {
            "type": "number",
            "description": "Total number of sms used by the agent in the given period."
          },
          "smsPerConversation": {
            "type": "number",
            "description": "Number of sms per conversations by the agent in the given period."
          },
          "emailsUsed": {
            "type": "number",
            "description": "Total number of emails used by the agent in the given period."
          },
          "emailsPerConversation": {
            "type": "number",
            "description": "Number of emails per conversations by the agent in the given period."
          }
        },
        "required": [
          "tokensUsed",
          "tokensPerConversation",
          "vapiSecondsUsed",
          "averageCallDuration",
          "smsUsed",
          "smsPerConversation",
          "emailsUsed",
          "emailsPerConversation"
        ]
      },
      "CreateAgentWebhookBodyDTO": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "description": "Title of the webhook",
            "example": "My Webhook"
          },
          "description": {
            "type": "string",
            "description": "Description of the webhook",
            "example": "This webhook is triggered when a message is received"
          },
          "url": {
            "type": "string",
            "description": "Public HTTPS URL where the webhook will be sent. Local, private, reserved, and metadata-service addresses are not allowed.",
            "example": "https://api.example.com/webhook"
          },
          "triggerCondition": {
            "type": "string",
            "description": "Condition that triggers the webhook",
            "enum": [
              "each_message",
              "end_dialog",
              "start_dialog",
              "chat_currently_unavailable",
              "auto_archive_conversation",
              "manual"
            ],
            "example": "each_message"
          },
          "headers": {
            "type": "object",
            "description": "Optional headers to be sent with the webhook",
            "example": {
              "Authorization": "Bearer token"
            }
          }
        },
        "required": [
          "title",
          "description",
          "url",
          "triggerCondition"
        ]
      },
      "CreateAgentWebhookResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID of the created webhook",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          "agentId": {
            "type": "string",
            "description": "ID of the agent this webhook belongs to",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          "title": {
            "type": "string",
            "description": "Title of the webhook",
            "example": "My Webhook"
          },
          "description": {
            "type": "string",
            "description": "Description of the webhook",
            "example": "This webhook is triggered when a message is received"
          },
          "url": {
            "type": "string",
            "description": "URL where the webhook will be sent",
            "example": "https://api.example.com/webhook"
          },
          "triggerCondition": {
            "type": "string",
            "description": "Condition that triggers the webhook",
            "enum": [
              "each_message",
              "end_dialog",
              "start_dialog",
              "chat_currently_unavailable",
              "auto_archive_conversation",
              "manual"
            ],
            "example": "each_message"
          },
          "headers": {
            "type": "object",
            "description": "Optional headers to be sent with the webhook",
            "example": {
              "Authorization": "Bearer token"
            }
          },
          "status": {
            "type": "string",
            "description": "Status of the webhook",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Creation timestamp",
            "example": "2024-03-20T12:00:00Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Last update timestamp",
            "example": "2024-03-20T12:00:00Z"
          }
        },
        "required": [
          "id",
          "agentId",
          "title",
          "description",
          "url",
          "triggerCondition",
          "status",
          "createdAt",
          "updatedAt"
        ]
      },
      "AgentLimitsResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Unique identifier for the agent limits",
            "format": "uuid"
          },
          "agentId": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Unique identifier for the agent",
            "format": "uuid"
          },
          "isOrganizationDefault": {
            "type": "boolean",
            "example": true,
            "description": "Whether the agent limits are organization defaults"
          },
          "tokensAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Tokens amount per month"
          },
          "smsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "SMS amount per month"
          },
          "emailsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Emails amount per month"
          },
          "secondsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Seconds amount per month"
          }
        },
        "required": [
          "id",
          "agentId",
          "isOrganizationDefault",
          "tokensAmountPerMonth",
          "smsAmountPerMonth",
          "emailsAmountPerMonth",
          "secondsAmountPerMonth"
        ]
      },
      "CreateAgentLimitsBodyDTO": {
        "type": "object",
        "properties": {
          "tokensAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Tokens amount per month"
          },
          "smsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "SMS amount per month"
          },
          "emailsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Emails amount per month"
          },
          "secondsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Seconds amount per month"
          }
        },
        "required": [
          "tokensAmountPerMonth",
          "smsAmountPerMonth",
          "emailsAmountPerMonth",
          "secondsAmountPerMonth"
        ]
      },
      "UpdateAgentLimitsBodyDTO": {
        "type": "object",
        "properties": {
          "tokensAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Tokens amount per month"
          },
          "smsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "SMS amount per month"
          },
          "emailsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Emails amount per month"
          },
          "secondsAmountPerMonth": {
            "type": "number",
            "example": 1000,
            "description": "Seconds amount per month"
          }
        }
      },
      "AgentUsageResponseDTO": {
        "type": "object",
        "properties": {
          "emailsAmount": {
            "type": "number",
            "example": 1000,
            "description": "Emails amount"
          },
          "smsAmount": {
            "type": "number",
            "example": 1000,
            "description": "SMS amount"
          },
          "tokensAmount": {
            "type": "number",
            "example": 1000,
            "description": "Tokens amount"
          },
          "secondsAmount": {
            "type": "number",
            "example": 1000,
            "description": "Seconds amount"
          }
        },
        "required": [
          "emailsAmount",
          "smsAmount",
          "tokensAmount",
          "secondsAmount"
        ]
      },
      "UpdateAgentByApiKeyBodyDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the agent.",
            "example": "My agent"
          },
          "publicName": {
            "type": "string",
            "description": "Public name of the agent.",
            "example": "My agent"
          },
          "description": {
            "type": "string",
            "description": "Description of the agent.",
            "example": "My agent description"
          },
          "tags": {
            "description": "Tags of the agent.",
            "example": "[\"Sales\", \"Support\"]",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "avatarUrl": {
            "type": "string",
            "description": "Avatar URL of the agent.",
            "example": "https://example.com/avatar.jpg"
          },
          "backgroundUrl": {
            "type": "string",
            "description": "Background URL of the agent.",
            "example": "https://example.com/background.jpg"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive",
              "draft"
            ],
            "description": "Status of the agent.",
            "example": "active"
          },
          "instructions": {
            "type": "string",
            "description": "Instructions of the agent.",
            "example": "My agent instructions"
          },
          "model": {
            "type": "string",
            "description": "Model of the agent.",
            "example": "openai/gpt-5.1"
          },
          "topP": {
            "type": "number",
            "description": "TopP of the agent.",
            "example": 1
          },
          "temperature": {
            "type": "number",
            "description": "Temperature of the agent.",
            "example": 1
          },
          "reasoningEffort": {
            "type": "string",
            "enum": [
              "none",
              "minimal",
              "low",
              "medium",
              "high",
              "xhigh",
              "max"
            ],
            "description": "Reasoning effort of the agent.",
            "example": "medium"
          },
          "reasoningMode": {
            "type": "string",
            "enum": [
              "standard",
              "pro"
            ],
            "description": "Reasoning mode of the agent.",
            "example": "standard"
          },
          "defaultErrorMessage": {
            "type": "string",
            "description": "Default error message of the agent.",
            "example": "Sorry, something went wrong."
          },
          "isFileSearchEnabled": {
            "type": "boolean",
            "description": "Is file search enabled.",
            "example": false
          },
          "isCodeInterpreterEnabled": {
            "type": "boolean",
            "description": "Is code interpreter enabled.",
            "example": false
          },
          "fileSearchMaxNumResults": {
            "type": "number",
            "description": "File search max number of results. Required when isFileSearchEnabled is true.",
            "example": 10
          },
          "isOutputJsonSchemaEnabled": {
            "type": "boolean",
            "description": "Is output JSON schema enabled.",
            "example": false
          },
          "outputJsonSchema": {
            "type": "string",
            "description": "Output JSON schema of the agent.",
            "example": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}"
          },
          "restrictDocumentsToOwnerOnly": {
            "type": "boolean",
            "description": "Restrict documents to owner only.",
            "example": false
          }
        },
        "required": [
          "outputJsonSchema"
        ]
      },
      "AgentScrapResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "5f7b1b3b-3b3b-4b3b-8b3b-3b3b3b3b3b3b"
          },
          "url": {
            "type": "string",
            "example": "https://inverclydeleisure.com"
          },
          "crawlerType": {
            "type": "string",
            "enum": [
              "FIRECRAWL",
              "APIFY"
            ],
            "example": "FIRECRAWL"
          },
          "crawlFormat": {
            "type": "string",
            "enum": [
              "JSON",
              "MARKDOWN",
              "HTML",
              "CONTENT"
            ],
            "example": "MARKDOWN"
          },
          "excludeUrls": {
            "nullable": true,
            "example": [
              "/admin"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pageLimit": {
            "type": "number",
            "example": 30
          },
          "maxDepth": {
            "type": "number",
            "example": 3
          },
          "frequency": {
            "type": "string",
            "enum": [
              "manual",
              "daily",
              "weekly",
              "monthly"
            ],
            "example": "daily"
          },
          "autoUpload": {
            "type": "boolean",
            "example": true
          },
          "crawlingStatus": {
            "type": "string",
            "enum": [
              "not_started",
              "in_progress",
              "completed",
              "failed",
              "canceled"
            ],
            "example": "completed"
          },
          "startCrawledAt": {
            "type": "object",
            "nullable": true,
            "example": "2026-07-14T09:00:00.000Z"
          },
          "endCrawledAt": {
            "type": "object",
            "nullable": true,
            "example": "2026-07-14T09:05:00.000Z"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "example": "2026-07-14T09:00:00.000Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "example": "2026-07-14T09:05:00.000Z"
          }
        },
        "required": [
          "id",
          "url",
          "crawlerType",
          "crawlFormat",
          "excludeUrls",
          "pageLimit",
          "maxDepth",
          "frequency",
          "autoUpload",
          "crawlingStatus",
          "startCrawledAt",
          "endCrawledAt",
          "createdAt",
          "updatedAt"
        ]
      },
      "CreateAgentScrapBodyDTO": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "URL to crawl. Must be a publicly reachable http(s) URL; private, loopback, link-local, and metadata hosts are rejected.",
            "example": "https://inverclydeleisure.com"
          },
          "crawlerType": {
            "type": "string",
            "enum": [
              "FIRECRAWL",
              "APIFY"
            ],
            "description": "Crawler engine to use.",
            "default": "FIRECRAWL"
          },
          "crawlFormat": {
            "type": "string",
            "enum": [
              "JSON",
              "MARKDOWN",
              "HTML",
              "CONTENT"
            ],
            "description": "Output format for crawled content.",
            "default": "MARKDOWN"
          },
          "excludeUrls": {
            "description": "URL patterns to exclude from the crawl.",
            "nullable": true,
            "example": [
              "/admin",
              "/login"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pageLimit": {
            "type": "number",
            "description": "Maximum number of pages to crawl.",
            "minimum": 1,
            "maximum": 3000,
            "default": 10
          },
          "maxDepth": {
            "type": "number",
            "description": "Maximum link depth to follow from the root URL.",
            "minimum": 1,
            "maximum": 5,
            "default": 2
          },
          "frequency": {
            "type": "string",
            "enum": [
              "manual",
              "daily",
              "weekly",
              "monthly"
            ],
            "description": "How often to automatically re-crawl the URL.",
            "default": "daily"
          },
          "autoUpload": {
            "type": "boolean",
            "description": "When true, crawled content is automatically uploaded to the agent knowledge base after each crawl.",
            "default": true
          }
        },
        "required": [
          "url"
        ]
      },
      "UpdateAgentScrapBodyDTO": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "URL to crawl. Changing this triggers a new crawl immediately. Must be a publicly reachable http(s) URL; private, loopback, link-local, and metadata hosts are rejected."
          },
          "crawlerType": {
            "type": "string",
            "enum": [
              "FIRECRAWL",
              "APIFY"
            ],
            "description": "Crawler engine to use."
          },
          "crawlFormat": {
            "type": "string",
            "enum": [
              "JSON",
              "MARKDOWN",
              "HTML",
              "CONTENT"
            ],
            "description": "Output format for crawled content."
          },
          "excludeUrls": {
            "description": "URL patterns to exclude from the crawl. Set to null to clear existing patterns.",
            "nullable": true,
            "example": [
              "/admin",
              "/login"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pageLimit": {
            "type": "number",
            "description": "Maximum number of pages to crawl.",
            "minimum": 1,
            "maximum": 3000
          },
          "maxDepth": {
            "type": "number",
            "description": "Maximum link depth to follow from the root URL.",
            "minimum": 1,
            "maximum": 5
          },
          "frequency": {
            "type": "string",
            "enum": [
              "manual",
              "daily",
              "weekly",
              "monthly"
            ],
            "description": "How often to automatically re-crawl the URL."
          },
          "autoUpload": {
            "type": "boolean",
            "description": "When true, crawled content is automatically uploaded to the agent knowledge base after each crawl."
          }
        }
      },
      "CreateAgentApiKeyBodyDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Label for the API key.",
            "example": "Production key"
          },
          "expiresAt": {
            "type": "string",
            "description": "Expiry date in ISO 8601 format (YYYY-MM-DD).",
            "example": "2027-01-01"
          }
        },
        "required": [
          "name",
          "expiresAt"
        ]
      },
      "CreateAgentApiKeyResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the API key.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "name": {
            "type": "string",
            "description": "Label for the API key.",
            "example": "Production key"
          },
          "keyPreview": {
            "type": "string",
            "description": "Masked preview of the API key. The full key is only returned when the key is created or rotated.",
            "example": "raia_*******_abcd"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "expired",
              "revoked"
            ],
            "description": "Current status of the API key.",
            "example": "active"
          },
          "expiresAt": {
            "type": "string",
            "nullable": true,
            "description": "Expiry date of the API key (YYYY-MM-DD). Null if the key does not expire.",
            "example": "2027-01-01"
          },
          "revokedAt": {
            "type": "string",
            "nullable": true,
            "description": "Timestamp when the API key was revoked. Null if the key is still active.",
            "example": null
          },
          "createdAt": {
            "type": "string",
            "description": "Timestamp when the API key was created.",
            "example": "2026-07-14T09:00:00.000Z"
          },
          "agentApiKey": {
            "type": "string",
            "description": "The full API key. This value is returned only once — at creation or rotation. Store it securely; it cannot be retrieved again.",
            "example": "raia_550e8400-e29b-41d4-a716-446655440000"
          }
        },
        "required": [
          "id",
          "name",
          "keyPreview",
          "status",
          "expiresAt",
          "revokedAt",
          "createdAt",
          "agentApiKey"
        ]
      },
      "AgentApiKeyResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the API key.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "name": {
            "type": "string",
            "description": "Label for the API key.",
            "example": "Production key"
          },
          "keyPreview": {
            "type": "string",
            "description": "Masked preview of the API key. The full key is only returned when the key is created or rotated.",
            "example": "raia_*******_abcd"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "expired",
              "revoked"
            ],
            "description": "Current status of the API key.",
            "example": "active"
          },
          "expiresAt": {
            "type": "string",
            "nullable": true,
            "description": "Expiry date of the API key (YYYY-MM-DD). Null if the key does not expire.",
            "example": "2027-01-01"
          },
          "revokedAt": {
            "type": "string",
            "nullable": true,
            "description": "Timestamp when the API key was revoked. Null if the key is still active.",
            "example": null
          },
          "createdAt": {
            "type": "string",
            "description": "Timestamp when the API key was created.",
            "example": "2026-07-14T09:00:00.000Z"
          }
        },
        "required": [
          "id",
          "name",
          "keyPreview",
          "status",
          "expiresAt",
          "revokedAt",
          "createdAt"
        ]
      },
      "UploadAgentFileBodyDTO": {
        "type": "object",
        "properties": {
          "file": {
            "type": "string",
            "format": "binary",
            "description": "The file to upload"
          },
          "autoAddToVectorStore": {
            "type": "boolean",
            "example": true,
            "description": "Indicates whether to automatically add the file to the vector store."
          }
        },
        "required": [
          "file"
        ]
      },
      "UploadAgentFileResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Unique identifier for the agent file",
            "format": "uuid"
          },
          "fileName": {
            "type": "string",
            "example": "example.txt",
            "description": "Name of the agent file"
          },
          "url": {
            "type": "string",
            "example": "https://example.com/file.txt",
            "description": "URL of the agent file"
          },
          "createdAt": {
            "type": "string",
            "example": "2023-10-01T12:00:00Z",
            "description": "Creation date of the agent file",
            "format": "date-time"
          },
          "vectorStoreFileId": {
            "type": "string",
            "example": "file-123e4567-e89b",
            "description": "Unique identifier for the vector store file"
          },
          "isUploadedToVectorStore": {
            "type": "boolean",
            "example": true,
            "description": "Indicates the file’s upload status to the vector store. A null value suggests a possible vector store error.",
            "nullable": true
          },
          "vectorStoreUploadStatus": {
            "type": "string",
            "enum": [
              "processing",
              "done",
              "failed"
            ],
            "example": "done",
            "description": "Lifecycle status of the file upload to the OpenAI vector store. `null` means not uploaded, `processing` means an upload is in progress, `done` means the upload is complete.",
            "nullable": true
          },
          "uploadedToVectorStoreAt": {
            "type": "string",
            "example": "2023-10-01T12:00:00Z",
            "description": "Date when the file was uploaded to the vector store",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "fileName",
          "url",
          "createdAt"
        ]
      },
      "AgentFileResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Unique identifier for the agent file",
            "format": "uuid"
          },
          "fileName": {
            "type": "string",
            "example": "example.txt",
            "description": "Name of the agent file"
          },
          "url": {
            "type": "string",
            "example": "https://example.com/file.txt",
            "description": "URL of the agent file"
          },
          "createdAt": {
            "type": "string",
            "example": "2023-10-01T12:00:00Z",
            "description": "Creation date of the agent file",
            "format": "date-time"
          },
          "vectorStoreFileId": {
            "type": "string",
            "example": "file-123e4567-e89b",
            "description": "Unique identifier for the vector store file"
          },
          "isUploadedToVectorStore": {
            "type": "boolean",
            "example": true,
            "description": "Indicates the file’s upload status to the vector store. A null value suggests a possible vector store error.",
            "nullable": true
          },
          "vectorStoreUploadStatus": {
            "type": "string",
            "enum": [
              "processing",
              "done",
              "failed"
            ],
            "example": "done",
            "description": "Lifecycle status of the file upload to the OpenAI vector store. `null` means not uploaded, `processing` means an upload is in progress, `done` means the upload is complete.",
            "nullable": true
          },
          "uploadedToVectorStoreAt": {
            "type": "string",
            "example": "2023-10-01T12:00:00Z",
            "description": "Date when the file was uploaded to the vector store",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "fileName",
          "url",
          "createdAt"
        ]
      },
      "GetAgentFilesPaginatedByApiKeyResponseDTO": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "number",
            "description": "Current page"
          },
          "pageSize": {
            "type": "number",
            "description": "Page size"
          },
          "totalItems": {
            "type": "number",
            "description": "Total items"
          },
          "totalPages": {
            "type": "number",
            "description": "Total pages"
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Has next page"
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Has previous page"
          },
          "data": {
            "description": "Agent files for the requested page.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentFileResponseDTO"
            }
          }
        },
        "required": [
          "currentPage",
          "pageSize",
          "totalItems",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage",
          "data"
        ]
      },
      "DeleteAgentFilesBodyDTO": {
        "type": "object",
        "properties": {
          "fileIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        },
        "required": [
          "fileIds"
        ]
      },
      "AgentFunctionResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "agentId": {
            "type": "string",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "name": {
            "type": "string",
            "example": "check_availability"
          },
          "description": {
            "type": "string",
            "example": "Check real-time availability for activities."
          },
          "url": {
            "type": "string",
            "example": "https://hooks.example.com/webhook/gladstone-api"
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "example": "GET"
          },
          "definition": {
            "type": "object",
            "description": "JSON Schema for the function parameters."
          },
          "headersConfigured": {
            "type": "boolean",
            "description": "Whether custom headers are configured on this function. Header values are never returned.",
            "example": true
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "example": "2026-07-14T09:00:00.000Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "example": "2026-07-14T09:00:00.000Z"
          }
        },
        "required": [
          "id",
          "agentId",
          "name",
          "description",
          "url",
          "method",
          "definition",
          "headersConfigured",
          "status",
          "createdAt",
          "updatedAt"
        ]
      },
      "CreateAgentFunctionBodyDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Display name for the function.",
            "example": "check_availability"
          },
          "internalName": {
            "type": "string",
            "description": "Stable internal identifier the agent runtime uses to reference this function. Must be unique per agent and match /[a-zA-Z0-9_-]/, max 64 characters. Unlike the display name it is not derived and does not change when the name changes.",
            "example": "check_availability"
          },
          "description": {
            "type": "string",
            "description": "Human-readable description of what the function does. The agent uses this to decide when to call it.",
            "example": "Check real-time availability for activities and tour slots at the operator site."
          },
          "url": {
            "type": "string",
            "description": "HTTPS URL the agent will invoke using the configured HTTP method.",
            "example": "https://hooks.example.com/webhook/gladstone-api"
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "default": "POST",
            "description": "HTTP method used to invoke the endpoint. GET sends function arguments as query parameters; POST sends them as a JSON body.",
            "example": "GET"
          },
          "definition": {
            "type": "object",
            "description": "JSON Schema object defining the parameters the agent sends when calling this function. Must be a valid JSON Schema (type: object with properties).",
            "example": "{\"type\":\"object\",\"properties\":{\"action\":{\"type\":\"string\",\"enum\":[\"check_availability\"]},\"siteId\":{\"type\":\"string\"}},\"required\":[\"action\",\"siteId\"]}"
          },
          "headers": {
            "type": "object",
            "description": "HTTP headers sent with every function call. Values are write-only — they are never returned in GET responses. Use for auth tokens or shared secrets.",
            "example": {
              "x-webhook-secret": "my-secret-token"
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Initial status of the function.",
            "default": "active"
          }
        },
        "required": [
          "name",
          "internalName",
          "description",
          "url",
          "definition"
        ]
      },
      "UpdateAgentFunctionBodyDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Display name for the function."
          },
          "internalName": {
            "type": "string",
            "description": "Stable internal identifier for the function. Must be unique per agent and match /[a-zA-Z0-9_-]/, max 64 characters."
          },
          "description": {
            "type": "string",
            "description": "Description of what the function does."
          },
          "url": {
            "type": "string",
            "description": "HTTPS URL the agent will invoke using the configured HTTP method."
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "description": "HTTP method used to invoke the endpoint. GET sends function arguments as query parameters; POST sends them as a JSON body.",
            "example": "GET"
          },
          "definition": {
            "type": "object",
            "description": "JSON Schema for function parameters.",
            "example": "{\"type\":\"object\",\"properties\":{\"action\":{\"type\":\"string\"}},\"required\":[\"action\"]}"
          },
          "headers": {
            "type": "object",
            "description": "Replaces all existing headers. Pass an empty object {} to clear headers. Values are write-only and never returned in GET responses."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ]
          }
        }
      },
      "AgentLiveChatResponseDTO": {
        "type": "object",
        "properties": {
          "systemName": {
            "type": "string",
            "description": "System name of the skill.",
            "enum": [
              "LIVE_CHAT",
              "SMS",
              "EMAIL",
              "WEBHOOK",
              "FUNCTION",
              "SCORING",
              "API",
              "VOICE",
              "MEMORY",
              "AGENT_REPORT",
              "SCRAPING",
              "NOTIFICATIONS",
              "EXTERNAL_RETRIEVERS",
              "WEB_SEARCH",
              "FEEDBACK",
              "ESCALATION",
              "CALENDAR",
              "AUDITOR",
              "COPILOT",
              "MCP",
              "ENHANCED_PROMPTING",
              "SLACK",
              "DATA_RETENTION",
              "ORCHESTRATOR",
              "MS_TEAMS",
              "MESSAGE_QUOTA"
            ],
            "example": "AGENT_SKILL_SYSTEM_NAME"
          },
          "status": {
            "type": "string",
            "description": "Status of the email skill.",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "color": {
            "type": "string",
            "description": "Color of the chat widget.",
            "example": "#5D6169"
          },
          "widgetButtonConfig": {
            "description": "Embedded chat launcher (widget button) settings with legacy fields normalized.",
            "allOf": [
              {
                "$ref": "#/components/schemas/LiveChatWidgetButtonExternalDTO"
              }
            ]
          },
          "titleLine1": {
            "type": "string",
            "description": "First line of the chat widget title.",
            "example": ""
          },
          "titleLine2": {
            "type": "string",
            "description": "Second line of the chat widget title.",
            "example": "Hello, how can I help you?"
          },
          "intro": {
            "type": "string",
            "description": "Default introduction message (same as titleLine2; kept for backwards compatibility).",
            "example": "Hello, how can I help you?"
          },
          "links": {
            "description": "List of links to be displayed in the chat widget.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LiveChatLinkExternalDTO"
            }
          },
          "disclaimer": {
            "type": "string",
            "description": "Disclaimer message.",
            "example": "This is a disclaimer message."
          },
          "chatFooterContent": {
            "type": "string",
            "description": "Chat footer content below the input (e.g. privacy policy)",
            "example": "By chatting with us, you agree to our [Privacy Policy](https://example.com/privacy)."
          },
          "suggestions": {
            "description": "List of suggestions for the chat widget.",
            "example": [
              "Suggestion 1",
              "Suggestion 2",
              "Suggestion 3"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "whitelistedIps": {
            "description": "List of IP addresses that are whitelisted.",
            "example": [
              "192.168.1.1",
              "192.168.1.2"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "restrictedCountries": {
            "description": "List of countries that are restricted.",
            "example": [
              "US",
              "CA",
              "GB"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "limitUnavailableDates": {
            "type": "boolean",
            "description": "Whether live chat should be unavailable on the configured unavailableDates (YYYY-MM-DD).",
            "example": false
          },
          "unavailableDates": {
            "description": "Dates (YYYY-MM-DD) when live chat is unavailable (e.g. holidays, maintenance).",
            "example": [
              "2026-01-01",
              "2026-12-25"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "unavailableDatesMessage": {
            "type": "string",
            "description": "Custom message to show when live chat is unavailable on unavailableDates.",
            "example": "Chat is unavailable today. Please come back tomorrow."
          },
          "agentId": {
            "type": "string",
            "description": "Unique identifier of the agent.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "embedKey": {
            "type": "string",
            "description": "Public, non-secret identifier used to embed the live chat widget on a website. Safe to include in client-side code. Generated the first time the skill is configured.",
            "example": "9c2e1a4d-6f3b-4e2a-8b1c-2d5e7f9a0b3c"
          },
          "welcomeMessage": {
            "type": "string",
            "description": "Welcome message shown when the chat widget opens.",
            "example": "How can I help you?"
          },
          "avatarUrl": {
            "type": "string",
            "description": "Avatar image URL for the chat widget.",
            "nullable": true,
            "example": "https://storage.example/acme-avatar.png"
          }
        },
        "required": [
          "systemName",
          "status",
          "limitUnavailableDates",
          "unavailableDates",
          "unavailableDatesMessage",
          "agentId",
          "embedKey"
        ]
      },
      "LiveChatLinkBodyDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Label displayed for the link.",
            "example": "Privacy Policy"
          },
          "url": {
            "type": "string",
            "description": "Absolute URL opened when the link is selected.",
            "example": "https://example.com/privacy"
          }
        },
        "required": [
          "name",
          "url"
        ]
      },
      "UpdateAgentLiveChatBodyDTO": {
        "type": "object",
        "properties": {
          "titleLine1": {
            "type": "string",
            "description": "First line of the chat widget title.",
            "example": "Acme Support"
          },
          "titleLine2": {
            "type": "string",
            "description": "Second line of the chat widget title.",
            "example": "How can I help you?"
          },
          "welcomeMessage": {
            "type": "string",
            "description": "Welcome message shown when the chat widget opens.",
            "example": "Hi! What can I help you with today?"
          },
          "avatarStoragePath": {
            "type": "string",
            "description": "Storage path returned by the image upload-url endpoint. The API converts it to a public URL before saving the live chat configuration. Pass null to remove the avatar.",
            "nullable": true,
            "example": "550e8400-e29b-41d4-a716-446655440000_acme-avatar.png"
          },
          "color": {
            "type": "string",
            "description": "Primary color of the chat widget.",
            "example": "#162A43"
          },
          "disclaimer": {
            "type": "string",
            "description": "Disclaimer message shown in the widget."
          },
          "chatFooterContent": {
            "type": "string",
            "description": "Chat footer content below the input (e.g. privacy policy)."
          },
          "suggestions": {
            "description": "Suggested prompts shown in the widget.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "links": {
            "description": "Links displayed in the chat widget. Pass an empty array to remove all links.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LiveChatLinkBodyDTO"
            }
          },
          "whitelistedIps": {
            "description": "Whitelisted IP addresses.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "restrictedCountries": {
            "description": "Restricted country codes.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "limitUnavailableDates": {
            "type": "boolean",
            "description": "Whether live chat should be unavailable on unavailableDates."
          },
          "unavailableDates": {
            "description": "Dates (YYYY-MM-DD) when live chat is unavailable.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "unavailableDatesMessage": {
            "type": "string",
            "description": "Message shown when live chat is unavailable on unavailableDates."
          }
        }
      },
      "CreateAgentImageUploadUrlBodyDTO": {
        "type": "object",
        "properties": {
          "fileName": {
            "type": "string",
            "description": "Name of the file to upload.",
            "example": "acme-avatar.png"
          },
          "contentType": {
            "type": "string",
            "enum": [
              "image/png",
              "image/jpeg",
              "image/gif",
              "image/webp"
            ],
            "description": "MIME type of the file to upload.",
            "example": "image/png"
          }
        },
        "required": [
          "fileName",
          "contentType"
        ]
      },
      "AgentImageUploadUrlResponseDTO": {
        "type": "object",
        "properties": {
          "signedUrl": {
            "type": "string",
            "description": "Signed URL to PUT the file contents to.",
            "example": "https://storage-provider/..."
          },
          "storagePath": {
            "type": "string",
            "description": "Storage path for the uploaded file. Supply this as avatarStoragePath to the live chat update endpoint once the upload completes.",
            "example": "550e8400-e29b-41d4-a716-446655440000_acme-avatar.png"
          }
        },
        "required": [
          "signedUrl",
          "storagePath"
        ]
      },
      "CreateResourceUsageLogsBodyDto": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "LLM_TOKENS",
              "VAPI_SECONDS"
            ],
            "description": "The type of resource consumed",
            "example": "LLM_TOKENS"
          },
          "amount": {
            "type": "number",
            "description": "The amount of resource consumed.",
            "example": 4567
          },
          "inputTokens": {
            "type": "number",
            "description": "Number of input tokens consumed.",
            "example": 3000
          },
          "outputTokens": {
            "type": "number",
            "description": "Number of output tokens consumed.",
            "example": 1567
          },
          "reasoningTokens": {
            "type": "number",
            "description": "Number of reasoning tokens included in the output.",
            "example": 500
          },
          "modelProvider": {
            "type": "string",
            "description": "Provider of the model used for the request.",
            "example": "OpenAI",
            "nullable": true
          },
          "model": {
            "type": "string",
            "description": "Model used for the request.",
            "example": "openai/gpt-5",
            "nullable": true
          },
          "reasoningEffort": {
            "type": "string",
            "description": "Reasoning effort used for the request.",
            "example": "medium",
            "nullable": true
          },
          "reasoningMode": {
            "type": "string",
            "description": "Reasoning mode used for the request.",
            "example": "enabled",
            "nullable": true
          }
        },
        "required": [
          "type",
          "amount"
        ]
      },
      "GetAgentRoleByApiKeyResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "description": "Unique identifier for the agent role.",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Name of the agent role."
          },
          "description": {
            "type": "string",
            "description": "Description of the agent role."
          }
        },
        "required": [
          "id",
          "name",
          "description"
        ]
      },
      "ExternalApiOrganizationLlmModelResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Organization model access record ID.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "modelId": {
            "type": "string",
            "description": "Allowed model ID.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "modelName": {
            "type": "string",
            "description": "OpenRouter-compatible model name.",
            "example": "openai/gpt-5.6-luna"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "archived"
            ],
            "description": "Access status for the organization model.",
            "example": "active"
          },
          "isDefault": {
            "type": "boolean",
            "description": "Whether this is the organization default model.",
            "example": true
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Timestamp when the organization model access was created.",
            "example": "2026-01-15T12:00:00Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Timestamp when the organization model access was last updated.",
            "example": "2026-01-15T12:00:00Z"
          }
        },
        "required": [
          "id",
          "modelId",
          "modelName",
          "status",
          "isDefault",
          "createdAt",
          "updatedAt"
        ]
      },
      "ExternalApiCreatedByDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID of the creator.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "email": {
            "type": "string",
            "description": "Email of the creator.",
            "example": "test@test.com"
          },
          "firstName": {
            "type": "string",
            "description": "First name of the creator.",
            "example": "UserFN"
          },
          "lastName": {
            "type": "string",
            "description": "Last name of the creator.",
            "example": "UserLN"
          }
        },
        "required": [
          "id",
          "email",
          "firstName",
          "lastName"
        ]
      },
      "ExternalApiSubscriptionResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Subscription ID.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "title": {
            "type": "string",
            "description": "Subscription title.",
            "example": "Subscription title"
          },
          "description": {
            "type": "string",
            "description": "Subscription description.",
            "example": "Subscription description"
          },
          "agentsAmount": {
            "type": "number",
            "description": "Number of agents in the subscription.",
            "example": 10
          },
          "tokensAmountPerMonth": {
            "type": "number",
            "description": "OpenAI tokens amount in the subscription.",
            "example": 1000000
          },
          "secondsAmountPerMonth": {
            "type": "number",
            "description": "Vapi seconds amount in the subscription.",
            "example": 1000000
          },
          "smsAmountPerMonth": {
            "type": "number",
            "description": "Number of SMS in the subscription.",
            "example": 1000
          },
          "emailsAmountPerMonth": {
            "type": "number",
            "description": "Number of Emails in the subscription.",
            "example": 1000
          },
          "usersWithAccessAmount": {
            "type": "number",
            "description": "Number of users in organizations.",
            "example": 100
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Subscription status.",
            "example": "active"
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ],
            "description": "Subscription visibility.",
            "example": "public"
          },
          "isTrial": {
            "type": "boolean",
            "description": "True if subscription is trial.",
            "example": false
          },
          "createdBy": {
            "description": "Created by.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiCreatedByDTO"
              }
            ]
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Creation timestamp",
            "example": "2024-03-20T12:00:00Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Last update timestamp",
            "example": "2024-03-20T12:00:00Z"
          },
          "organizationsCount": {
            "type": "number",
            "description": "Number of organizations with current subscription.",
            "example": 100
          },
          "price": {
            "type": "number",
            "description": "Subscription in cent.",
            "example": 49900
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "agentsAmount",
          "tokensAmountPerMonth",
          "secondsAmountPerMonth",
          "smsAmountPerMonth",
          "emailsAmountPerMonth",
          "usersWithAccessAmount",
          "status",
          "visibility",
          "isTrial",
          "createdBy",
          "createdAt",
          "updatedAt",
          "organizationsCount",
          "price"
        ]
      },
      "ExternalApiOrganizationWithSubscriptionResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Organization ID.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Organization name.",
            "example": "New Organization"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "pending",
              "archived",
              "blocked"
            ],
            "description": "Organization status.",
            "example": "active"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Creation timestamp",
            "example": "2024-03-20T12:00:00Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Last update timestamp",
            "example": "2024-03-20T12:00:00Z"
          },
          "createdBy": {
            "description": "Created by.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiCreatedByDTO"
              }
            ]
          },
          "subscription": {
            "nullable": true,
            "description": "Organization subscription, or null when the organization has no subscription.",
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiSubscriptionResponseDTO"
              }
            ]
          },
          "agentsCount": {
            "type": "number",
            "description": "Number of agents in the organization.",
            "example": 3
          }
        },
        "required": [
          "id",
          "name",
          "status",
          "createdAt",
          "updatedAt",
          "createdBy",
          "subscription",
          "agentsCount"
        ]
      },
      "ExternalApiGetAllOrganizationsResponseDTO": {
        "type": "object",
        "properties": {
          "currentPage": {
            "type": "number",
            "description": "Current page"
          },
          "pageSize": {
            "type": "number",
            "description": "Page size"
          },
          "totalItems": {
            "type": "number",
            "description": "Total items"
          },
          "totalPages": {
            "type": "number",
            "description": "Total pages"
          },
          "hasNextPage": {
            "type": "boolean",
            "description": "Has next page"
          },
          "hasPreviousPage": {
            "type": "boolean",
            "description": "Has previous page"
          },
          "data": {
            "description": "Organizations for the requested page.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalApiOrganizationWithSubscriptionResponseDTO"
            }
          }
        },
        "required": [
          "currentPage",
          "pageSize",
          "totalItems",
          "totalPages",
          "hasNextPage",
          "hasPreviousPage",
          "data"
        ]
      },
      "ExternalApiInviteUserBodyDTO": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "Invited user email.",
            "example": "test@test.com",
            "minLength": 4,
            "maxLength": 255
          },
          "role": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "manager",
              "user",
              "copilot_user",
              "copilot_admin",
              "guest"
            ],
            "description": "Invited user role.",
            "example": "user"
          }
        },
        "required": [
          "email",
          "role"
        ]
      },
      "ExternalApiCreateOrganizationByApiKeyBodyDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Organization name.",
            "example": "New Organization",
            "maxLength": 255
          },
          "users": {
            "description": "List of invited users.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalApiInviteUserBodyDTO"
            }
          },
          "licenseKey": {
            "type": "string",
            "description": "Organization license key.",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          "endedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Subscription end date. Applies if \"subscriptionId\" is specified and this subscription is not a trial.",
            "example": "2024-03-20T12:00:00Z"
          }
        },
        "required": [
          "name",
          "users",
          "licenseKey"
        ]
      },
      "ExternalApiGetOrganizationResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Organization ID.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "description": "Organization name.",
            "example": "New Organization"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "pending",
              "archived",
              "blocked"
            ],
            "description": "Organization status.",
            "example": "active"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Creation timestamp",
            "example": "2024-03-20T12:00:00Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Last update timestamp",
            "example": "2024-03-20T12:00:00Z"
          },
          "createdBy": {
            "description": "Created by.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiCreatedByDTO"
              }
            ]
          },
          "subscription": {
            "description": "Organization subscription.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiSubscriptionResponseDTO"
              }
            ]
          }
        },
        "required": [
          "id",
          "name",
          "status",
          "createdAt",
          "updatedAt",
          "createdBy",
          "subscription"
        ]
      },
      "ExternalApiCreateOrganizationByOrganizationApiKeyBodyDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Name of the new organization.",
            "example": "New Organization",
            "maxLength": 255
          },
          "licenseKey": {
            "type": "string",
            "description": "License key the new organization is created under.",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          },
          "ownerUserId": {
            "type": "string",
            "description": "ID of a user in the calling organization who will own the new organization. Defaults to the calling organization creator.",
            "example": "123e4567-e89b-12d3-a456-426614174000"
          }
        },
        "required": [
          "name",
          "licenseKey"
        ]
      },
      "ExternalApiCrateOrUpdateConversationMessageFeedbackBodyDTO": {
        "type": "object",
        "properties": {
          "conversationMessageId": {
            "type": "string",
            "description": "Unique identifier for the conversation message.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "userId": {
            "type": "string",
            "description": "Unique identifier for the user.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "voteType": {
            "type": "string",
            "enum": [
              "up",
              "down"
            ],
            "description": "Feedback vote type. Up if feedback is positive",
            "example": "up"
          },
          "question": {
            "type": "string",
            "description": "Your question."
          },
          "answer": {
            "type": "string",
            "description": "Agent answer."
          },
          "comment": {
            "type": "string",
            "description": "Comment for your feedback.",
            "example": "Awesome :)"
          }
        },
        "required": [
          "conversationMessageId",
          "userId",
          "voteType",
          "question"
        ]
      },
      "ExternalApiCrateOrUpdateConversationMessageFeedbackResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the conversation message feedback.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "conversationMessageId": {
            "type": "string",
            "description": "Unique identifier for the conversation message.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "format": "uuid"
          },
          "voteType": {
            "type": "string",
            "enum": [
              "up",
              "down"
            ],
            "description": "Feedback vote type. Up if feedback is positive",
            "example": "up"
          },
          "question": {
            "type": "string",
            "description": "Your question.",
            "nullable": true
          },
          "answer": {
            "type": "string",
            "description": "Agent answer.",
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "description": "Feedback created at",
            "example": "2023-01-01T00:00:00.000Z"
          },
          "updatedAt": {
            "type": "string",
            "description": "Feedback updated at",
            "example": "2023-01-01T00:00:00.000Z"
          },
          "comment": {
            "type": "string",
            "description": "Comment for your feedback.",
            "example": "Awesome :)",
            "nullable": true
          }
        },
        "required": [
          "id",
          "conversationMessageId",
          "voteType",
          "question",
          "answer",
          "createdAt",
          "updatedAt",
          "comment"
        ]
      },
      "GetAllOrganizationPlatformUsersResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "test@test.com"
          },
          "phoneNumber": {
            "type": "string",
            "description": "User phone number",
            "example": "+1234567890"
          },
          "firstName": {
            "type": "string",
            "description": "User first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "User last name",
            "example": "Doe"
          },
          "organizationRole": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "manager",
              "user",
              "copilot_user",
              "copilot_admin",
              "guest"
            ],
            "description": "Role of the user in the organization.",
            "example": "user"
          },
          "organizationStatus": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Status of the user's membership in the organization.",
            "example": "active"
          }
        },
        "required": [
          "id",
          "email",
          "phoneNumber",
          "firstName",
          "lastName",
          "organizationRole",
          "organizationStatus"
        ]
      },
      "ExternalApiPlatformUserSummaryDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "user@example.com"
          },
          "firstName": {
            "type": "string",
            "description": "User first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "User last name",
            "example": "Doe"
          },
          "organizationRole": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "manager",
              "user",
              "copilot_user",
              "copilot_admin",
              "guest"
            ],
            "description": "Role of the user in the organization.",
            "example": "user"
          },
          "organizationStatus": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Status of the user's membership in the organization.",
            "example": "active"
          }
        },
        "required": [
          "id",
          "email",
          "firstName",
          "lastName",
          "organizationRole",
          "organizationStatus"
        ]
      },
      "ExternalApiPlatformUserAgentAccessDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Agent ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "name": {
            "type": "string",
            "description": "Agent name",
            "example": "Support Agent"
          },
          "publicName": {
            "type": "string",
            "description": "Agent public name",
            "example": "Support Agent"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive",
              "draft"
            ],
            "description": "Agent status",
            "example": "active"
          },
          "avatarUrl": {
            "type": "string",
            "nullable": true,
            "description": "Agent avatar URL",
            "example": "https://storage.example.com/avatars/agent.png"
          },
          "agentRole": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "editor",
              "user",
              "copilot_user",
              "copilot_admin"
            ],
            "nullable": true,
            "description": "Role assigned to the user directly on the agent. Null when access is granted only by an organization-level role.",
            "example": "admin"
          },
          "agentAccessStatus": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "nullable": true,
            "description": "Status of the direct user-to-agent assignment. Null when the user has no direct agent assignment.",
            "example": "active"
          },
          "accessSource": {
            "type": "string",
            "enum": [
              "agent",
              "organization"
            ],
            "description": "Whether access comes from a direct role on the agent or from an owner or admin role in the organization that owns the agent.",
            "example": "agent"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Agent creation date",
            "example": "2024-01-01T00:00:00.000Z"
          }
        },
        "required": [
          "id",
          "name",
          "publicName",
          "status",
          "accessSource",
          "createdAt"
        ]
      },
      "GetAgentsByPlatformUserResponseDTO": {
        "type": "object",
        "properties": {
          "user": {
            "description": "The platform user the agents belong to.",
            "allOf": [
              {
                "$ref": "#/components/schemas/ExternalApiPlatformUserSummaryDTO"
              }
            ]
          },
          "agents": {
            "description": "Agents the user has access to, with access control data.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExternalApiPlatformUserAgentAccessDTO"
            }
          }
        },
        "required": [
          "user",
          "agents"
        ]
      },
      "UpdateOrganizationPlatformUserBodyDTO": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "admin",
              "manager",
              "user",
              "copilot_user",
              "copilot_admin",
              "guest"
            ],
            "description": "New role of the user in the organization. The owner role cannot be assigned through the external API. Provide at least one of role or status.",
            "example": "admin"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "New status of the user's membership in the organization. Inactive suspends access without removing assignments or history. Provide at least one of role or status.",
            "example": "inactive"
          }
        }
      },
      "UpdateOrganizationPlatformUserResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "User ID",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "email": {
            "type": "string",
            "description": "User email",
            "example": "user@example.com"
          },
          "firstName": {
            "type": "string",
            "description": "User first name",
            "example": "John"
          },
          "lastName": {
            "type": "string",
            "description": "User last name",
            "example": "Doe"
          },
          "organizationRole": {
            "type": "string",
            "enum": [
              "owner",
              "admin",
              "manager",
              "user",
              "copilot_user",
              "copilot_admin",
              "guest"
            ],
            "description": "Role of the user in the organization after the update.",
            "example": "admin"
          },
          "organizationStatus": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Status of the user's membership in the organization after the update.",
            "example": "active"
          }
        },
        "required": [
          "id",
          "email",
          "firstName",
          "lastName",
          "organizationRole",
          "organizationStatus"
        ]
      },
      "PackDocumentInputDTO": {
        "type": "object",
        "properties": {
          "fileName": {
            "type": "string",
            "description": "Original file name of the uploaded document.",
            "example": "refund-policy.pdf"
          },
          "storagePath": {
            "type": "string",
            "description": "Storage path returned by the pack document upload-url endpoint after the file has been uploaded to the signed URL.",
            "example": "agent-packs/documents/5f7b1b3b/refund-policy.pdf"
          }
        },
        "required": [
          "fileName",
          "storagePath"
        ]
      },
      "CreatePackBodyDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Human-readable name of the pack.",
            "example": "Core Support Playbook"
          },
          "description": {
            "type": "string",
            "description": "Short description of what the pack contains.",
            "example": "Shared tone, escalation rules and refund policy for support agents."
          },
          "instructions": {
            "type": "string",
            "description": "The shared instructions / core training text imported into agents linked to this pack.",
            "example": "Always greet the customer by name. Never promise a refund above $100 without approval."
          },
          "isPrivate": {
            "type": "boolean",
            "default": false,
            "description": "When true the pack is private to the organization member who owns the Organization API key. Defaults to false (visible to the whole organization).",
            "example": false
          },
          "files": {
            "description": "Documents to attach to the pack on creation. Upload each file to a signed URL first (see the pack document upload-url endpoint) and pass the returned fileName and storagePath here.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PackDocumentInputDTO"
            }
          }
        },
        "required": [
          "name",
          "description",
          "instructions"
        ]
      },
      "PackFileResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "File ID.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "fileName": {
            "type": "string",
            "description": "Original file name.",
            "example": "refund-policy.pdf"
          },
          "url": {
            "type": "string",
            "description": "Time-limited signed download URL for the file.",
            "example": "https://storage.example.com/agent-packs/refund-policy.pdf?signature=..."
          },
          "size": {
            "type": "number",
            "description": "File size in bytes.",
            "example": 20480
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "File creation date.",
            "example": "2024-01-01T00:00:00.000Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "File last update date.",
            "example": "2024-01-02T00:00:00.000Z"
          }
        },
        "required": [
          "id",
          "fileName",
          "url",
          "size",
          "createdAt",
          "updatedAt"
        ]
      },
      "PackWithFilesResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Pack ID.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "name": {
            "type": "string",
            "description": "Name of the pack.",
            "example": "Core Support Playbook"
          },
          "description": {
            "type": "string",
            "description": "Description of the pack.",
            "example": "Shared tone, escalation rules and refund policy."
          },
          "instructions": {
            "type": "string",
            "description": "Shared instructions / core training text.",
            "example": "Always greet the customer by name."
          },
          "isPrivate": {
            "type": "boolean",
            "description": "Whether the pack is private to the API key owner.",
            "example": false
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Status of the pack.",
            "example": "active"
          },
          "usedInAgentsCount": {
            "type": "number",
            "description": "Number of agents this pack is currently linked to.",
            "example": 3
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Creation date.",
            "example": "2024-01-01T00:00:00.000Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Last update date.",
            "example": "2024-01-02T00:00:00.000Z"
          },
          "files": {
            "description": "Documents attached to the pack, with signed download URLs.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PackFileResponseDTO"
            }
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "instructions",
          "isPrivate",
          "status",
          "usedInAgentsCount",
          "createdAt",
          "updatedAt",
          "files"
        ]
      },
      "PackResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Pack ID.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "name": {
            "type": "string",
            "description": "Name of the pack.",
            "example": "Core Support Playbook"
          },
          "description": {
            "type": "string",
            "description": "Description of the pack.",
            "example": "Shared tone, escalation rules and refund policy."
          },
          "instructions": {
            "type": "string",
            "description": "Shared instructions / core training text.",
            "example": "Always greet the customer by name."
          },
          "isPrivate": {
            "type": "boolean",
            "description": "Whether the pack is private to the API key owner.",
            "example": false
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Status of the pack.",
            "example": "active"
          },
          "usedInAgentsCount": {
            "type": "number",
            "description": "Number of agents this pack is currently linked to.",
            "example": 3
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "description": "Creation date.",
            "example": "2024-01-01T00:00:00.000Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "description": "Last update date.",
            "example": "2024-01-02T00:00:00.000Z"
          }
        },
        "required": [
          "id",
          "name",
          "description",
          "instructions",
          "isPrivate",
          "status",
          "usedInAgentsCount",
          "createdAt",
          "updatedAt"
        ]
      },
      "PaginatedPacksResponseDTO": {
        "type": "object",
        "properties": {
          "data": {
            "description": "Packs on the current page.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PackResponseDTO"
            }
          },
          "total": {
            "type": "number",
            "description": "Total number of packs matching the query.",
            "example": 42
          },
          "page": {
            "type": "number",
            "description": "Zero-based current page number.",
            "example": 0
          },
          "pageSize": {
            "type": "number",
            "description": "Page size used for the query.",
            "example": 10
          },
          "totalPages": {
            "type": "number",
            "description": "Total number of pages.",
            "example": 5
          }
        },
        "required": [
          "data",
          "total",
          "page",
          "pageSize",
          "totalPages"
        ]
      },
      "UpdatePackBodyDTO": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "New name of the pack.",
            "example": "Core Support Playbook (v2)"
          },
          "description": {
            "type": "string",
            "description": "New description of the pack.",
            "example": "Updated escalation rules for support agents."
          },
          "instructions": {
            "type": "string",
            "description": "New shared instructions / core training text.",
            "example": "Always greet the customer by name and confirm their order id."
          },
          "isPrivate": {
            "type": "boolean",
            "description": "Whether the pack is private to the Organization API key owner.",
            "example": false
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Status of the pack. Inactive packs are hidden from agents but not deleted.",
            "example": "active"
          }
        }
      },
      "CreatePackDocumentUploadUrlBodyDTO": {
        "type": "object",
        "properties": {
          "fileName": {
            "type": "string",
            "description": "Name of the document to upload.",
            "example": "refund-policy.pdf"
          },
          "contentType": {
            "type": "string",
            "enum": [
              "application/msword",
              "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
              "text/plain",
              "text/plain; charset=utf-8",
              "application/pdf",
              "text/markdown",
              "application/json"
            ],
            "description": "MIME content type of the document to upload.",
            "example": "application/pdf"
          }
        },
        "required": [
          "fileName",
          "contentType"
        ]
      },
      "CreatePackDocumentUploadUrlResponseDTO": {
        "type": "object",
        "properties": {
          "signedUrl": {
            "type": "string",
            "description": "Time-limited signed URL. Upload the document with an HTTP PUT to this URL.",
            "example": "https://storage.example.com/agent-packs/documents/...?signature=..."
          },
          "storagePath": {
            "type": "string",
            "description": "Storage path of the uploaded document. Pass this (with fileName) when attaching the document to a pack.",
            "example": "agent-packs/documents/5f7b1b3b/refund-policy.pdf"
          }
        },
        "required": [
          "signedUrl",
          "storagePath"
        ]
      },
      "LinkPackToAgentResponseDTO": {
        "type": "object",
        "properties": {
          "agentId": {
            "type": "string",
            "description": "ID of the agent the pack was linked to.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "packId": {
            "type": "string",
            "description": "ID of the pack that was linked.",
            "example": "6a8c2c4c-4c4c-5c4c-4c4c-4c4c4c4c4c4c"
          }
        },
        "required": [
          "agentId",
          "packId"
        ]
      },
      "CreateFunctionBodyDTO": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the organization member who will own the function. Must belong to the API key organization. When isPrivate is true the function is visible only to this user; otherwise it is available to the whole organization.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "name": {
            "type": "string",
            "description": "Human-readable name of the function.",
            "example": "Lookup Order Status"
          },
          "internalName": {
            "type": "string",
            "description": "Machine name used as the tool key. 1-64 characters, letters, numbers, underscores and hyphens only. Unique within the organization.",
            "example": "lookup_order_status"
          },
          "description": {
            "type": "string",
            "description": "Description of what the function does.",
            "example": "Looks up the current status of an order by its id."
          },
          "url": {
            "type": "string",
            "description": "HTTPS endpoint invoked when the function runs.",
            "example": "https://api.example.com/orders/status"
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "default": "POST",
            "description": "HTTP method used to invoke the endpoint. GET sends function arguments as query parameters; POST sends them as a JSON body.",
            "example": "GET"
          },
          "isPrivate": {
            "type": "boolean",
            "description": "When true the function is private to the owner (userId) — \"only for me\". When false it is available to the whole organization.",
            "example": false
          },
          "definition": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Function definition / parameter schema, as a JSON object of string values.",
            "example": {
              "location": "string",
              "unit": "string"
            }
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "nullable": true,
            "description": "Optional HTTP headers sent with the outbound request.",
            "example": {
              "Authorization": "Bearer ..."
            }
          }
        },
        "required": [
          "userId",
          "name",
          "internalName",
          "description",
          "url",
          "isPrivate",
          "definition"
        ]
      },
      "FunctionResponseDTO": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "name": {
            "type": "string",
            "example": "Lookup Order Status"
          },
          "internalName": {
            "type": "string",
            "example": "lookup_order_status"
          },
          "description": {
            "type": "string",
            "example": "Looks up the current status of an order by its id."
          },
          "isPrivate": {
            "type": "boolean",
            "description": "True when the function is private to its owner.",
            "example": false
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "example": "active"
          },
          "url": {
            "type": "string",
            "example": "https://api.example.com/orders/status"
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "example": "GET"
          },
          "definition": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "location": "string"
            }
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "nullable": true,
            "example": {
              "Authorization": "Bearer ..."
            }
          },
          "userId": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the organization member who owns the function.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string",
            "example": "2024-01-01T00:00:00.000Z"
          },
          "updatedAt": {
            "format": "date-time",
            "type": "string",
            "example": "2024-01-02T00:00:00.000Z"
          }
        },
        "required": [
          "id",
          "name",
          "internalName",
          "description",
          "isPrivate",
          "status",
          "url",
          "method",
          "definition",
          "userId",
          "createdAt",
          "updatedAt"
        ]
      },
      "PaginatedFunctionsResponseDTO": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FunctionResponseDTO"
            }
          },
          "total": {
            "type": "number",
            "example": 42
          },
          "page": {
            "type": "number",
            "example": 0
          },
          "pageSize": {
            "type": "number",
            "example": 10
          },
          "totalPages": {
            "type": "number",
            "example": 5
          }
        },
        "required": [
          "data",
          "total",
          "page",
          "pageSize",
          "totalPages"
        ]
      },
      "UpdateFunctionBodyDTO": {
        "type": "object",
        "properties": {
          "userId": {
            "type": "string",
            "format": "uuid",
            "description": "ID of the organization member acting on the function. Must belong to the API key organization and have access to the function.",
            "example": "5f7b1b3b-3b3b-4b3b-3b3b-3b3b3b3b3b3b"
          },
          "name": {
            "type": "string",
            "example": "Lookup Order Status"
          },
          "internalName": {
            "type": "string",
            "example": "lookup_order_status"
          },
          "description": {
            "type": "string",
            "example": "Looks up the current status of an order by its id."
          },
          "url": {
            "type": "string",
            "example": "https://api.example.com/orders/status"
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST"
            ],
            "description": "HTTP method used to invoke the endpoint. GET sends function arguments as query parameters; POST sends them as a JSON body.",
            "example": "GET"
          },
          "isPrivate": {
            "type": "boolean",
            "description": "Toggle \"only for me\" (true) vs organization-wide (false). Only the owner can change a function's privacy.",
            "example": false
          },
          "definition": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Function definition / parameter schema.",
            "example": {
              "location": "string"
            }
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "nullable": true,
            "description": "Optional HTTP headers sent with the outbound request.",
            "example": {
              "Authorization": "Bearer ..."
            }
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive"
            ],
            "description": "Status of the function.",
            "example": "active"
          }
        },
        "required": [
          "userId"
        ]
      }
    }
  }
}