> 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/organization-api-key.md).

# Organization API Key

## Create agent via organization API key

> Creates an agent by organization 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":[{"Organization-Secret-Key":[]}],"components":{"securitySchemes":{"Organization-Secret-Key":{"type":"apiKey","in":"header","name":"Organization-Secret-Key","description":"Custom authentication header"}},"schemas":{"CreateAgentByApiKeyBodyDTO":{"type":"object","properties":{"roleId":{"type":"string","description":"Agent role ID.","format":"uuid"},"name":{"type":"string","description":"Name of the agent."},"publicName":{"type":"string","description":"Public name of the agent."},"description":{"type":"string","description":"Description of the agent."},"instructions":{"type":"string","description":"Instructions of the agent."},"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":"Model of the agent."},"topP":{"type":"number","description":"TopP of the agent."},"temperature":{"type":"number","description":"Temperature of the agent."},"isFileSearchEnabled":{"type":"boolean","description":"Is file search enabled by default."},"isCodeInterpreterEnabled":{"type":"boolean","description":"Is code interpreter enabled by default."},"fileSearchMaxNumResults":{"type":"number","description":"File search max number of results. Required when isFileSearchEnabled is true.","default":10},"reasoningEffort":{"type":"string","enum":["low","medium","high","xhigh","minimal","none","max"],"description":"Reasoning effort of the agent. Required only when mode is reasoning."},"reasoningMode":{"type":"string","enum":["standard","pro"],"description":"Reasoning mode of the agent."},"isApiSkillEnabled":{"type":"boolean","description":"Is agent API skill enabled by default."},"isOutputJsonSchemaEnabled":{"type":"boolean","description":"Is output JSON schema enabled by default."},"outputJsonSchema":{"type":"string","description":"Output JSON schema of the agent."},"tags":{"description":"Tags of the agent.","type":"array","items":{"type":"string"}},"restrictDocumentsToOwnerOnly":{"type":"boolean","description":"Restrict documents to owner only."}},"required":["roleId","name","publicName","outputJsonSchema","tags"]},"CreateAgentResponseDTO":{"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."},"agentApiKey":{"type":"string","nullable":true,"description":"Deprecated: API keys are now managed separately via the agent API key endpoints"}},"required":["organizationId","organizationName","id","name","publicName","role","vectorStoreId","aiConfig","status","skills"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agents":{"post":{"description":"Creates an agent by organization API key. The response includes the agent details.","operationId":"ExternalApiAgentsController_createAgentByApiKey","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentByApiKeyBodyDTO"}}}},"responses":{"201":{"description":"Successfully created the agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 300 requests per 60 seconds for AI-backed external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create agent via organization API key","tags":["Organization API Key","Agents"]}}}}
```

## Get agent by ID via organization API key

> Fetches an agent by ID using an organization 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":[{"Organization-Secret-Key":[]}],"components":{"securitySchemes":{"Organization-Secret-Key":{"type":"apiKey","in":"header","name":"Organization-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/{id}":{"get":{"description":"Fetches an agent by ID using an organization API key. The response includes the agent details.","operationId":"ExternalApiAgentsController_getAgentByOrgKeyAndId","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved the agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentByApiKeyResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get agent by ID via organization API key","tags":["Organization API Key","Agents"]}}}}
```

## Update agent via organization API key

> Updates an agent by organization API key. The response includes the updated 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":[{"Organization-Secret-Key":[]}],"components":{"securitySchemes":{"Organization-Secret-Key":{"type":"apiKey","in":"header","name":"Organization-Secret-Key","description":"Custom authentication header"}},"schemas":{"UpdateAgentByApiKeyBodyDTO":{"type":"object","properties":{"name":{"type":"string","description":"Name of the agent."},"publicName":{"type":"string","description":"Public name of the agent."},"description":{"type":"string","description":"Description of the agent."},"tags":{"description":"Tags of the agent.","type":"array","items":{"type":"string"}},"avatarUrl":{"type":"string","description":"Avatar URL of the agent."},"backgroundUrl":{"type":"string","description":"Background URL of the agent."},"status":{"type":"string","enum":["active","inactive","draft"],"description":"Status of the agent."},"instructions":{"type":"string","description":"Instructions of the agent."},"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":"Model of the agent."},"topP":{"type":"number","description":"TopP of the agent."},"temperature":{"type":"number","description":"Temperature of the agent."},"reasoningEffort":{"type":"string","enum":["low","medium","high","xhigh","minimal","none","max"],"description":"Reasoning effort of the agent."},"reasoningMode":{"type":"string","enum":["standard","pro"],"description":"Reasoning mode of the agent."},"defaultErrorMessage":{"type":"string","description":"Default error message of the agent."},"isFileSearchEnabled":{"type":"boolean","description":"Is file search enabled."},"isCodeInterpreterEnabled":{"type":"boolean","description":"Is code interpreter enabled."},"fileSearchMaxNumResults":{"type":"number","description":"File search max number of results. Required when isFileSearchEnabled is true."},"isOutputJsonSchemaEnabled":{"type":"boolean","description":"Is output JSON schema enabled."},"outputJsonSchema":{"type":"string","description":"Output JSON schema of the agent."},"restrictDocumentsToOwnerOnly":{"type":"boolean","description":"Restrict documents to owner only."}},"required":["outputJsonSchema"]},"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/{id}":{"put":{"description":"Updates an agent by organization API key. The response includes the updated agent details.","operationId":"ExternalApiAgentsController_updateAgentByApiKey","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentByApiKeyBodyDTO"}}}},"responses":{"200":{"description":"Successfully updated the agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentByApiKeyResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Update agent via organization API key","tags":["Organization API Key","Agents"]}}}}
```

## List scraping configurations

> Returns all scraping configurations for an agent.

```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":{"AgentScrapResponseDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"crawlerType":{"type":"string","enum":["FIRECRAWL","APIFY"]},"crawlFormat":{"type":"string","enum":["JSON","MARKDOWN","HTML","CONTENT"]},"excludeUrls":{"nullable":true,"type":"array","items":{"type":"string"}},"pageLimit":{"type":"number"},"maxDepth":{"type":"number"},"frequency":{"type":"string","enum":["manual","daily","weekly","monthly"]},"autoUpload":{"type":"boolean"},"crawlingStatus":{"type":"string","enum":["not_started","in_progress","completed","failed","canceled"]},"startCrawledAt":{"type":"object","nullable":true},"endCrawledAt":{"type":"object","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","url","crawlerType","crawlFormat","excludeUrls","pageLimit","maxDepth","frequency","autoUpload","crawlingStatus","startCrawledAt","endCrawledAt","createdAt","updatedAt"]},"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"]}}},"paths":{"/external/agent-scraps/{id}/scraping":{"get":{"description":"Returns all scraping configurations for an agent.","operationId":"ExternalApiAgentScrapingController_getAgentScraps","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of scraping configurations.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentScrapResponseDTO"}}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"List scraping configurations","tags":["Organization API Key","Agent Scraping"]}}}}
```

## Create scraping configuration

> Creates a new scraping configuration and triggers an initial crawl immediately. Subsequent crawls run automatically on the configured frequency.

```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":{"CreateAgentScrapBodyDTO":{"type":"object","properties":{"url":{"type":"string","description":"URL to crawl. Must be a publicly reachable http(s) URL; private, loopback, link-local, and metadata hosts are rejected."},"crawlerType":{"type":"string","enum":["FIRECRAWL","APIFY"],"description":"Crawler engine to use.","default":"FIRECRAWL"},"crawlFormat":{"type":"string","enum":["JSON","MARKDOWN","HTML","CONTENT"],"description":"Output format for crawled content.","default":"MARKDOWN"},"excludeUrls":{"description":"URL patterns to exclude from the crawl.","nullable":true,"type":"array","items":{"type":"string"}},"pageLimit":{"type":"number","description":"Maximum number of pages to crawl.","minimum":1,"maximum":3000,"default":10},"maxDepth":{"type":"number","description":"Maximum link depth to follow from the root URL.","minimum":1,"maximum":5,"default":2},"frequency":{"type":"string","enum":["manual","daily","weekly","monthly"],"description":"How often to automatically re-crawl the URL.","default":"daily"},"autoUpload":{"type":"boolean","description":"When true, crawled content is automatically uploaded to the agent knowledge base after each crawl.","default":true}},"required":["url"]},"AgentScrapResponseDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"crawlerType":{"type":"string","enum":["FIRECRAWL","APIFY"]},"crawlFormat":{"type":"string","enum":["JSON","MARKDOWN","HTML","CONTENT"]},"excludeUrls":{"nullable":true,"type":"array","items":{"type":"string"}},"pageLimit":{"type":"number"},"maxDepth":{"type":"number"},"frequency":{"type":"string","enum":["manual","daily","weekly","monthly"]},"autoUpload":{"type":"boolean"},"crawlingStatus":{"type":"string","enum":["not_started","in_progress","completed","failed","canceled"]},"startCrawledAt":{"type":"object","nullable":true},"endCrawledAt":{"type":"object","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","url","crawlerType","crawlFormat","excludeUrls","pageLimit","maxDepth","frequency","autoUpload","crawlingStatus","startCrawledAt","endCrawledAt","createdAt","updatedAt"]},"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/agent-scraps/{id}/scraping":{"post":{"description":"Creates a new scraping configuration and triggers an initial crawl immediately. Subsequent crawls run automatically on the configured frequency.","operationId":"ExternalApiAgentScrapingController_createAgentScrap","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentScrapBodyDTO"}}}},"responses":{"201":{"description":"Scraping configuration created. Initial crawl triggered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentScrapResponseDTO"}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Scraping skill is not enabled on this agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create scraping configuration","tags":["Organization API Key","Agent Scraping"]}}}}
```

## Get scraping configuration

> Returns a single scraping configuration by ID.

```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":{"AgentScrapResponseDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"crawlerType":{"type":"string","enum":["FIRECRAWL","APIFY"]},"crawlFormat":{"type":"string","enum":["JSON","MARKDOWN","HTML","CONTENT"]},"excludeUrls":{"nullable":true,"type":"array","items":{"type":"string"}},"pageLimit":{"type":"number"},"maxDepth":{"type":"number"},"frequency":{"type":"string","enum":["manual","daily","weekly","monthly"]},"autoUpload":{"type":"boolean"},"crawlingStatus":{"type":"string","enum":["not_started","in_progress","completed","failed","canceled"]},"startCrawledAt":{"type":"object","nullable":true},"endCrawledAt":{"type":"object","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","url","crawlerType","crawlFormat","excludeUrls","pageLimit","maxDepth","frequency","autoUpload","crawlingStatus","startCrawledAt","endCrawledAt","createdAt","updatedAt"]},"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"]}}},"paths":{"/external/agent-scraps/{id}/scraping/{scrapingId}":{"get":{"description":"Returns a single scraping configuration by ID.","operationId":"ExternalApiAgentScrapingController_getAgentScrapById","parameters":[{"name":"scrapingId","required":true,"in":"path","description":"Unique identifier of the scraping configuration.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"Scraping configuration found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentScrapResponseDTO"}}}},"404":{"description":"Agent or scraping configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Get scraping configuration","tags":["Organization API Key","Agent Scraping"]}}}}
```

## Update scraping configuration

> Updates a scraping configuration. All fields are optional. Any update triggers a new crawl immediately.

```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":{"UpdateAgentScrapBodyDTO":{"type":"object","properties":{"url":{"type":"string","description":"URL to crawl. Changing this triggers a new crawl immediately. Must be a publicly reachable http(s) URL; private, loopback, link-local, and metadata hosts are rejected."},"crawlerType":{"type":"string","enum":["FIRECRAWL","APIFY"],"description":"Crawler engine to use."},"crawlFormat":{"type":"string","enum":["JSON","MARKDOWN","HTML","CONTENT"],"description":"Output format for crawled content."},"excludeUrls":{"description":"URL patterns to exclude from the crawl. Set to null to clear existing patterns.","nullable":true,"type":"array","items":{"type":"string"}},"pageLimit":{"type":"number","description":"Maximum number of pages to crawl.","minimum":1,"maximum":3000},"maxDepth":{"type":"number","description":"Maximum link depth to follow from the root URL.","minimum":1,"maximum":5},"frequency":{"type":"string","enum":["manual","daily","weekly","monthly"],"description":"How often to automatically re-crawl the URL."},"autoUpload":{"type":"boolean","description":"When true, crawled content is automatically uploaded to the agent knowledge base after each crawl."}}},"AgentScrapResponseDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"crawlerType":{"type":"string","enum":["FIRECRAWL","APIFY"]},"crawlFormat":{"type":"string","enum":["JSON","MARKDOWN","HTML","CONTENT"]},"excludeUrls":{"nullable":true,"type":"array","items":{"type":"string"}},"pageLimit":{"type":"number"},"maxDepth":{"type":"number"},"frequency":{"type":"string","enum":["manual","daily","weekly","monthly"]},"autoUpload":{"type":"boolean"},"crawlingStatus":{"type":"string","enum":["not_started","in_progress","completed","failed","canceled"]},"startCrawledAt":{"type":"object","nullable":true},"endCrawledAt":{"type":"object","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","url","crawlerType","crawlFormat","excludeUrls","pageLimit","maxDepth","frequency","autoUpload","crawlingStatus","startCrawledAt","endCrawledAt","createdAt","updatedAt"]},"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"]}}},"paths":{"/external/agent-scraps/{id}/scraping/{scrapingId}":{"put":{"description":"Updates a scraping configuration. All fields are optional. Any update triggers a new crawl immediately.","operationId":"ExternalApiAgentScrapingController_updateAgentScrap","parameters":[{"name":"scrapingId","required":true,"in":"path","description":"Unique identifier of the scraping configuration.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentScrapBodyDTO"}}}},"responses":{"200":{"description":"Scraping configuration updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentScrapResponseDTO"}}}},"404":{"description":"Agent or scraping configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Update scraping configuration","tags":["Organization API Key","Agent Scraping"]}}}}
```

## Delete scraping configuration

> Deletes a scraping configuration and removes all associated crawled files from the agent knowledge base.

```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":{"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"]}}},"paths":{"/external/agent-scraps/{id}/scraping/{scrapingId}":{"delete":{"description":"Deletes a scraping configuration and removes all associated crawled files from the agent knowledge base.","operationId":"ExternalApiAgentScrapingController_deleteAgentScrap","parameters":[{"name":"scrapingId","required":true,"in":"path","description":"Unique identifier of the scraping configuration.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"204":{"description":"Scraping configuration deleted."},"404":{"description":"Agent or scraping configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Delete scraping configuration","tags":["Organization API Key","Agent Scraping"]}}}}
```

## Trigger manual crawl

> Triggers an immediate crawl for a scraping configuration outside the scheduled frequency.

```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":{"AgentScrapResponseDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"crawlerType":{"type":"string","enum":["FIRECRAWL","APIFY"]},"crawlFormat":{"type":"string","enum":["JSON","MARKDOWN","HTML","CONTENT"]},"excludeUrls":{"nullable":true,"type":"array","items":{"type":"string"}},"pageLimit":{"type":"number"},"maxDepth":{"type":"number"},"frequency":{"type":"string","enum":["manual","daily","weekly","monthly"]},"autoUpload":{"type":"boolean"},"crawlingStatus":{"type":"string","enum":["not_started","in_progress","completed","failed","canceled"]},"startCrawledAt":{"type":"object","nullable":true},"endCrawledAt":{"type":"object","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","url","crawlerType","crawlFormat","excludeUrls","pageLimit","maxDepth","frequency","autoUpload","crawlingStatus","startCrawledAt","endCrawledAt","createdAt","updatedAt"]},"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"]}}},"paths":{"/external/agent-scraps/{id}/scraping/{scrapingId}/run":{"post":{"description":"Triggers an immediate crawl for a scraping configuration outside the scheduled frequency.","operationId":"ExternalApiAgentScrapingController_runAgentScrap","parameters":[{"name":"scrapingId","required":true,"in":"path","description":"Unique identifier of the scraping configuration.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"Crawl triggered. crawlingStatus updated to in_progress.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentScrapResponseDTO"}}}},"404":{"description":"Agent or scraping configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Trigger manual crawl","tags":["Organization API Key","Agent Scraping"]}}}}
```

## Cancel in-progress crawl

> Cancels a crawl that is currently in progress.

```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":{"AgentScrapResponseDTO":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"crawlerType":{"type":"string","enum":["FIRECRAWL","APIFY"]},"crawlFormat":{"type":"string","enum":["JSON","MARKDOWN","HTML","CONTENT"]},"excludeUrls":{"nullable":true,"type":"array","items":{"type":"string"}},"pageLimit":{"type":"number"},"maxDepth":{"type":"number"},"frequency":{"type":"string","enum":["manual","daily","weekly","monthly"]},"autoUpload":{"type":"boolean"},"crawlingStatus":{"type":"string","enum":["not_started","in_progress","completed","failed","canceled"]},"startCrawledAt":{"type":"object","nullable":true},"endCrawledAt":{"type":"object","nullable":true},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","url","crawlerType","crawlFormat","excludeUrls","pageLimit","maxDepth","frequency","autoUpload","crawlingStatus","startCrawledAt","endCrawledAt","createdAt","updatedAt"]},"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"]}}},"paths":{"/external/agent-scraps/{id}/scraping/{scrapingId}/cancel":{"post":{"description":"Cancels a crawl that is currently in progress.","operationId":"ExternalApiAgentScrapingController_cancelAgentScrap","parameters":[{"name":"scrapingId","required":true,"in":"path","description":"Unique identifier of the scraping configuration.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"Crawl cancelled. crawlingStatus updated to canceled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentScrapResponseDTO"}}}},"404":{"description":"Agent or scraping configuration not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Cancel in-progress crawl","tags":["Organization API Key","Agent Scraping"]}}}}
```

## List agent API keys

> Returns all API keys for an agent. An agent may have more than one key. The full key value is never returned — only a masked preview.

```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":{"AgentApiKeyResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the API key."},"name":{"type":"string","description":"Label for the API key."},"keyPreview":{"type":"string","description":"Masked preview of the API key. The full key is only returned when the key is created or rotated."},"status":{"type":"string","enum":["active","expired","revoked"],"description":"Current status of the API key."},"expiresAt":{"type":"string","nullable":true,"description":"Expiry date of the API key (YYYY-MM-DD). Null if the key does not expire."},"revokedAt":{"type":"string","nullable":true,"description":"Timestamp when the API key was revoked. Null if the key is still active."},"createdAt":{"type":"string","description":"Timestamp when the API key was created."}},"required":["id","name","keyPreview","status","expiresAt","revokedAt","createdAt"]},"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"]}}},"paths":{"/external/agent-api-keys/{id}":{"get":{"description":"Returns all API keys for an agent. An agent may have more than one key. The full key value is never returned — only a masked preview.","operationId":"ExternalApiAgentApiKeysController_listApiKeys","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"API key metadata for the agent.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentApiKeyResponseDTO"}}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"List agent API keys","tags":["Organization API Key","Agent API Keys"]}}}}
```

## Create agent API key

> Creates an API key for an agent. The full key is returned once — store it securely as it cannot be retrieved again.

```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":{"CreateAgentApiKeyBodyDTO":{"type":"object","properties":{"name":{"type":"string","description":"Label for the API key."},"expiresAt":{"type":"string","description":"Expiry date in ISO 8601 format (YYYY-MM-DD)."}},"required":["name","expiresAt"]},"CreateAgentApiKeyResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the API key."},"name":{"type":"string","description":"Label for the API key."},"keyPreview":{"type":"string","description":"Masked preview of the API key. The full key is only returned when the key is created or rotated."},"status":{"type":"string","enum":["active","expired","revoked"],"description":"Current status of the API key."},"expiresAt":{"type":"string","nullable":true,"description":"Expiry date of the API key (YYYY-MM-DD). Null if the key does not expire."},"revokedAt":{"type":"string","nullable":true,"description":"Timestamp when the API key was revoked. Null if the key is still active."},"createdAt":{"type":"string","description":"Timestamp when the API key was created."},"agentApiKey":{"type":"string","description":"The full API key. This value is returned only once — at creation or rotation. Store it securely; it cannot be retrieved again."}},"required":["id","name","keyPreview","status","expiresAt","revokedAt","createdAt","agentApiKey"]},"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/agent-api-keys/{id}":{"post":{"description":"Creates an API key for an agent. The full key is returned once — store it securely as it cannot be retrieved again.","operationId":"ExternalApiAgentApiKeysController_createApiKey","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentApiKeyBodyDTO"}}}},"responses":{"201":{"description":"API key created. The agentApiKey field is returned once only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentApiKeyResponseDTO"}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"API skill is not enabled on this agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create agent API key","tags":["Organization API Key","Agent API Keys"]}}}}
```

## Get agent API key

> Returns metadata for a single API key. The full key value is never returned — only a masked preview.

```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":{"AgentApiKeyResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the API key."},"name":{"type":"string","description":"Label for the API key."},"keyPreview":{"type":"string","description":"Masked preview of the API key. The full key is only returned when the key is created or rotated."},"status":{"type":"string","enum":["active","expired","revoked"],"description":"Current status of the API key."},"expiresAt":{"type":"string","nullable":true,"description":"Expiry date of the API key (YYYY-MM-DD). Null if the key does not expire."},"revokedAt":{"type":"string","nullable":true,"description":"Timestamp when the API key was revoked. Null if the key is still active."},"createdAt":{"type":"string","description":"Timestamp when the API key was created."}},"required":["id","name","keyPreview","status","expiresAt","revokedAt","createdAt"]},"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"]}}},"paths":{"/external/agent-api-keys/{id}/api-key/{keyId}":{"get":{"description":"Returns metadata for a single API key. The full key value is never returned — only a masked preview.","operationId":"ExternalApiAgentApiKeysController_getApiKey","parameters":[{"name":"keyId","required":true,"in":"path","description":"Unique identifier of the API key.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"API key metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentApiKeyResponseDTO"}}}},"404":{"description":"Agent or API key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Get agent API key","tags":["Organization API Key","Agent API Keys"]}}}}
```

## Revoke agent API key

> Revokes the specified API key. The key is immediately invalidated. Use POST /rotate to revoke and replace in a single operation.

```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":{"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"]}}},"paths":{"/external/agent-api-keys/{id}/api-key/{keyId}":{"delete":{"description":"Revokes the specified API key. The key is immediately invalidated. Use POST /rotate to revoke and replace in a single operation.","operationId":"ExternalApiAgentApiKeysController_deleteApiKey","parameters":[{"name":"keyId","required":true,"in":"path","description":"Unique identifier of the API key to revoke.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"204":{"description":"API key revoked."},"404":{"description":"Agent or API key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Revoke agent API key","tags":["Organization API Key","Agent API Keys"]}}}}
```

## Rotate agent API key

> Revokes the specified API key and creates a new one. The new key is returned once — store it securely as it cannot be retrieved again. The previous key is immediately invalidated.

```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":{"CreateAgentApiKeyBodyDTO":{"type":"object","properties":{"name":{"type":"string","description":"Label for the API key."},"expiresAt":{"type":"string","description":"Expiry date in ISO 8601 format (YYYY-MM-DD)."}},"required":["name","expiresAt"]},"CreateAgentApiKeyResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the API key."},"name":{"type":"string","description":"Label for the API key."},"keyPreview":{"type":"string","description":"Masked preview of the API key. The full key is only returned when the key is created or rotated."},"status":{"type":"string","enum":["active","expired","revoked"],"description":"Current status of the API key."},"expiresAt":{"type":"string","nullable":true,"description":"Expiry date of the API key (YYYY-MM-DD). Null if the key does not expire."},"revokedAt":{"type":"string","nullable":true,"description":"Timestamp when the API key was revoked. Null if the key is still active."},"createdAt":{"type":"string","description":"Timestamp when the API key was created."},"agentApiKey":{"type":"string","description":"The full API key. This value is returned only once — at creation or rotation. Store it securely; it cannot be retrieved again."}},"required":["id","name","keyPreview","status","expiresAt","revokedAt","createdAt","agentApiKey"]},"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"]}}},"paths":{"/external/agent-api-keys/{id}/api-key/{keyId}/rotate":{"post":{"description":"Revokes the specified API key and creates a new one. The new key is returned once — store it securely as it cannot be retrieved again. The previous key is immediately invalidated.","operationId":"ExternalApiAgentApiKeysController_rotateApiKey","parameters":[{"name":"keyId","required":true,"in":"path","description":"Unique identifier of the API key to rotate.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentApiKeyBodyDTO"}}}},"responses":{"201":{"description":"New API key created. Previous key revoked. The agentApiKey field is returned once only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentApiKeyResponseDTO"}}}},"404":{"description":"Agent or API key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Rotate agent API key","tags":["Organization API Key","Agent API Keys"]}}}}
```

## List agent functions

> Returns all functions registered on an agent.

```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":{"AgentFunctionResponseDTO":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"definition":{"type":"object","description":"JSON Schema for the function parameters."},"headersConfigured":{"type":"boolean","description":"Whether custom headers are configured on this function. Header values are never returned."},"status":{"type":"string","enum":["active","inactive"]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","agentId","name","description","url","definition","headersConfigured","status","createdAt","updatedAt"]},"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"]}}},"paths":{"/external/agent-functions/{id}/functions":{"get":{"description":"Returns all functions registered on an agent.","operationId":"ExternalApiAgentFunctionsController_getAgentFunctions","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"List of agent functions.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentFunctionResponseDTO"}}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"List agent functions","tags":["Organization API Key","Agent Functions"]}}}}
```

## Create agent function

> Registers a new function on an agent. The agent can invoke this function mid-conversation to call an external webhook. Header values are write-only and never returned in GET responses.

```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":{"CreateAgentFunctionBodyDTO":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the function."},"internalName":{"type":"string","description":"Stable internal identifier the agent runtime uses to reference this function. Must be unique per agent and match /[a-zA-Z0-9_-]/, max 64 characters. Unlike the display name it is not derived and does not change when the name changes."},"description":{"type":"string","description":"Human-readable description of what the function does. The agent uses this to decide when to call it."},"url":{"type":"string","description":"HTTPS URL the agent will POST to when invoking this function."},"definition":{"type":"object","description":"JSON Schema object defining the parameters the agent sends when calling this function. Must be a valid JSON Schema (type: object with properties)."},"headers":{"type":"object","description":"HTTP headers sent with every function call. Values are write-only — they are never returned in GET responses. Use for auth tokens or shared secrets."},"status":{"type":"string","enum":["active","inactive"],"description":"Initial status of the function.","default":"active"}},"required":["name","internalName","description","url","definition"]},"AgentFunctionResponseDTO":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"definition":{"type":"object","description":"JSON Schema for the function parameters."},"headersConfigured":{"type":"boolean","description":"Whether custom headers are configured on this function. Header values are never returned."},"status":{"type":"string","enum":["active","inactive"]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","agentId","name","description","url","definition","headersConfigured","status","createdAt","updatedAt"]},"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/agent-functions/{id}/functions":{"post":{"description":"Registers a new function on an agent. The agent can invoke this function mid-conversation to call an external webhook. Header values are write-only and never returned in GET responses.","operationId":"ExternalApiAgentFunctionsController_createAgentFunction","parameters":[{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentFunctionBodyDTO"}}}},"responses":{"201":{"description":"Function created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFunctionResponseDTO"}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"409":{"description":"A function with this name already exists on the agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create agent function","tags":["Organization API Key","Agent Functions"]}}}}
```

## Get agent function

> Returns a single function by ID. Header values are never returned.

```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":{"AgentFunctionResponseDTO":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"definition":{"type":"object","description":"JSON Schema for the function parameters."},"headersConfigured":{"type":"boolean","description":"Whether custom headers are configured on this function. Header values are never returned."},"status":{"type":"string","enum":["active","inactive"]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","agentId","name","description","url","definition","headersConfigured","status","createdAt","updatedAt"]},"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"]}}},"paths":{"/external/agent-functions/{id}/functions/{functionId}":{"get":{"description":"Returns a single function by ID. Header values are never returned.","operationId":"ExternalApiAgentFunctionsController_getAgentFunctionById","parameters":[{"name":"functionId","required":true,"in":"path","description":"Unique identifier of the function.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"Agent function details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFunctionResponseDTO"}}}},"404":{"description":"Agent or function not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Get agent function","tags":["Organization API Key","Agent Functions"]}}}}
```

## Update agent function

> Updates a function. All fields are optional — only supplied fields are updated. Supplying headers replaces all existing headers. Pass headers: {} to clear all headers.

```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":{"UpdateAgentFunctionBodyDTO":{"type":"object","properties":{"name":{"type":"string","description":"Display name for the function."},"internalName":{"type":"string","description":"Stable internal identifier for the function. Must be unique per agent and match /[a-zA-Z0-9_-]/, max 64 characters."},"description":{"type":"string","description":"Description of what the function does."},"url":{"type":"string","description":"HTTPS URL the agent will POST to."},"definition":{"type":"object","description":"JSON Schema for function parameters."},"headers":{"type":"object","description":"Replaces all existing headers. Pass an empty object {} to clear headers. Values are write-only and never returned in GET responses."},"status":{"type":"string","enum":["active","inactive"]}}},"AgentFunctionResponseDTO":{"type":"object","properties":{"id":{"type":"string"},"agentId":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"definition":{"type":"object","description":"JSON Schema for the function parameters."},"headersConfigured":{"type":"boolean","description":"Whether custom headers are configured on this function. Header values are never returned."},"status":{"type":"string","enum":["active","inactive"]},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","agentId","name","description","url","definition","headersConfigured","status","createdAt","updatedAt"]},"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"]}}},"paths":{"/external/agent-functions/{id}/functions/{functionId}":{"put":{"description":"Updates a function. All fields are optional — only supplied fields are updated. Supplying headers replaces all existing headers. Pass headers: {} to clear all headers.","operationId":"ExternalApiAgentFunctionsController_updateAgentFunction","parameters":[{"name":"functionId","required":true,"in":"path","description":"Unique identifier of the function.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentFunctionBodyDTO"}}}},"responses":{"200":{"description":"Updated function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFunctionResponseDTO"}}}},"404":{"description":"Agent or function not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Update agent function","tags":["Organization API Key","Agent Functions"]}}}}
```

## Delete agent function

> Soft-deletes a function. The agent will no longer be able to invoke it.

```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":{"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"]}}},"paths":{"/external/agent-functions/{id}/functions/{functionId}":{"delete":{"description":"Soft-deletes a function. The agent will no longer be able to invoke it.","operationId":"ExternalApiAgentFunctionsController_deleteAgentFunction","parameters":[{"name":"functionId","required":true,"in":"path","description":"Unique identifier of the function.","schema":{"type":"string"}},{"name":"id","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"204":{"description":"Function deleted."},"404":{"description":"Agent or function not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Delete agent function","tags":["Organization API Key","Agent Functions"]}}}}
```

## Get live chat configuration

> Returns the live chat skill configuration for an agent.

```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":{"AgentLiveChatResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING","SLACK","DATA_RETENTION","ORCHESTRATOR","MS_TEAMS","MESSAGE_QUOTA"]},"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."},"agentId":{"type":"string","description":"Unique identifier of the agent."},"embedKey":{"type":"string","description":"Public, non-secret identifier used to embed the live chat widget on a website. Safe to include in client-side code. Generated the first time the skill is configured."},"welcomeMessage":{"type":"string","description":"Welcome message shown when the chat widget opens."},"avatarUrl":{"type":"string","description":"Avatar image URL for the chat widget.","nullable":true}},"required":["systemName","status","limitUnavailableDates","unavailableDates","unavailableDatesMessage","agentId","embedKey"]},"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"]},"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"]}}},"paths":{"/external/live-chat-skill/{agentId}":{"get":{"description":"Returns the live chat skill configuration for an agent.","operationId":"ExternalApiAgentLiveChatController_getAgentLiveChat","parameters":[{"name":"agentId","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"Live chat configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLiveChatResponseDTO"}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Get live chat configuration","tags":["Organization API Key","Live Chat"]}}}}
```

## Update live chat configuration

> Updates the live chat skill configuration. All fields are optional.

```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":{"UpdateAgentLiveChatBodyDTO":{"type":"object","properties":{"titleLine1":{"type":"string","description":"First line of the chat widget title."},"titleLine2":{"type":"string","description":"Second line of the chat widget title."},"welcomeMessage":{"type":"string","description":"Welcome message shown when the chat widget opens."},"avatarStoragePath":{"type":"string","description":"Storage path returned by the image upload-url endpoint. The API converts it to a public URL before saving the live chat configuration. Pass null to remove the avatar.","nullable":true},"color":{"type":"string","description":"Primary color of the chat widget."},"disclaimer":{"type":"string","description":"Disclaimer message shown in the widget."},"chatFooterContent":{"type":"string","description":"Chat footer content below the input (e.g. privacy policy)."},"suggestions":{"description":"Suggested prompts shown in the widget.","type":"array","items":{"type":"string"}},"links":{"description":"Links displayed in the chat widget. Pass an empty array to remove all links.","type":"array","items":{"$ref":"#/components/schemas/LiveChatLinkBodyDTO"}},"whitelistedIps":{"description":"Whitelisted IP addresses.","type":"array","items":{"type":"string"}},"restrictedCountries":{"description":"Restricted country codes.","type":"array","items":{"type":"string"}},"limitUnavailableDates":{"type":"boolean","description":"Whether live chat should be unavailable on unavailableDates."},"unavailableDates":{"description":"Dates (YYYY-MM-DD) when live chat is unavailable.","type":"array","items":{"type":"string"}},"unavailableDatesMessage":{"type":"string","description":"Message shown when live chat is unavailable on unavailableDates."}}},"LiveChatLinkBodyDTO":{"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"]},"AgentLiveChatResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING","SLACK","DATA_RETENTION","ORCHESTRATOR","MS_TEAMS","MESSAGE_QUOTA"]},"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."},"agentId":{"type":"string","description":"Unique identifier of the agent."},"embedKey":{"type":"string","description":"Public, non-secret identifier used to embed the live chat widget on a website. Safe to include in client-side code. Generated the first time the skill is configured."},"welcomeMessage":{"type":"string","description":"Welcome message shown when the chat widget opens."},"avatarUrl":{"type":"string","description":"Avatar image URL for the chat widget.","nullable":true}},"required":["systemName","status","limitUnavailableDates","unavailableDates","unavailableDatesMessage","agentId","embedKey"]},"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"]},"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"]}}},"paths":{"/external/live-chat-skill/{agentId}":{"put":{"description":"Updates the live chat skill configuration. All fields are optional.","operationId":"ExternalApiAgentLiveChatController_updateAgentLiveChat","parameters":[{"name":"agentId","required":true,"in":"path","description":"Unique identifier of the agent.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentLiveChatBodyDTO"}}}},"responses":{"200":{"description":"Updated live chat configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLiveChatResponseDTO"}}}},"404":{"description":"Agent not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}}},"summary":"Update live chat configuration","tags":["Organization API Key","Live Chat"]}}}}
```

## Create agent image upload URL

> Generates a signed URL for uploading an agent avatar or live chat image. The returned storagePath can be supplied as avatarStoragePath to the live chat update endpoint once the upload completes.

```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":{"CreateAgentImageUploadUrlBodyDTO":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file to upload."},"contentType":{"type":"string","enum":["image/png","image/jpeg","image/gif","image/webp"],"description":"MIME type of the file to upload."}},"required":["fileName","contentType"]},"AgentImageUploadUrlResponseDTO":{"type":"object","properties":{"signedUrl":{"type":"string","description":"Signed URL to PUT the file contents to."},"storagePath":{"type":"string","description":"Storage path for the uploaded file. Supply this as avatarStoragePath to the live chat update endpoint once the upload completes."}},"required":["signedUrl","storagePath"]}}},"paths":{"/external/live-chat-skill/images/upload-url":{"post":{"description":"Generates a signed URL for uploading an agent avatar or live chat image. The returned storagePath can be supplied as avatarStoragePath to the live chat update endpoint once the upload completes.","operationId":"ExternalApiAgentLiveChatController_createImageUploadUrl","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentImageUploadUrlBodyDTO"}}}},"responses":{"201":{"description":"Signed upload URL created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentImageUploadUrlResponseDTO"}}}}},"summary":"Create agent image upload URL","tags":["Organization API Key","Agent Images"]}}}}
```

## Get agent roles by organization API key

> Fetches agent roles by organization API key. The response includes agent roles 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":{"GetAgentRoleByApiKeyResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the agent role.","format":"uuid"},"name":{"type":"string","description":"Name of the agent role."},"description":{"type":"string","description":"Description of the agent role."}},"required":["id","name","description"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/agent-roles/by-api-key":{"get":{"description":"Fetches agent roles by organization API key. The response includes agent roles details.","operationId":"ExternalApiAgentRolesController_getAgentRolesByApiKey","parameters":[],"responses":{"200":{"description":"Successfully retrieved agent roles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentRoleByApiKeyResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get agent roles by organization API key","tags":["Organization API Key","Agent Roles"]}}}}
```

## Create organization via organization API key

> Creates a new organization under the provided license key, exactly like creating an organization in the application. The license key is validated by the raia license service and a subscription (or trial) is attached. When ownerUserId is provided, that user must belong to the calling organization and becomes the owner; otherwise, the creator of the calling organization becomes the owner.

```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":{"ExternalApiCreateOrganizationByOrganizationApiKeyBodyDTO":{"type":"object","properties":{"name":{"type":"string","description":"Name of the new organization.","maxLength":255},"licenseKey":{"type":"string","description":"License key the new organization is created under."},"ownerUserId":{"type":"string","description":"ID of a user in the calling organization who will own the new organization. Defaults to the calling organization creator."}},"required":["name","licenseKey"]},"ExternalApiGetOrganizationResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Organization ID.","format":"uuid"},"name":{"type":"string","description":"Organization name."},"status":{"type":"string","enum":["active","pending","archived","blocked"],"description":"Organization status."},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"},"createdBy":{"description":"Created by.","allOf":[{"$ref":"#/components/schemas/ExternalApiCreatedByDTO"}]},"subscription":{"description":"Organization subscription.","allOf":[{"$ref":"#/components/schemas/ExternalApiSubscriptionResponseDTO"}]}},"required":["id","name","status","createdAt","updatedAt","createdBy","subscription"]},"ExternalApiCreatedByDTO":{"type":"object","properties":{"id":{"type":"string","description":"ID of the creator.","format":"uuid"},"email":{"type":"string","description":"Email of the creator."},"firstName":{"type":"string","description":"First name of the creator."},"lastName":{"type":"string","description":"Last name of the creator."}},"required":["id","email","firstName","lastName"]},"ExternalApiSubscriptionResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Subscription ID.","format":"uuid"},"title":{"type":"string","description":"Subscription title."},"description":{"type":"string","description":"Subscription description."},"agentsAmount":{"type":"number","description":"Number of agents in the subscription."},"tokensAmountPerMonth":{"type":"number","description":"OpenAI tokens amount in the subscription."},"secondsAmountPerMonth":{"type":"number","description":"Vapi seconds amount in the subscription."},"smsAmountPerMonth":{"type":"number","description":"Number of SMS in the subscription."},"emailsAmountPerMonth":{"type":"number","description":"Number of Emails in the subscription."},"usersWithAccessAmount":{"type":"number","description":"Number of users in organizations."},"status":{"type":"string","enum":["active","inactive"],"description":"Subscription status."},"visibility":{"type":"string","enum":["public","private"],"description":"Subscription visibility."},"isTrial":{"type":"boolean","description":"True if subscription is trial."},"createdBy":{"description":"Created by.","allOf":[{"$ref":"#/components/schemas/ExternalApiCreatedByDTO"}]},"createdAt":{"format":"date-time","type":"string","description":"Creation timestamp"},"updatedAt":{"format":"date-time","type":"string","description":"Last update timestamp"},"organizationsCount":{"type":"number","description":"Number of organizations with current subscription."},"price":{"type":"number","description":"Subscription in cent."}},"required":["id","title","description","agentsAmount","tokensAmountPerMonth","secondsAmountPerMonth","smsAmountPerMonth","emailsAmountPerMonth","usersWithAccessAmount","status","visibility","isTrial","createdBy","createdAt","updatedAt","organizationsCount","price"]},"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/organizations/by-organization-api-key":{"post":{"description":"Creates a new organization under the provided license key, exactly like creating an organization in the application. The license key is validated by the raia license service and a subscription (or trial) is attached. When ownerUserId is provided, that user must belong to the calling organization and becomes the owner; otherwise, the creator of the calling organization becomes the owner.","operationId":"ExternalApiOrganizationsController_createOrganizationByOrganizationApiKey","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalApiCreateOrganizationByOrganizationApiKeyBodyDTO"}}}},"responses":{"201":{"description":"Successfully created the organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalApiGetOrganizationResponseDTO"}}}},"400":{"description":"Invalid license key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Requested owner is not a member of the calling organization, or the calling organization creator was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create organization via organization API key","tags":["Organization API Key","Organizations"]}}}}
```

## Get all platform users for the current organization.

> Retrieves all platform users for the current organization, including their organization-level role and membership status. Optionally filter by role and/or status.

```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":{"GetAllOrganizationPlatformUsersResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"email":{"type":"string","description":"User email"},"phoneNumber":{"type":"string","description":"User phone number"},"firstName":{"type":"string","description":"User first name"},"lastName":{"type":"string","description":"User last name"},"organizationRole":{"type":"string","enum":["owner","admin","manager","user","copilot_user","copilot_admin","guest"],"description":"Role of the user in the organization."},"organizationStatus":{"type":"string","enum":["active","inactive"],"description":"Status of the user's membership in the organization."}},"required":["id","email","phoneNumber","firstName","lastName","organizationRole","organizationStatus"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/platform-users":{"get":{"description":"Retrieves all platform users for the current organization, including their organization-level role and membership status. Optionally filter by role and/or status.","operationId":"ExternalApiPlatformUsersController_getAllOrganizationPlatformUsers","parameters":[{"name":"role","required":false,"in":"query","description":"Platform user organization role.","schema":{"type":"string","enum":["owner","admin","manager","user","copilot_user","copilot_admin","guest"]}},{"name":"status","required":false,"in":"query","description":"Status of the user's membership in the organization.","schema":{"type":"string","enum":["active","inactive"]}}],"responses":{"200":{"description":"Successfully retrieved all platform users for the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAllOrganizationPlatformUsersResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get all platform users for the current organization.","tags":["Organization API Key","Platform Users"]}}}}
```

## Get agents by platform user via organization API key

> Fetches all agents a platform user has access to within the current organization, together with the role granting that access. Identify the user by exactly one of userId or email; the user must belong to the organization resolved from the Organization API key. Access includes direct user-to-agent assignments and, for active organization owners and admins, implicit access to every agent in the organization.

```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":{"GetAgentsByPlatformUserResponseDTO":{"type":"object","properties":{"user":{"description":"The platform user the agents belong to.","allOf":[{"$ref":"#/components/schemas/ExternalApiPlatformUserSummaryDTO"}]},"agents":{"description":"Agents the user has access to, with access control data.","type":"array","items":{"$ref":"#/components/schemas/ExternalApiPlatformUserAgentAccessDTO"}}},"required":["user","agents"]},"ExternalApiPlatformUserSummaryDTO":{"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"},"organizationRole":{"type":"string","enum":["owner","admin","manager","user","copilot_user","copilot_admin","guest"],"description":"Role of the user in the organization."},"organizationStatus":{"type":"string","enum":["active","inactive"],"description":"Status of the user's membership in the organization."}},"required":["id","email","firstName","lastName","organizationRole","organizationStatus"]},"ExternalApiPlatformUserAgentAccessDTO":{"type":"object","properties":{"id":{"type":"string","description":"Agent ID"},"name":{"type":"string","description":"Agent name"},"publicName":{"type":"string","description":"Agent public name"},"status":{"type":"string","enum":["active","inactive","draft"],"description":"Agent status"},"avatarUrl":{"type":"string","nullable":true,"description":"Agent 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 access is granted only 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."},"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":"Agent creation date"}},"required":["id","name","publicName","status","accessSource","createdAt"]},"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/platform-users/agents":{"get":{"description":"Fetches all agents a platform user has access to within the current organization, together with the role granting that access. Identify the user by exactly one of userId or email; the user must belong to the organization resolved from the Organization API key. Access includes direct user-to-agent assignments and, for active organization owners and admins, implicit access to every agent in the organization.","operationId":"ExternalApiPlatformUsersController_getAgentsByPlatformUser","parameters":[{"name":"userId","required":false,"in":"query","description":"Platform user ID. Provide exactly one of userId or email.","schema":{"format":"uuid","type":"string"}},{"name":"email","required":false,"in":"query","description":"Platform user email. Provide exactly one of userId or email.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved the agents the user has access to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentsByPlatformUserResponseDTO"}}}},"400":{"description":"Provide exactly one of userId or email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"User not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get agents by platform user via organization API key","tags":["Organization API Key","Platform Users","Agents"]}}}}
```

## Update a platform user role or status via organization API key

> Updates the organization-level role and/or membership status of a platform user in the current organization. Provide at least one of role or status. Setting status to inactive suspends the user's access to the organization without removing assignments or history; setting it back to active restores access. The owner role can be neither assigned nor modified through the external API, and the user who created the Organization API key in use cannot be modified with it.

```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":{"UpdateOrganizationPlatformUserBodyDTO":{"type":"object","properties":{"role":{"type":"string","enum":["admin","manager","user","copilot_user","copilot_admin","guest"],"description":"New role of the user in the organization. The owner role cannot be assigned through the external API. Provide at least one of role or status."},"status":{"type":"string","enum":["active","inactive"],"description":"New status of the user's membership in the organization. Inactive suspends access without removing assignments or history. Provide at least one of role or status."}}},"UpdateOrganizationPlatformUserResponseDTO":{"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"},"organizationRole":{"type":"string","enum":["owner","admin","manager","user","copilot_user","copilot_admin","guest"],"description":"Role of the user in the organization after the update."},"organizationStatus":{"type":"string","enum":["active","inactive"],"description":"Status of the user's membership in the organization after the update."}},"required":["id","email","firstName","lastName","organizationRole","organizationStatus"]},"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/platform-users/{userId}":{"patch":{"description":"Updates the organization-level role and/or membership status of a platform user in the current organization. Provide at least one of role or status. Setting status to inactive suspends the user's access to the organization without removing assignments or history; setting it back to active restores access. The owner role can be neither assigned nor modified through the external API, and the user who created the Organization API key in use cannot be modified with it.","operationId":"ExternalApiPlatformUsersController_updateOrganizationPlatformUser","parameters":[{"name":"userId","required":true,"in":"path","description":"Platform user ID.","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationPlatformUserBodyDTO"}}}},"responses":{"200":{"description":"Successfully updated the platform user.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationPlatformUserResponseDTO"}}}},"400":{"description":"Provide at least one of role or status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"User not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Update a platform user role or status via organization API key","tags":["Organization API Key","Platform Users"]}}}}
```

## List packs via organization API key

> Retrieves a paginated list of the organization's packs. Optionally filter by name and include inactive packs.

```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":{"PaginatedPacksResponseDTO":{"type":"object","properties":{"data":{"description":"Packs on the current page.","type":"array","items":{"$ref":"#/components/schemas/PackResponseDTO"}},"total":{"type":"number","description":"Total number of packs matching the query."},"page":{"type":"number","description":"Zero-based current page number."},"pageSize":{"type":"number","description":"Page size used for the query."},"totalPages":{"type":"number","description":"Total number of pages."}},"required":["data","total","page","pageSize","totalPages"]},"PackResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Pack ID."},"name":{"type":"string","description":"Name of the pack."},"description":{"type":"string","description":"Description of the pack."},"instructions":{"type":"string","description":"Shared instructions / core training text."},"isPrivate":{"type":"boolean","description":"Whether the pack is private to the API key owner."},"status":{"type":"string","enum":["active","inactive"],"description":"Status of the pack."},"usedInAgentsCount":{"type":"number","description":"Number of agents this pack is currently linked to."},"createdAt":{"format":"date-time","type":"string","description":"Creation date."},"updatedAt":{"format":"date-time","type":"string","description":"Last update date."}},"required":["id","name","description","instructions","isPrivate","status","usedInAgentsCount","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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/packs":{"get":{"description":"Retrieves a paginated list of the organization's packs. Optionally filter by name and include inactive packs.","operationId":"ExternalApiAgentPacksController_getPacks","parameters":[{"name":"page","required":false,"in":"query","description":"Zero-based page number.","schema":{"default":0,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of packs per page.","schema":{"default":10,"type":"number"}},{"name":"searchKeyword","required":false,"in":"query","description":"Filter packs whose name contains this keyword.","schema":{"type":"string"}},{"name":"includeInactive","required":false,"in":"query","description":"Include inactive packs in the result. Requires the Organization API key owner to have permission to read inactive packs.","schema":{"default":false,"type":"boolean"}},{"name":"orderDirection","required":false,"in":"query","description":"Sort direction by creation date.","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"description":"Successfully retrieved the packs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPacksResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"List packs via organization API key","tags":["Organization API Key","Packs"]}}}}
```

## Create a pack via organization API key

> Creates a new pack in the organization resolved from the Organization API key. Packs store shared instructions (core training) that can be linked to and imported by multiple agents. The pack is owned by the organization member who created the API key.

```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":{"CreatePackBodyDTO":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name of the pack."},"description":{"type":"string","description":"Short description of what the pack contains."},"instructions":{"type":"string","description":"The shared instructions / core training text imported into agents linked to this pack."},"isPrivate":{"type":"boolean","default":false,"description":"When true the pack is private to the organization member who owns the Organization API key. Defaults to false (visible to the whole organization)."},"files":{"description":"Documents to attach to the pack on creation. Upload each file to a signed URL first (see the pack document upload-url endpoint) and pass the returned fileName and storagePath here.","type":"array","items":{"$ref":"#/components/schemas/PackDocumentInputDTO"}}},"required":["name","description","instructions"]},"PackDocumentInputDTO":{"type":"object","properties":{"fileName":{"type":"string","description":"Original file name of the uploaded document."},"storagePath":{"type":"string","description":"Storage path returned by the pack document upload-url endpoint after the file has been uploaded to the signed URL."}},"required":["fileName","storagePath"]},"PackWithFilesResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Pack ID."},"name":{"type":"string","description":"Name of the pack."},"description":{"type":"string","description":"Description of the pack."},"instructions":{"type":"string","description":"Shared instructions / core training text."},"isPrivate":{"type":"boolean","description":"Whether the pack is private to the API key owner."},"status":{"type":"string","enum":["active","inactive"],"description":"Status of the pack."},"usedInAgentsCount":{"type":"number","description":"Number of agents this pack is currently linked to."},"createdAt":{"format":"date-time","type":"string","description":"Creation date."},"updatedAt":{"format":"date-time","type":"string","description":"Last update date."},"files":{"description":"Documents attached to the pack, with signed download URLs.","type":"array","items":{"$ref":"#/components/schemas/PackFileResponseDTO"}}},"required":["id","name","description","instructions","isPrivate","status","usedInAgentsCount","createdAt","updatedAt","files"]},"PackFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID."},"fileName":{"type":"string","description":"Original file name."},"url":{"type":"string","description":"Time-limited signed download URL for the file."},"size":{"type":"number","description":"File size in bytes."},"createdAt":{"format":"date-time","type":"string","description":"File creation date."},"updatedAt":{"format":"date-time","type":"string","description":"File last update date."}},"required":["id","fileName","url","size","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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/packs":{"post":{"description":"Creates a new pack in the organization resolved from the Organization API key. Packs store shared instructions (core training) that can be linked to and imported by multiple agents. The pack is owned by the organization member who created the API key.","operationId":"ExternalApiAgentPacksController_createPack","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePackBodyDTO"}}}},"responses":{"201":{"description":"Successfully created the pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackWithFilesResponseDTO"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create a pack via organization API key","tags":["Organization API Key","Packs"]}}}}
```

## Get a pack via organization API key

> Retrieves a single pack by id, including its attached documents with signed download URLs. The pack must belong to the API key's organization.

```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":{"PackWithFilesResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Pack ID."},"name":{"type":"string","description":"Name of the pack."},"description":{"type":"string","description":"Description of the pack."},"instructions":{"type":"string","description":"Shared instructions / core training text."},"isPrivate":{"type":"boolean","description":"Whether the pack is private to the API key owner."},"status":{"type":"string","enum":["active","inactive"],"description":"Status of the pack."},"usedInAgentsCount":{"type":"number","description":"Number of agents this pack is currently linked to."},"createdAt":{"format":"date-time","type":"string","description":"Creation date."},"updatedAt":{"format":"date-time","type":"string","description":"Last update date."},"files":{"description":"Documents attached to the pack, with signed download URLs.","type":"array","items":{"$ref":"#/components/schemas/PackFileResponseDTO"}}},"required":["id","name","description","instructions","isPrivate","status","usedInAgentsCount","createdAt","updatedAt","files"]},"PackFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID."},"fileName":{"type":"string","description":"Original file name."},"url":{"type":"string","description":"Time-limited signed download URL for the file."},"size":{"type":"number","description":"File size in bytes."},"createdAt":{"format":"date-time","type":"string","description":"File creation date."},"updatedAt":{"format":"date-time","type":"string","description":"File last update date."}},"required":["id","fileName","url","size","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/packs/{id}":{"get":{"description":"Retrieves a single pack by id, including its attached documents with signed download URLs. The pack must belong to the API key's organization.","operationId":"ExternalApiAgentPacksController_getPackById","parameters":[{"name":"id","required":true,"in":"path","description":"Pack ID.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Successfully retrieved the pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackWithFilesResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Pack not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get a pack via organization API key","tags":["Organization API Key","Packs"]}}}}
```

## Update a pack via organization API key

> Updates a pack's name, description, instructions, privacy or status. Provide at least one field. The pack must belong to the API key's organization.

```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":{"UpdatePackBodyDTO":{"type":"object","properties":{"name":{"type":"string","description":"New name of the pack."},"description":{"type":"string","description":"New description of the pack."},"instructions":{"type":"string","description":"New shared instructions / core training text."},"isPrivate":{"type":"boolean","description":"Whether the pack is private to the Organization API key owner."},"status":{"type":"string","enum":["active","inactive"],"description":"Status of the pack. Inactive packs are hidden from agents but not deleted."}}},"PackWithFilesResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Pack ID."},"name":{"type":"string","description":"Name of the pack."},"description":{"type":"string","description":"Description of the pack."},"instructions":{"type":"string","description":"Shared instructions / core training text."},"isPrivate":{"type":"boolean","description":"Whether the pack is private to the API key owner."},"status":{"type":"string","enum":["active","inactive"],"description":"Status of the pack."},"usedInAgentsCount":{"type":"number","description":"Number of agents this pack is currently linked to."},"createdAt":{"format":"date-time","type":"string","description":"Creation date."},"updatedAt":{"format":"date-time","type":"string","description":"Last update date."},"files":{"description":"Documents attached to the pack, with signed download URLs.","type":"array","items":{"$ref":"#/components/schemas/PackFileResponseDTO"}}},"required":["id","name","description","instructions","isPrivate","status","usedInAgentsCount","createdAt","updatedAt","files"]},"PackFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID."},"fileName":{"type":"string","description":"Original file name."},"url":{"type":"string","description":"Time-limited signed download URL for the file."},"size":{"type":"number","description":"File size in bytes."},"createdAt":{"format":"date-time","type":"string","description":"File creation date."},"updatedAt":{"format":"date-time","type":"string","description":"File last update date."}},"required":["id","fileName","url","size","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/packs/{id}":{"put":{"description":"Updates a pack's name, description, instructions, privacy or status. Provide at least one field. The pack must belong to the API key's organization.","operationId":"ExternalApiAgentPacksController_updatePack","parameters":[{"name":"id","required":true,"in":"path","description":"Pack ID.","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePackBodyDTO"}}}},"responses":{"200":{"description":"Successfully updated the pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackWithFilesResponseDTO"}}}},"400":{"description":"Provide at least one field to update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Pack not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Update a pack via organization API key","tags":["Organization API Key","Packs"]}}}}
```

## Delete a pack via organization API key

> Soft-deletes a pack. A pack that is still linked to one or more agents cannot be deleted. The pack must belong to the API key's organization.

```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":{"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/packs/{id}":{"delete":{"description":"Soft-deletes a pack. A pack that is still linked to one or more agents cannot be deleted. The pack must belong to the API key's organization.","operationId":"ExternalApiAgentPacksController_deletePack","parameters":[{"name":"id","required":true,"in":"path","description":"Pack ID.","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Successfully deleted the pack."},"400":{"description":"The pack is still linked to one or more agents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Pack not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Delete a pack via organization API key","tags":["Organization API Key","Packs"]}}}}
```

## Create a pack document upload URL via organization API key

> Creates a time-limited signed URL for uploading a pack document. Upload the file with an HTTP PUT to the returned signedUrl, then attach it to a pack (on create, or via the attach-document endpoint) using the returned storagePath and the file name.

```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":{"CreatePackDocumentUploadUrlBodyDTO":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the document to upload."},"contentType":{"type":"string","enum":["application/msword","application/vnd.openxmlformats-officedocument.wordprocessingml.document","text/plain","text/plain; charset=utf-8","application/pdf","text/markdown","application/json"],"description":"MIME content type of the document to upload."}},"required":["fileName","contentType"]},"CreatePackDocumentUploadUrlResponseDTO":{"type":"object","properties":{"signedUrl":{"type":"string","description":"Time-limited signed URL. Upload the document with an HTTP PUT to this URL."},"storagePath":{"type":"string","description":"Storage path of the uploaded document. Pass this (with fileName) when attaching the document to a pack."}},"required":["signedUrl","storagePath"]},"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"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/packs/documents/upload-url":{"post":{"description":"Creates a time-limited signed URL for uploading a pack document. Upload the file with an HTTP PUT to the returned signedUrl, then attach it to a pack (on create, or via the attach-document endpoint) using the returned storagePath and the file name.","operationId":"ExternalApiAgentPacksController_createDocumentUploadUrl","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePackDocumentUploadUrlBodyDTO"}}}},"responses":{"201":{"description":"Successfully created the signed upload URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePackDocumentUploadUrlResponseDTO"}}}},"400":{"description":"Invalid file name or unsupported content type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create a pack document upload URL via organization API key","tags":["Organization API Key","Packs"]}}}}
```

## Attach a document to a pack via organization API key

> Attaches a previously uploaded document to a pack. Upload the file to a signed URL first (see the pack document upload-url endpoint), then pass the returned fileName and storagePath. The pack must belong to the API key's organization.

```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":{"PackDocumentInputDTO":{"type":"object","properties":{"fileName":{"type":"string","description":"Original file name of the uploaded document."},"storagePath":{"type":"string","description":"Storage path returned by the pack document upload-url endpoint after the file has been uploaded to the signed URL."}},"required":["fileName","storagePath"]},"PackWithFilesResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Pack ID."},"name":{"type":"string","description":"Name of the pack."},"description":{"type":"string","description":"Description of the pack."},"instructions":{"type":"string","description":"Shared instructions / core training text."},"isPrivate":{"type":"boolean","description":"Whether the pack is private to the API key owner."},"status":{"type":"string","enum":["active","inactive"],"description":"Status of the pack."},"usedInAgentsCount":{"type":"number","description":"Number of agents this pack is currently linked to."},"createdAt":{"format":"date-time","type":"string","description":"Creation date."},"updatedAt":{"format":"date-time","type":"string","description":"Last update date."},"files":{"description":"Documents attached to the pack, with signed download URLs.","type":"array","items":{"$ref":"#/components/schemas/PackFileResponseDTO"}}},"required":["id","name","description","instructions","isPrivate","status","usedInAgentsCount","createdAt","updatedAt","files"]},"PackFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID."},"fileName":{"type":"string","description":"Original file name."},"url":{"type":"string","description":"Time-limited signed download URL for the file."},"size":{"type":"number","description":"File size in bytes."},"createdAt":{"format":"date-time","type":"string","description":"File creation date."},"updatedAt":{"format":"date-time","type":"string","description":"File last update date."}},"required":["id","fileName","url","size","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/packs/{id}/documents":{"post":{"description":"Attaches a previously uploaded document to a pack. Upload the file to a signed URL first (see the pack document upload-url endpoint), then pass the returned fileName and storagePath. The pack must belong to the API key's organization.","operationId":"ExternalApiAgentPacksController_attachDocument","parameters":[{"name":"id","required":true,"in":"path","description":"Pack ID.","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackDocumentInputDTO"}}}},"responses":{"200":{"description":"Successfully attached the document to the pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackWithFilesResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Pack not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Attach a document to a pack via organization API key","tags":["Organization API Key","Packs"]}}}}
```

## Remove a document from a pack via organization API key

> Removes a document from a pack by its file id. The pack must belong to the API key's organization.

```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":{"PackWithFilesResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"Pack ID."},"name":{"type":"string","description":"Name of the pack."},"description":{"type":"string","description":"Description of the pack."},"instructions":{"type":"string","description":"Shared instructions / core training text."},"isPrivate":{"type":"boolean","description":"Whether the pack is private to the API key owner."},"status":{"type":"string","enum":["active","inactive"],"description":"Status of the pack."},"usedInAgentsCount":{"type":"number","description":"Number of agents this pack is currently linked to."},"createdAt":{"format":"date-time","type":"string","description":"Creation date."},"updatedAt":{"format":"date-time","type":"string","description":"Last update date."},"files":{"description":"Documents attached to the pack, with signed download URLs.","type":"array","items":{"$ref":"#/components/schemas/PackFileResponseDTO"}}},"required":["id","name","description","instructions","isPrivate","status","usedInAgentsCount","createdAt","updatedAt","files"]},"PackFileResponseDTO":{"type":"object","properties":{"id":{"type":"string","description":"File ID."},"fileName":{"type":"string","description":"Original file name."},"url":{"type":"string","description":"Time-limited signed download URL for the file."},"size":{"type":"number","description":"File size in bytes."},"createdAt":{"format":"date-time","type":"string","description":"File creation date."},"updatedAt":{"format":"date-time","type":"string","description":"File last update date."}},"required":["id","fileName","url","size","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/packs/{id}/documents/{fileId}":{"delete":{"description":"Removes a document from a pack by its file id. The pack must belong to the API key's organization.","operationId":"ExternalApiAgentPacksController_removeDocument","parameters":[{"name":"id","required":true,"in":"path","description":"Pack ID.","schema":{"format":"uuid","type":"string"}},{"name":"fileId","required":true,"in":"path","description":"Document (file) ID to remove from the pack.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Successfully removed the document from the pack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackWithFilesResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Pack not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Remove a document from a pack via organization API key","tags":["Organization API Key","Packs"]}}}}
```

## Link a pack to an agent

> Links a pack to an agent, copying the pack's shared instructions and documents onto the agent. The pack and agent must both belong to the organization resolved from the Organization API key.

```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":{"LinkPackToAgentResponseDTO":{"type":"object","properties":{"agentId":{"type":"string","description":"ID of the agent the pack was linked to."},"packId":{"type":"string","description":"ID of the pack that was linked."}},"required":["agentId","packId"]},"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/packs/{id}/link/{agentId}":{"post":{"description":"Links a pack to an agent, copying the pack's shared instructions and documents onto the agent. The pack and agent must both belong to the organization resolved from the Organization API key.","operationId":"ExternalApiAgentPacksController_linkPackToAgent","parameters":[{"name":"id","required":true,"in":"path","description":"Pack ID.","schema":{"format":"uuid","type":"string"}},{"name":"agentId","required":true,"in":"path","description":"Agent ID.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Successfully linked the pack to the agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkPackToAgentResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Pack or agent not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Link a pack to an agent","tags":["Organization API Key","Packs","Agents"]}}}}
```

## Unlink a pack from an agent

> Removes the link between a pack and an agent. The pack and agent must both belong to the organization resolved from the Organization API key.

```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":{"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/packs/{id}/link/{agentId}":{"delete":{"description":"Removes the link between a pack and an agent. The pack and agent must both belong to the organization resolved from the Organization API key.","operationId":"ExternalApiAgentPacksController_unlinkPackFromAgent","parameters":[{"name":"id","required":true,"in":"path","description":"Pack ID.","schema":{"format":"uuid","type":"string"}},{"name":"agentId","required":true,"in":"path","description":"Agent ID.","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Successfully unlinked the pack from the agent."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Pack or agent not found, or the pack is not linked to the agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Unlink a pack from an agent","tags":["Organization API Key","Packs","Agents"]}}}}
```

## List functions via organization API key

> Retrieves a paginated list of the functions visible to the supplied userId: the organization's shared functions plus that user's own private functions. Optionally filter by name and include inactive functions.

```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":{"PaginatedFunctionsResponseDTO":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FunctionResponseDTO"}},"total":{"type":"number"},"page":{"type":"number"},"pageSize":{"type":"number"},"totalPages":{"type":"number"}},"required":["data","total","page","pageSize","totalPages"]},"FunctionResponseDTO":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"internalName":{"type":"string"},"description":{"type":"string"},"isPrivate":{"type":"boolean","description":"True when the function is private to its owner."},"status":{"type":"string","enum":["active","inactive"]},"url":{"type":"string"},"definition":{"type":"object","additionalProperties":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"userId":{"type":"string","format":"uuid","description":"ID of the organization member who owns the function."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","internalName","description","isPrivate","status","url","definition","userId","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/functions":{"get":{"description":"Retrieves a paginated list of the functions visible to the supplied userId: the organization's shared functions plus that user's own private functions. Optionally filter by name and include inactive functions.","operationId":"ExternalApiFunctionsController_getFunctions","parameters":[{"name":"userId","required":true,"in":"query","description":"ID of the organization member whose visible functions are listed (their private functions plus the organization-wide ones). Must belong to the API key organization.","schema":{"format":"uuid","type":"string"}},{"name":"page","required":false,"in":"query","schema":{"default":0,"type":"number"}},{"name":"pageSize","required":false,"in":"query","schema":{"default":10,"type":"number"}},{"name":"searchKeyword","required":false,"in":"query","description":"Filter functions whose name contains this keyword.","schema":{"type":"string"}},{"name":"includeInactive","required":false,"in":"query","description":"Include inactive functions. Requires the acting user to have permission to read inactive functions.","schema":{"default":false,"type":"boolean"}},{"name":"orderDirection","required":false,"in":"query","description":"Sort direction by creation date.","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"description":"Successfully retrieved the functions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedFunctionsResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"User not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"List functions via organization API key","tags":["Organization API Key","Functions"]}}}}
```

## Create a function via organization API key

> Creates a function in the organization resolved from the Organization API key, owned by the supplied userId. Set isPrivate to true to make the function private to that user ("only for me"); set it to false to make it available to the whole organization. The owner must be a member of the organization and have permission to create functions.

```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":{"CreateFunctionBodyDTO":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","description":"ID of the organization member who will own the function. Must belong to the API key organization. When isPrivate is true the function is visible only to this user; otherwise it is available to the whole organization."},"name":{"type":"string","description":"Human-readable name of the function."},"internalName":{"type":"string","description":"Machine name used as the tool key. 1-64 characters, letters, numbers, underscores and hyphens only. Unique within the organization."},"description":{"type":"string","description":"Description of what the function does."},"url":{"type":"string","description":"HTTPS endpoint invoked when the function runs."},"isPrivate":{"type":"boolean","description":"When true the function is private to the owner (userId) — \"only for me\". When false it is available to the whole organization."},"definition":{"type":"object","additionalProperties":{"type":"string"},"description":"Function definition / parameter schema, as a JSON object of string values."},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true,"description":"Optional HTTP headers sent with the outbound request."}},"required":["userId","name","internalName","description","url","isPrivate","definition"]},"FunctionResponseDTO":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"internalName":{"type":"string"},"description":{"type":"string"},"isPrivate":{"type":"boolean","description":"True when the function is private to its owner."},"status":{"type":"string","enum":["active","inactive"]},"url":{"type":"string"},"definition":{"type":"object","additionalProperties":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"userId":{"type":"string","format":"uuid","description":"ID of the organization member who owns the function."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","internalName","description","isPrivate","status","url","definition","userId","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/functions":{"post":{"description":"Creates a function in the organization resolved from the Organization API key, owned by the supplied userId. Set isPrivate to true to make the function private to that user (\"only for me\"); set it to false to make it available to the whole organization. The owner must be a member of the organization and have permission to create functions.","operationId":"ExternalApiFunctionsController_createFunction","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFunctionBodyDTO"}}}},"responses":{"201":{"description":"Successfully created the function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionResponseDTO"}}}},"400":{"description":"Invalid request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Owner user not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create a function via organization API key","tags":["Organization API Key","Functions"]}}}}
```

## Get a function via organization API key

> Retrieves a single function by id, as seen by the supplied userId. The function must belong to the API key's organization and be visible to that user.

```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":{"FunctionResponseDTO":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"internalName":{"type":"string"},"description":{"type":"string"},"isPrivate":{"type":"boolean","description":"True when the function is private to its owner."},"status":{"type":"string","enum":["active","inactive"]},"url":{"type":"string"},"definition":{"type":"object","additionalProperties":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"userId":{"type":"string","format":"uuid","description":"ID of the organization member who owns the function."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","internalName","description","isPrivate","status","url","definition","userId","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/functions/{id}":{"get":{"description":"Retrieves a single function by id, as seen by the supplied userId. The function must belong to the API key's organization and be visible to that user.","operationId":"ExternalApiFunctionsController_getFunctionById","parameters":[{"name":"id","required":true,"in":"path","description":"Function ID.","schema":{"format":"uuid","type":"string"}},{"name":"userId","required":true,"in":"query","description":"ID of the organization member acting on the function. Must belong to the API key organization.","schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"description":"Successfully retrieved the function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Function or user not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get a function via organization API key","tags":["Organization API Key","Functions"]}}}}
```

## Delete a function via organization API key

> Deletes a function on behalf of the supplied userId. Only the owner can delete a private function. The function must belong to the API key's organization.

```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":{"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/functions/{id}":{"delete":{"description":"Deletes a function on behalf of the supplied userId. Only the owner can delete a private function. The function must belong to the API key's organization.","operationId":"ExternalApiFunctionsController_deleteFunction","parameters":[{"name":"id","required":true,"in":"path","description":"Function ID.","schema":{"format":"uuid","type":"string"}},{"name":"userId","required":true,"in":"query","description":"ID of the organization member acting on the function. Must belong to the API key organization.","schema":{"format":"uuid","type":"string"}}],"responses":{"204":{"description":"Successfully deleted the function."},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Function or user not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Delete a function via organization API key","tags":["Organization API Key","Functions"]}}}}
```

## Update a function via organization API key

> Updates a function on behalf of the supplied userId. Provide at least one field to change. Only the owner can change a private function or toggle its privacy. The function must belong to the API key's organization.

```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":{"UpdateFunctionBodyDTO":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","description":"ID of the organization member acting on the function. Must belong to the API key organization and have access to the function."},"name":{"type":"string"},"internalName":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"isPrivate":{"type":"boolean","description":"Toggle \"only for me\" (true) vs organization-wide (false). Only the owner can change a function's privacy."},"definition":{"type":"object","additionalProperties":{"type":"string"},"description":"Function definition / parameter schema."},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true,"description":"Optional HTTP headers sent with the outbound request."},"status":{"type":"string","enum":["active","inactive"],"description":"Status of the function."}},"required":["userId"]},"FunctionResponseDTO":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"internalName":{"type":"string"},"description":{"type":"string"},"isPrivate":{"type":"boolean","description":"True when the function is private to its owner."},"status":{"type":"string","enum":["active","inactive"]},"url":{"type":"string"},"definition":{"type":"object","additionalProperties":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"userId":{"type":"string","format":"uuid","description":"ID of the organization member who owns the function."},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"required":["id","name","internalName","description","isPrivate","status","url","definition","userId","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/functions/{id}":{"patch":{"description":"Updates a function on behalf of the supplied userId. Provide at least one field to change. Only the owner can change a private function or toggle its privacy. The function must belong to the API key's organization.","operationId":"ExternalApiFunctionsController_updateFunction","parameters":[{"name":"id","required":true,"in":"path","description":"Function ID.","schema":{"format":"uuid","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFunctionBodyDTO"}}}},"responses":{"200":{"description":"Successfully updated the function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FunctionResponseDTO"}}}},"400":{"description":"Provide at least one field to update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestErrorDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"404":{"description":"Function or user not found in the current organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityNotFoundErrorDTO"}}}},"429":{"description":"Rate limit exceeded. Each organization is limited to 1000 requests per 60 seconds for system external API operations."},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Update a function via organization API key","tags":["Organization API Key","Functions"]}}}}
```


---

# 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/organization-api-key.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.