# 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"}},"required":["id","firstName","lastName"]},"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"}}}},"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 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":{"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"}]},"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"],"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"],"description":"Reasoning effort 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"]},"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"]},"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":{"type":"string"}},"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"]},"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"]},"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."}},"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"]},"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."}},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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/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"}}}}},"summary":"Get agent 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"}]},"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"],"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"],"description":"Reasoning effort 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"]},"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"]},"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":{"type":"string"}},"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"]},"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"]},"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."}},"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"]},"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."}},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"]},"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"}}}},"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"}}}},"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":"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"]},"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"]},"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"]},"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"}}}},"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":"Create agent webhook","tags":["Agents","Agent API Key"]}}}}
```


---

# Agent Instructions: 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:

```
GET https://docs.raiaai.com/api-reference/agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.