# 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"],"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"],"description":"Reasoning effort of the agent. Required only when mode is reasoning."},"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"}]},"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"],"description":"Open AI model."},"temperature":{"type":"number","description":"OpenAI temperature."},"topP":{"type":"number","description":"OpenAI top_p."},"instructions":{"type":"string","description":"OpenAI instructions."},"isCodeInterpreterEnabled":{"type":"boolean","description":"Is code interpreter enabled."},"isFileSearchEnabled":{"type":"boolean","description":"Is file search enabled."},"fileSearchMaxNumResults":{"type":"number","description":"File search max number of results."},"reasoningEffort":{"type":"string","enum":["low","medium","high","xhigh","minimal","none"],"description":"Reasoning effort of the agent.","nullable":true},"isOutputJsonSchemaEnabled":{"type":"boolean","description":"Is output JSON schema enabled."},"outputJsonSchema":{"type":"string","description":"Output JSON schema of the agent."}},"required":["id","model","temperature","topP","instructions","isCodeInterpreterEnabled","isFileSearchEnabled","fileSearchMaxNumResults","outputJsonSchema"]},"BaseSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]}},"required":["systemName","status"]},"LiveChatSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"color":{"type":"string","description":"Color of the chat widget."},"widgetButtonConfig":{"description":"Embedded chat launcher (widget button) settings with legacy fields normalized.","allOf":[{"$ref":"#/components/schemas/LiveChatWidgetButtonExternalDTO"}]},"titleLine1":{"type":"string","description":"First line of the chat widget title."},"titleLine2":{"type":"string","description":"Second line of the chat widget title."},"intro":{"type":"string","description":"Default introduction message (same as titleLine2; kept for backwards compatibility)."},"links":{"description":"List of links to be displayed in the chat widget.","type":"array","items":{"type":"string"}},"disclaimer":{"type":"string","description":"Disclaimer message."},"chatFooterContent":{"type":"string","description":"Chat footer content below the input (e.g. privacy policy)"},"suggestions":{"description":"List of suggestions for the chat widget.","type":"array","items":{"type":"string"}},"whitelistedIps":{"description":"List of IP addresses that are whitelisted.","type":"array","items":{"type":"string"}},"restrictedCountries":{"description":"List of countries that are restricted.","type":"array","items":{"type":"string"}},"limitUnavailableDates":{"type":"boolean","description":"Whether live chat should be unavailable on the configured unavailableDates (YYYY-MM-DD)."},"unavailableDates":{"description":"Dates (YYYY-MM-DD) when live chat is unavailable (e.g. holidays, maintenance).","type":"array","items":{"type":"string"}},"unavailableDatesMessage":{"type":"string","description":"Custom message to show when live chat is unavailable on unavailableDates."}},"required":["systemName","status","limitUnavailableDates","unavailableDates","unavailableDatesMessage"]},"LiveChatWidgetButtonExternalDTO":{"type":"object","properties":{"mode":{"type":"string","enum":["automatic","on_hover"]},"type":{"type":"string","enum":["icon_only","text_only","icon_and_text"]},"borderRadius":{"type":"string","enum":["0px","8px","100%"]},"size":{"type":"string","description":"Launcher size in pixels "},"selectedTheme":{"type":"string","enum":["light","dark","system"],"description":"Light, dark, or system color resolution for the launcher. Required when launcherTheme is custom."},"lightThemeConfig":{"$ref":"#/components/schemas/LiveChatWidgetButtonThemeExternalDTO"},"darkThemeConfig":{"$ref":"#/components/schemas/LiveChatWidgetButtonThemeExternalDTO"},"launcherAttentionEffect":{"type":"string","enum":["none","pulse"]},"launcherTheme":{"type":"string","enum":["default","solid","gradient","glassmorphism","custom"]},"logoFit":{"type":"string","enum":["cover","contain"]},"launcherTeaser":{"type":"string","enum":["suggestions","proactive","none"]},"proactiveBubble":{"description":"Proactive teaser (when launcherTeaser is proactive).","allOf":[{"$ref":"#/components/schemas/LiveChatWidgetProactiveBubbleExternalDTO"}]}},"required":["mode","type","borderRadius","size","lightThemeConfig","darkThemeConfig","launcherAttentionEffect","launcherTheme","logoFit","launcherTeaser"]},"LiveChatWidgetButtonThemeExternalDTO":{"type":"object","properties":{"backgroundColor":{"type":"string","description":"Launcher button background color (hex)."},"textColor":{"type":"string","description":"Launcher button text and icon color (hex)."}},"required":["backgroundColor","textColor"]},"LiveChatWidgetProactiveBubbleExternalDTO":{"type":"object","properties":{"message":{"type":"string","description":"Proactive teaser copy (when launcherTeaser is proactive)."},"delaySeconds":{"type":"number","description":"Delay in seconds before the proactive teaser (0–3600)."}},"required":["message","delaySeconds"]},"SmsSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"phoneNumber":{"type":"string","description":"Phone number associated with the sms skill."},"defaultSmsIntroduction":{"type":"object","description":"Default SMS introduction."},"smsSignature":{"type":"object","description":"SMS signature."}},"required":["systemName","status","phoneNumber"]},"EmailSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"email":{"type":"string","description":"Email address associated with the email skill."},"senderName":{"type":"string","description":"Name of the email sender."},"defaultSubject":{"type":"string","description":"Email subject."},"defaultEmailIntroduction":{"type":"string","description":"Default email introduction."},"emailSignature":{"type":"string","description":"Default email closing."}},"required":["systemName","status","email"]},"WebhookSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"name":{"type":"string","description":"Webhook skill name."},"description":{"type":"string","description":"Webhook skill description."},"webhooks":{"description":"Webhook configs.","type":"array","items":{"$ref":"#/components/schemas/WebhookResponseDTO"}}},"required":["systemName","status","name","description","webhooks"]},"WebhookResponseDTO":{"type":"object","properties":{"status":{"type":"string","description":"Status of the webhook.","enum":["active","inactive"]},"title":{"type":"string","description":"Webhook title."},"description":{"type":"string","description":"Webhook description."},"url":{"type":"string","description":"Webhook URL."},"triggerCondition":{"type":"string","description":"Webhook trigger condition.","enum":["each_message","end_dialog","start_dialog","chat_currently_unavailable","auto_archive_conversation"]},"headers":{"type":"object","description":"Webhook headers."}},"required":["status","title","description","url","triggerCondition"]},"FunctionsSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]}},"required":["systemName","status"]},"ScoringSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"scoringPrompt":{"type":"string","description":"Scoring prompt."}},"required":["systemName","status"]},"APISkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"apiKey":{"type":"string","description":"API key for the skill.","format":"uuid"}},"required":["systemName","status","apiKey"]},"VoiceSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"vApiAssistantId":{"type":"string","description":"Vapi assistant id."},"vApiPhoneNumberId":{"type":"string","description":"Vapi phone number id."}},"required":["systemName","status","vApiAssistantId","vApiPhoneNumberId"]},"MemorySkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"type":{"type":"string","enum":["BY_USER","BY_AGENT"],"description":"Memory skill type."},"retentionDuration":{"type":"number","description":"Retention duration."}},"required":["systemName","status","type","retentionDuration"]},"ReportSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"frequency":{"type":"string","enum":["DAILY","WEEKLY","MONTHLY"],"description":"Agent report frequency."},"emails":{"description":"Agent report emails.","type":"array","items":{"type":"string"}}},"required":["systemName","status","frequency","emails"]},"ScrapingSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"scrapingConfigs":{"description":"Agent scraping configs.","type":"array","items":{"$ref":"#/components/schemas/ScrapingConfigResponseDTO"}}},"required":["systemName","status","scrapingConfigs"]},"ScrapingConfigResponseDTO":{"type":"object","properties":{"url":{"type":"string","description":"Scraping url."},"startCrawledAt":{"format":"date-time","type":"string","description":"Start crawled at.","nullable":true},"endCrawledAt":{"format":"date-time","type":"string","description":"End crawled at.","nullable":true},"crawlerType":{"type":"string","enum":["FIRECRAWL","APIFY"],"description":"Crawler type."},"crawlFormat":{"type":"string","enum":["JSON","MARKDOWN","HTML","CONTENT"],"description":"Crawl format."},"excludeUrls":{"description":"Excluded urls.","nullable":true,"type":"array","items":{"type":"string"}},"pageLimit":{"type":"number","description":"Page limit."},"maxDepth":{"type":"number","description":"Max depth."},"frequency":{"type":"string","enum":["manual","daily","weekly","monthly"],"description":"Scraping frequency."},"autoUpload":{"type":"boolean","description":"Is auto upload enabled."},"crawlingStatus":{"type":"string","enum":["not_started","in_progress","completed","failed","canceled"],"description":"Crawling status."}},"required":["url","startCrawledAt","endCrawledAt","crawlerType","crawlFormat","excludeUrls","pageLimit","maxDepth","frequency","autoUpload","crawlingStatus"]},"NotificationSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]}},"required":["systemName","status"]},"ExternalRetrieversSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"externalRetrievers":{"description":"External retrievers.","type":"array","items":{"$ref":"#/components/schemas/ExternalRetrieverResponseDTO"}}},"required":["systemName","status","externalRetrievers"]},"ExternalRetrieverResponseDTO":{"type":"object","properties":{"name":{"type":"string","description":"Retriever name."},"type":{"type":"string","enum":["pinecone"],"description":"Retriever type."},"status":{"type":"string","enum":["active","inactive"],"description":"Retriever status."},"config":{"description":"Retriever config.","allOf":[{"$ref":"#/components/schemas/ExternalRetrieverConfig"}]}},"required":["name","type","status","config"]},"ExternalRetrieverConfig":{"type":"object","properties":{"apiKey":{"type":"string","description":"External retriever API key."},"indexName":{"type":"string","description":"External retriever index name."},"host":{"type":"string","description":"External retriever host."},"fieldName":{"type":"string","description":"External retriever field name."},"namespace":{"type":"string","description":"External retriever namespace."},"topK":{"type":"number","description":"External retriever topK."},"isEmbedded":{"type":"boolean","description":"External retriever is embedded."},"dimensions":{"type":"number","description":"External retriever dimensions."},"model":{"type":"string","enum":["text-embedding-ada-002","text-embedding-3-large","text-embedding-3-small"],"description":"External retriever model."}},"required":["apiKey","indexName","host","fieldName","namespace","topK","isEmbedded"]},"WebSearchSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"webSearchServiceType":{"type":"string","enum":["openai"],"description":"Web search service."},"prompt":{"type":"string","description":"Web search prompt."}},"required":["systemName","status","webSearchServiceType","prompt"]},"FeedbackSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"period":{"type":"string","enum":["last_30_days","last_60_days","last_90_days","all_time"],"description":"Feedback period."},"autoUpload":{"type":"boolean","description":"Is auto upload enabled."},"generationMode":{"type":"string","enum":["manual","auto"],"description":"Feedback generation mode."}},"required":["systemName","status","period","autoUpload","generationMode"]},"EscalationSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"escalations":{"description":"Escalations.","type":"array","items":{"$ref":"#/components/schemas/EscalationResponseDTO"}}},"required":["systemName","status","escalations"]},"EscalationResponseDTO":{"type":"object","properties":{"topic":{"type":"string","description":"Escalation topic."},"escalationPrompt":{"type":"string","description":"Escalation prompt."},"autoChangeConversationMode":{"type":"boolean","description":"Is auto change conversation mode to manual enabled?"},"response":{"type":"string","description":"Message to the user in case of escalation."},"recipients":{"description":"Send notification to the recipients in case of escalation.","type":"array","items":{"$ref":"#/components/schemas/EscalationRecipientsResponseDTO"}}},"required":["topic","escalationPrompt","autoChangeConversationMode","response","recipients"]},"EscalationRecipientsResponseDTO":{"type":"object","properties":{"channel":{"type":"string","enum":["sms","email","webhook"],"description":"Notification channel."},"value":{"type":"string","description":"Notification recipient."},"headers":{"type":"object","description":"Optional headers to be sent with the webhook"}},"required":["channel","value"]},"CalendarSkillResponseDTO":{"type":"object","properties":{"systemName":{"type":"string","description":"System name of the skill.","enum":["LIVE_CHAT","SMS","EMAIL","WEBHOOK","FUNCTION","SCORING","API","VOICE","MEMORY","AGENT_REPORT","SCRAPING","NOTIFICATIONS","EXTERNAL_RETRIEVERS","WEB_SEARCH","FEEDBACK","ESCALATION","CALENDAR","AUDITOR","COPILOT","MCP","ENHANCED_PROMPTING"]},"status":{"type":"string","description":"Status of the email skill.","enum":["active","inactive"]},"config":{"oneOf":[{"$ref":"#/components/schemas/CalCalendarConfig"}],"discriminator":{"propertyName":"type","mapping":{"cal":"#/components/schemas/CalCalendarConfig"}},"allOf":[{"$ref":"#/components/schemas/CalCalendarConfig"}]}},"required":["systemName","status","config"]},"CalCalendarConfig":{"type":"object","properties":{"type":{"type":"string","enum":["cal"],"description":"Calendar type."},"apiKey":{"type":"string","description":"Cal calendar API key."},"prompt":{"type":"string","description":"Cal calendar prompt."}},"required":["type","apiKey","prompt"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"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"}}}},"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 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"}}}},"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"]}}}}
```

## Get all platform users for the current organization.

> Retrieves all platform users for the current 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":{"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"}},"required":["id","email","phoneNumber","firstName","lastName"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"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.","operationId":"ExternalApiPlatformUsersController_getAllOrganizationPlatformUsers","parameters":[{"name":"role","required":false,"in":"query","description":"Platform user organization role.","schema":{"type":"string","enum":["owner","admin","user","copilot_user","copilot_agent_user","copilot_admin"]}}],"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"}}}},"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"]}}}}
```


---

# Agent Instructions: Querying This Documentation

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

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

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

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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