> For the complete documentation index, see [llms.txt](https://raia2.gitbook.io/raia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://raia2.gitbook.io/raia/api-reference/agents.md).

# Agents

## Get agent users by agent ID and Organization API key

> Fetches agent users by agent ID and Organization API key. The response includes the agent users details.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Organization-Secret-Key":[]}],"components":{"securitySchemes":{"Organization-Secret-Key":{"type":"apiKey","in":"header","name":"Organization-Secret-Key","description":"Custom authentication header"}},"schemas":{"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"]},"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"},"isAnonymized":{"type":"boolean","description":"Is anonymized"}},"required":["id","firstName","lastName","isAnonymized"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/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":{"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"}}}}},"summary":"Get agent users by agent ID and Organization API key","tags":["Agents","Organization API Key"]}}}}
```

## Get agent platform users by agent ID and Organization API key

> 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.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Organization-Secret-Key":[]}],"components":{"securitySchemes":{"Organization-Secret-Key":{"type":"apiKey","in":"header","name":"Organization-Secret-Key","description":"Custom authentication header"}},"schemas":{"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"]},"ExternalApiAgentPlatformUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"email":{"type":"string","description":"User email"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"avatarUrl":{"type":"string","nullable":true,"description":"User avatar URL"},"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."},"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."},"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."},"organizationStatus":{"type":"string","enum":["active","inactive"],"nullable":true,"description":"Status of the user's membership in the agent's organization."},"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."},"createdAt":{"format":"date-time","type":"string","description":"User creation date"}},"required":["id","email","firstName","lastName","accessSource","createdAt"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/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":{"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"}}}}},"summary":"Get agent platform users by agent ID and Organization API key","tags":["Agents","Organization API Key","Platform Users"]}}}}
```

## Get agent users by Agent API key

> Fetches agent users by Agent API key. The response includes the agent users details.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"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"]},"ExternalApiUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"context":{"type":"string","description":"User context"},"source":{"type":"string","description":"User source"},"fkId":{"type":"string","description":"User fkId"},"fkUserId":{"type":"string","description":"User fkUserId"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"metadata":{"type":"object","description":"Conversation user metadata"},"isAnonymized":{"type":"boolean","description":"Is anonymized"}},"required":["id","firstName","lastName","isAnonymized"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/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"}}}}},"summary":"Get agent users by Agent API key","tags":["Agents","Agent API Key"]}}}}
```

## Get agent admin users by Agent API key

> 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.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"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"]},"ExternalApiAgentAdminUserResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"email":{"type":"string","description":"User email"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"avatarUrl":{"type":"string","nullable":true,"description":"User avatar URL"},"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."},"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."},"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."},"organizationStatus":{"type":"string","enum":["active","inactive"],"nullable":true,"description":"Status of the user's membership in the agent's organization."},"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."},"createdAt":{"format":"date-time","type":"string","description":"User creation date"}},"required":["id","email","firstName","lastName","accessSource","createdAt"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/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"}}}}},"summary":"Get agent admin users by Agent API key","tags":["Agents","Agent API Key"]}}}}
```

## Get agent by API key

> Fetches an agent by API key. The response includes the agent details.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"GetAgentByApiKeyResponseDTO":{"type":"object","properties":{"organizationId":{"type":"string","description":"Unique identifier for the organization.","format":"uuid"},"organizationName":{"type":"string","description":"Name of the organization."},"id":{"type":"string","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."},"aiConfig":{"description":"Agent AI config.","allOf":[{"$ref":"#/components/schemas/AIConfigResponseDTO"}]},"avatarUrl":{"type":"string","description":"Avatar URL of the agent."},"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/WebSearchSkillResponseDTO"},{"$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."}},"required":["organizationId","organizationName","id","name","publicName","role","vectorStoreId","aiConfig","status","skills"]},"AIConfigResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Agent AI config ID."},"model":{"type":"string","enum":["gpt-4.1","gpt-4.1-nano","gpt-4.1-mini","gpt-3.5-turbo","o3-mini","gpt-5-nano","gpt-5","gpt-5-mini","gpt-5.1","gpt-5.2","gpt-5.4","gpt-5.4-mini","gpt-5.4-nano","gpt-5.5","gpt-5.6","gpt-5.6-terra","gpt-5.6-luna"],"description":"Open AI model."},"temperature":{"type":"number","description":"OpenAI temperature."},"topP":{"type":"number","description":"OpenAI top_p."},"instructions":{"type":"string","description":"OpenAI instructions."},"isCodeInterpreterEnabled":{"type":"boolean","description":"Is code interpreter enabled."},"isFileSearchEnabled":{"type":"boolean","description":"Is file search enabled."},"fileSearchMaxNumResults":{"type":"number","description":"File search max number of results."},"reasoningEffort":{"type":"string","enum":["low","medium","high","xhigh","minimal","none","max"],"description":"Reasoning effort of the agent.","nullable":true},"reasoningMode":{"type":"string","enum":["standard","pro"],"description":"Reasoning mode of the agent.","nullable":true},"isOutputJsonSchemaEnabled":{"type":"boolean","description":"Is output JSON schema enabled."},"outputJsonSchema":{"type":"string","description":"Output JSON schema of the agent."}},"required":["id","model","temperature","topP","instructions","isCodeInterpreterEnabled","isFileSearchEnabled","fileSearchMaxNumResults","outputJsonSchema"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]}},"required":["systemName","status"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"color":{"type":"string","description":"Color of the chat widget."},"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."},"titleLine2":{"type":"string","description":"Second line of the chat widget title."},"intro":{"type":"string","description":"Default introduction message (same as titleLine2; kept for backwards compatibility)."},"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."},"chatFooterContent":{"type":"string","description":"Chat footer content below the input (e.g. privacy policy)"},"suggestions":{"description":"List of suggestions for the chat widget.","type":"array","items":{"type":"string"}},"whitelistedIps":{"description":"List of IP addresses that are whitelisted.","type":"array","items":{"type":"string"}},"restrictedCountries":{"description":"List of countries that are restricted.","type":"array","items":{"type":"string"}},"limitUnavailableDates":{"type":"boolean","description":"Whether live chat should be unavailable on the configured unavailableDates (YYYY-MM-DD)."},"unavailableDates":{"description":"Dates (YYYY-MM-DD) when live chat is unavailable (e.g. holidays, maintenance).","type":"array","items":{"type":"string"}},"unavailableDatesMessage":{"type":"string","description":"Custom message to show when live chat is unavailable on unavailableDates."}},"required":["systemName","status","limitUnavailableDates","unavailableDates","unavailableDatesMessage"]},"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 "},"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"]},"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"]},"LiveChatLinkExternalDTO":{"type":"object","properties":{"name":{"type":"string","description":"Label displayed for the link."},"url":{"type":"string","description":"Absolute URL opened when the link is selected."}},"required":["name","url"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"phoneNumber":{"type":"string","description":"Phone number associated with the sms skill."},"defaultSmsIntroduction":{"type":"object","description":"Default SMS introduction."},"smsSignature":{"type":"object","description":"SMS signature."},"responseDelaySeconds":{"type":"object","description":"Delay in seconds before sending an SMS response (0–3600).","nullable":true}},"required":["systemName","status","phoneNumber"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"email":{"type":"string","description":"Email address associated with the email skill."},"senderName":{"type":"string","description":"Name of the email sender."},"defaultSubject":{"type":"string","description":"Email subject."},"defaultEmailIntroduction":{"type":"string","description":"Default email introduction."},"emailSignature":{"type":"string","description":"Default email closing."},"responseDelaySeconds":{"type":"object","description":"Delay in seconds before sending an email response (0–3600).","nullable":true}},"required":["systemName","status","email"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"name":{"type":"string","description":"Webhook skill name."},"description":{"type":"string","description":"Webhook skill description."},"webhooks":{"description":"Webhook configs.","type":"array","items":{"$ref":"#/components/schemas/WebhookResponseDTO"}}},"required":["systemName","status","name","description","webhooks"]},"WebhookResponseDTO":{"type":"object","properties":{"status":{"type":"string","description":"Status of the webhook.","enum":["active","inactive"]},"title":{"type":"string","description":"Webhook title."},"description":{"type":"string","description":"Webhook description."},"url":{"type":"string","description":"Webhook URL."},"triggerCondition":{"type":"string","description":"Webhook trigger condition.","enum":["each_message","end_dialog","start_dialog","chat_currently_unavailable","auto_archive_conversation","manual"]},"headers":{"type":"object","description":"Webhook headers."}},"required":["status","title","description","url","triggerCondition"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]}},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"scoringPrompt":{"type":"string","description":"Scoring prompt."}},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"apiKey":{"type":"string","description":"API key for the skill.","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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"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"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"scrapingConfigs":{"description":"Agent scraping configs.","type":"array","items":{"$ref":"#/components/schemas/ScrapingConfigResponseDTO"}}},"required":["systemName","status","scrapingConfigs"]},"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"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]}},"required":["systemName","status"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"externalRetrievers":{"description":"External retrievers.","type":"array","items":{"$ref":"#/components/schemas/ExternalRetrieverResponseDTO"}}},"required":["systemName","status","externalRetrievers"]},"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"]},"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"]},"WebSearchSkillResponseDTO":{"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"webSearchServiceType":{"type":"string","enum":["openai"],"description":"Web search service."},"prompt":{"type":"string","description":"Web search prompt."}},"required":["systemName","status","webSearchServiceType","prompt"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"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"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"escalations":{"description":"Escalations.","type":"array","items":{"$ref":"#/components/schemas/EscalationResponseDTO"}}},"required":["systemName","status","escalations"]},"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"]},"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"}},"required":["channel","value"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"config":{"oneOf":[{"$ref":"#/components/schemas/CalCalendarConfig"}],"discriminator":{"propertyName":"type","mapping":{"cal":"#/components/schemas/CalCalendarConfig"}},"allOf":[{"$ref":"#/components/schemas/CalCalendarConfig"}]}},"required":["systemName","status","config"]},"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"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"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"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"config":{"description":"Microsoft Teams skill configuration.","allOf":[{"$ref":"#/components/schemas/MsTeamsSkillConfigExternalDTO"}]}},"required":["systemName","status","config"]},"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"]},"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"]},"MsTeamsTeamConfigExternalDTO":{"type":"object","properties":{"teamId":{"type":"string","description":"Microsoft Teams team ID."},"channels":{"$ref":"#/components/schemas/MsTeamsChannelScopeExternalDTO"}},"required":["teamId","channels"]},"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"]},"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"]},"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"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"config":{"description":"Slack skill configuration.","allOf":[{"$ref":"#/components/schemas/SlackSkillConfigExternalDTO"}]}},"required":["systemName","status","config"]},"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"]},"SlackWorkspaceConfigExternalDTO":{"type":"object","properties":{"slackTeamId":{"type":"string","description":"Slack workspace id (`T…`). Matches inbound `team_id`."},"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"]},"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"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/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"}}}}},"summary":"Get agent by API key","tags":["Agents","Agent API Key"]}}}}
```

## Get agent statistic by API key

> Fetches an agent statistic by API key. The response includes the agent statistic.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"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"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/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","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date of statistics calculation.","schema":{"format":"date-time","type":"string"}},{"name":"fkId","required":false,"in":"query","description":"Conversation user fkId.","schema":{"type":"string"}},{"name":"fkUserId","required":false,"in":"query","description":"Conversation user fkUserId.","schema":{"type":"string"}},{"name":"userId","required":false,"in":"query","description":"Conversation user userId.","schema":{"format":"uuid","type":"string"}},{"name":"conversationUserId","required":false,"in":"query","description":"Conversation user id.","schema":{"format":"uuid","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"}}}}},"summary":"Get agent statistic by API key","tags":["Agents","Agent API Key"]}}}}
```

## Create agent webhook

> Creates a new webhook for the agent identified by the API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"CreateAgentWebhookBodyDTO":{"type":"object","properties":{"title":{"type":"string","description":"Title of the webhook"},"description":{"type":"string","description":"Description of the webhook"},"url":{"type":"string","description":"Public HTTPS URL where the webhook will be sent. Local, private, reserved, and metadata-service addresses are not allowed."},"triggerCondition":{"type":"string","description":"Condition that triggers the webhook","enum":["each_message","end_dialog","start_dialog","chat_currently_unavailable","auto_archive_conversation","manual"]},"headers":{"type":"object","description":"Optional headers to be sent with the webhook"}},"required":["title","description","url","triggerCondition"]},"CreateAgentWebhookResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"ID of the created webhook"},"agentId":{"type":"string","description":"ID of the agent this webhook belongs to"},"title":{"type":"string","description":"Title of the webhook"},"description":{"type":"string","description":"Description of the webhook"},"url":{"type":"string","description":"URL where the webhook will be sent"},"triggerCondition":{"type":"string","description":"Condition that triggers the webhook","enum":["each_message","end_dialog","start_dialog","chat_currently_unavailable","auto_archive_conversation","manual"]},"headers":{"type":"object","description":"Optional headers to be sent with the webhook"},"status":{"type":"string","description":"Status of the webhook","enum":["active","inactive"]},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"}},"required":["id","agentId","title","description","url","triggerCondition","status","createdAt","updatedAt"]},"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"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/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"}}}}},"summary":"Create agent webhook","tags":["Agents","Agent API Key"]}}}}
```

## Get agent limits by Agent API key

> Fetches agent limits for the agent resolved by the provided Agent API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"AgentLimitsResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent limits","format":"uuid"},"agentId":{"type":"string","description":"Unique identifier for the agent","format":"uuid"},"isOrganizationDefault":{"type":"boolean","description":"Whether the agent limits are organization defaults"},"tokensAmountPerMonth":{"type":"number","description":"Tokens amount per month"},"smsAmountPerMonth":{"type":"number","description":"SMS amount per month"},"emailsAmountPerMonth":{"type":"number","description":"Emails amount per month"},"secondsAmountPerMonth":{"type":"number","description":"Seconds amount per month"}},"required":["id","agentId","isOrganizationDefault","tokensAmountPerMonth","smsAmountPerMonth","emailsAmountPerMonth","secondsAmountPerMonth"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/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"}}}}},"summary":"Get agent limits by Agent API key","tags":["Agents","Agent API Key"]}}}}
```

## Create agent limits by Agent API key

> Creates agent limits for the agent resolved by the provided Agent API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"CreateAgentLimitsBodyDTO":{"type":"object","properties":{"tokensAmountPerMonth":{"type":"number","description":"Tokens amount per month"},"smsAmountPerMonth":{"type":"number","description":"SMS amount per month"},"emailsAmountPerMonth":{"type":"number","description":"Emails amount per month"},"secondsAmountPerMonth":{"type":"number","description":"Seconds amount per month"}},"required":["tokensAmountPerMonth","smsAmountPerMonth","emailsAmountPerMonth","secondsAmountPerMonth"]},"AgentLimitsResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent limits","format":"uuid"},"agentId":{"type":"string","description":"Unique identifier for the agent","format":"uuid"},"isOrganizationDefault":{"type":"boolean","description":"Whether the agent limits are organization defaults"},"tokensAmountPerMonth":{"type":"number","description":"Tokens amount per month"},"smsAmountPerMonth":{"type":"number","description":"SMS amount per month"},"emailsAmountPerMonth":{"type":"number","description":"Emails amount per month"},"secondsAmountPerMonth":{"type":"number","description":"Seconds amount per month"}},"required":["id","agentId","isOrganizationDefault","tokensAmountPerMonth","smsAmountPerMonth","emailsAmountPerMonth","secondsAmountPerMonth"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agents/limits":{"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"}}}}},"summary":"Create agent limits by Agent API key","tags":["Agents","Agent API Key"]}}}}
```

## Update agent limits by Agent API key

> Updates agent limits for the agent resolved by the provided Agent API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"UpdateAgentLimitsBodyDTO":{"type":"object","properties":{"tokensAmountPerMonth":{"type":"number","description":"Tokens amount per month"},"smsAmountPerMonth":{"type":"number","description":"SMS amount per month"},"emailsAmountPerMonth":{"type":"number","description":"Emails amount per month"},"secondsAmountPerMonth":{"type":"number","description":"Seconds amount per month"}}},"AgentLimitsResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent limits","format":"uuid"},"agentId":{"type":"string","description":"Unique identifier for the agent","format":"uuid"},"isOrganizationDefault":{"type":"boolean","description":"Whether the agent limits are organization defaults"},"tokensAmountPerMonth":{"type":"number","description":"Tokens amount per month"},"smsAmountPerMonth":{"type":"number","description":"SMS amount per month"},"emailsAmountPerMonth":{"type":"number","description":"Emails amount per month"},"secondsAmountPerMonth":{"type":"number","description":"Seconds amount per month"}},"required":["id","agentId","isOrganizationDefault","tokensAmountPerMonth","smsAmountPerMonth","emailsAmountPerMonth","secondsAmountPerMonth"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agents/limits":{"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"}}}}},"summary":"Update agent limits by Agent API key","tags":["Agents","Agent API Key"]}}}}
```

## Delete agent limits by Agent API key

> Deletes agent limits for the agent resolved by the provided Agent API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agents/limits":{"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"}}}}},"summary":"Delete agent limits by Agent API key","tags":["Agents","Agent API Key"]}}}}
```

## Get agent usage by Agent API key

> Fetches agent usage for the agent resolved by the provided Agent API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"AgentUsageResponseDTO":{"type":"object","properties":{"emailsAmount":{"type":"number","description":"Emails amount"},"smsAmount":{"type":"number","description":"SMS amount"},"tokensAmount":{"type":"number","description":"Tokens amount"},"secondsAmount":{"type":"number","description":"Seconds amount"}},"required":["emailsAmount","smsAmount","tokensAmount","secondsAmount"]},"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"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/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"}}}}},"summary":"Get agent usage by Agent API key","tags":["Agents","Agent API Key"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://raia2.gitbook.io/raia/api-reference/agents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.