Welcome to the Realm API documentation. With this API you can add, edit and delete documents from Realm, as well as integrate Realm into your applications.
Authorization: Bearer [your-api-token]
This API implements rate limiting using a token bucket algorithm to ensure fair usage and system stability. When rate limits are exceeded, the API will return a 429 Too Many Requests status code.
Each endpoint has its own rate limit configuration. If you exceed the rate limit, the request will be queued for up to 3 seconds before being rejected. We recommend implementing exponential backoff in your client applications when receiving 429 responses.
The API does not have a separate pricing for now; it is included in the Realm subscription. We might change this in the future, but will notice you well in advance if we do.
If you encounter any issues or have questions, please contact our team in Slack or via email: team@withrealm.com
servers: - url: https://app.withrealm.com/api/external/alpha description: Default multi-tenant environment. - url: https://{tenant}.withrealm.com/api/external/alpha description: Single-tenant deployment. variables: tenant: default: your-tenant description: Your organization's tenant subdomain. security: [] tags: - name: Chats description: Endpoints for chat and message management - name: Documents description: >- Endpoints for document management and operations. These endpoints can be used with custom connectors - they will not work with pre-built connectors. To use these endpoints, you'll need to create a custom connector from the Connectors page. - name: Connectors description: Endpoints for connector management and operations x-group: Data sources - name: Agents description: Endpoints for agent management and operations paths: /chats: post: tags: - Chats summary: Create or continue a chat description: >- Create a chat with a specific agent, or continue an existing chat. Any document that you have access to that is in the agent's knowledge base could be used to answer questions. ### Rate Limits 600 requests per minute. operationId: createChat requestBody: content: application/json: schema: $ref: '#/components/schemas/ChatRequest' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ChatResponse' '400': description: Bad request content: application/json: schema: type: object properties: error: type: string details: type: string required: - error '401': description: 'Unauthorized: missing or invalid API token' content: application/json: schema: type: object properties: error: type: string required: - error '403': description: >- Forbidden: the API token lacks the required scope, or external API access is not available on the organization's plan content: application/json: schema: type: object properties: error: type: string required: - error '409': description: >- Conflict: a previous answer for this chat is still generating (error code generation_in_flight). Retry after retry_after_seconds. content: application/json: schema: $ref: '#/components/schemas/GenerationInFlightConflict' '429': description: >- Too many requests: rate limit exceeded. Retry after the number of seconds in the Retry-After response header. content: application/json: schema: type: object properties: error: type: string required: - error '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string required: - error security: - bearerAuth: [] components: schemas: ChatRequest: type: object properties: assistant_id: type: - string - 'null' description: Deprecated. Use agent_id instead. agent_id: type: - string - 'null' description: >- The ID of the agent to use for the chat. You can find the ID by clicking on the agent in the [Agents](/agents) page. chat_id: type: string description: >- The ID of the chat to continue. If not provided, a new chat will be created. example: '123' content: type: string description: The content of the user message. research_mode: type: boolean description: >- Enable research mode for this chat. Only works if the agent has research mode enabled ('optional' or 'always_on'). data_analysis: type: boolean description: >- Control Data Analysis for this request. Omit to use the agent's configured default, set true to enable it when allowed, or set false to disable it for this request. document_refs: type: array items: $ref: '#/components/schemas/ExternalChatDocumentReference' maxItems: 20 description: >- Attach exact documents by Realm API data source ID and source document ID. citation_style: type: string enum: - link - remove default: remove description: >- The style of citations to use. 'remove' will not show any citations, 'link' will format them as URLs. output_format: type: string enum: - markdown - text default: markdown description: >- The format of the content returned. 'markdown' includes formatting, 'text' returns plain text. prompt_variables: type: object additionalProperties: type: string description: Prompt variables as input to the agent. answer_only: type: boolean default: false description: >- When enabled for non-streaming responses, return only the final answer text, excluding intermediate reasoning, thinking steps, and agent narration. Has no effect on streaming responses. eco_mode: type: boolean description: >- Experimental. Use cost-efficient models for this request. Omit to inherit the agent and organization defaults. Eco is available only for Auto and Smart agents. eval_options: type: object properties: include_turn_trace: type: boolean description: >- Return a normalized persisted trace for the current turn, including approval pauses. Requires internal evaluation access. model_override: type: string enum: - test - o1 - o3 - o1-mini - o3-mini - o4-mini - gpt-image-2 - azure-gpt-5.6-terra-credits - azure-gpt-5.6-luna-credits - azure-gpt-5.5-credits - azure-gpt-5.4-credits - azure-gpt-5.4-mini-credits - azure-gpt-5.1-credits - azure-finetuned-mini-1 - azure-finetuned-filtersearch-1 - azure-finetuned-filtersearch-2 - azure-finetuned-filtersearch-3 - vertex-finetuned-1 - vertex-finetuned-2 - azure-o1 - azure-o3 - azure-o1-mini - azure-o3-mini - azure-o4-mini - vertex-claude-3-7-sonnet@20250219 - vertex-claude-3-5-sonnet@20240620 - vertex-claude-3-5-sonnet-v2@20241022 - vertex-claude-3-haiku@20240307 - vertex-claude-3-opus@20240229 - vertex-claude-opus-4@20250514 - vertex-claude-sonnet-4@20250514 - vertex-claude-sonnet-4-5@20250929 - vertex-claude-opus-4-5@20251101 - vertex-claude-opus-4-6@default - vertex-claude-opus-4-7@global - vertex-claude-opus-4-7@eu - vertex-claude-sonnet-5@eu - vertex-claude-opus-4-8@global - vertex-claude-opus-4-8@eu - vertex-claude-sonnet-4-6 - vertex-claude-haiku-4-5@20251001 - bedrock-anthropic.claude-opus-4-5-20251101-v1:0 - bedrock-anthropic.claude-opus-4-6-v1 - bedrock-anthropic.claude-opus-4-7 - bedrock-anthropic.claude-opus-4-8 - bedrock-anthropic.claude-sonnet-4-6 - bedrock-anthropic.claude-sonnet-4-5-20250929-v1:0 - bedrock-us-anthropic.claude-sonnet-4-20250514-v1:0 - bedrock-eu-anthropic.claude-sonnet-4-20250514-v1:0 - bedrock-eu-anthropic.claude-3-7-sonnet-20250219-v1:0 - bedrock-eu-anthropic.claude-3-5-sonnet-20240620-v1:0 - bedrock-eu-anthropic.claude-3-5-haiku-20241022-v1:0 - bedrock-anthropic.claude-haiku-4-5-20251001-v1:0 - claude-sonnet-4-20250514 - claude-sonnet-4-6 - claude-sonnet-5 - claude-opus-4-6 - claude-opus-4-7 - claude-opus-4-8 - claude-haiku-4-5-20251001 - claude-sonnet-4-5-20250929 - claude-3-7-sonnet-latest - claude-3-7-sonnet-20250219 - claude-3-5-sonnet-20241022 - groq-mixtral - google-gemini-1.5-pro-001 - google-gemini-1.5-flash-001 - google-gemini-2.0-flash-001 - google-gemini-2.5-pro - google-gemini-2.5-flash - google-gemini-2.5-flash-lite - google-gemini-2.5-flash-image - google-gemini-3.1-flash-lite - google-gemini-3.1-flash-lite-eu - google-gemini-3.1-flash-image - google-gemini-3.5-flash-lite - google-gemini-3.5-flash-lite-eu - google-gemini-3.5-flash - google-gemini-3.5-flash-eu - google-gemini-3.6-flash - gemini-2.0-flash-001 - gemini-2.5-pro - gemini-2.5-flash - gemini-2.5-flash-lite - gemini-2.5-flash-image - gemini-3.1-flash-lite - gemini-3.1-flash-image - gemini-3.5-flash-lite - gemini-3.5-flash - gemini-3.6-flash - gemini-3-pro - gemini-3-flash - google-gemini-3-flash - google-gemini-3-pro - finetuned-mini - finetuned-mini-2 - finetuned-mini-3 - finetuned-filtersearch-1 - finetuned-gpt41mini-1 - finetuned-4o - qwen-7b - flow-judge - llama-3.2-3b - cerebras-llama-3.3-70b - nebius-kimi-k2.5 - nebius-gpt-oss-120b - nebius-gpt-oss-20b - nebius-qwen3-30b-thinking - nebius-nemotron-nano-30b - nebius-glm-4.5-air - nebius-minimax-m2.1 - azure-deepseek-v4-flash - tensorx-deepseek-v4-flash - tensorx-deepseek-v4-flash-0731 - gmicloud-deepseek-v4-flash - deepinfra-deepseek-v4-flash - deepinfra-deepseek-v4-flash-0731 - openrouter-deepseek-v4-flash - novita-deepseek-v4-flash - novita-deepseek-v4-pro - novita-mimo-v2.5 - digitalocean-mimo-v2.5 - deepinfra-mimo-v2.5 - novita-gemma-4-26b-a4b-it - novita-qwen3-coder-30b-a3b-instruct - novita-gpt-oss-120b - novita-gpt-oss-20b - novita-ling-2.6-flash - novita-minimax-m3 - deepinfra-minimax-m3 - novita-hy3 - deepinfra-hy3 - novita-step-3.7-flash - deepinfra-step-3.7-flash description: >- Force the primary agent and answer model for a controlled evaluation. Shared classifier and search helper models remain unchanged. Requires include_turn_trace. reasoning_effort: type: string enum: - low - medium - high - max description: >- Force a provider-neutral reasoning effort for primary model calls in a controlled evaluation. Max resolves to the strongest setting supported by each concrete model and provider. Requires include_turn_trace. required: - include_turn_trace tool_mode: type: string enum: - ask - act - 'off' description: >- Set action behavior for this request. Ask requires approval for every available action, act skips approval for available actions, and off disables all actions. tool_connector_ids: type: array items: type: string minLength: 1 maxItems: 100 description: >- Replace the agent's configured external tools with these connector or action identifiers for this request. tool_configs: type: object additionalProperties: type: object properties: status: type: string enum: - ask - enabled - disabled required: - status description: >- Override ask, enabled, or disabled status for individual available actions. Overrides take precedence over ask or act mode; off always disables actions. required: - content example: agent_id: agt_1a2b3c content: Summarize our Q3 sales performance. chat_id: cht_9x8y7z tool_mode: ask data_analysis: true document_refs: - data_source_id: ds_kb_main source_id: doc_42 citation_style: link output_format: markdown ChatResponse: anyOf: - $ref: '#/components/schemas/FinalizedChatResponse' - $ref: '#/components/schemas/ApprovalRequiredChatResponse' GenerationInFlightConflict: type: object properties: error: type: string enum: - generation_in_flight description: Machine-readable error code for the conflict message: type: string description: Human-readable explanation of the conflict retry_after_seconds: type: number description: How long the in-flight answer may still run before retry required: - error - message - retry_after_seconds example: error: generation_in_flight message: >- Another answer is already being generated in this chat. Retry after 8 seconds, or start a new chat. retry_after_seconds: 8 ExternalChatDocumentReference: type: object properties: data_source_id: type: string minLength: 1 description: The Realm API data source ID that owns the document. source_id: type: string minLength: 1 description: The source document ID supplied when the document was added. required: - data_source_id - source_id FinalizedChatResponse: type: object properties: id: type: string description: Unique identifier for the chat assistant_id: type: string description: Deprecated. Use agent_id instead. agent_id: type: string description: The ID of the agent that processed the request created: type: number description: Unix timestamp in milliseconds of when the completion was created created_date: type: string description: ISO 8601 formatted timestamp of when the completion was created content: type: string description: The content of the chat research_mode: type: boolean description: >- If research mode was used for this chat. The agent configuration can override the user requested value. output_format: type: string enum: - markdown - text description: The format of the content returned status: type: string enum: - completed - queued description: Whether the chat completed immediately or was queued eval_trace: allOf: - $ref: '#/components/schemas/EvalTurnTraceV1' - description: >- Normalized persisted turn trace returned only for authorized eval requests required: - id - assistant_id - agent_id - created - created_date - content - research_mode - output_format - status example: id: cht_9x8y7z assistant_id: agt_1a2b3c agent_id: agt_1a2b3c created: 1730210400000 created_date: '2024-10-29T14:00:00.000Z' content: Your Q3 revenue grew 12% quarter over quarter. research_mode: false output_format: markdown status: completed ApprovalRequiredChatResponse: type: object properties: id: type: string description: Unique identifier for the chat assistant_id: type: string description: Deprecated. Use agent_id instead. agent_id: type: string description: The ID of the agent that processed the request created: type: number description: Unix timestamp in milliseconds of when the completion was created created_date: type: string description: ISO 8601 formatted timestamp of when the completion was created content: type: string description: The content of the chat research_mode: type: boolean description: >- If research mode was used for this chat. The agent configuration can override the user requested value. output_format: type: string enum: - markdown - text description: The format of the content returned status: type: string enum: - approval_required description: The chat is paused waiting for ask-first tool approval assistant_message_id: type: string description: The assistant message that contains the pending approvals approvals: type: array items: type: object properties: type: type: string enum: - dynamic-tool toolName: type: string toolCallId: type: string title: type: string providerExecuted: type: boolean state: type: string enum: - input-streaming - input-available - approval-requested - approval-responded - output-streaming - output-available - output-error - output-denied input: {} output: {} partialInput: type: string partialOutput: type: string errorText: type: string reconnect: type: object properties: reason: type: string enum: - auth - forbidden toolId: type: string connectorName: type: - string - 'null' ownerUserId: type: string required: - reason - toolId - connectorName - ownerUserId readableReference: type: object properties: reference: type: string title: type: string content: type: string toolName: type: string toolCallId: type: string required: - reference - title - content - toolName - toolCallId caller: type: - object - 'null' properties: type: type: string toolId: type: string tool_id: type: string providerOptions: type: object additionalProperties: type: object additionalProperties: {} providerMetadata: type: object additionalProperties: type: object additionalProperties: {} approval: type: object properties: id: type: string approved: type: boolean reason: type: string required: - id toolMetadata: type: object properties: logo: type: string serverDisplayName: type: string displayName: type: string description: type: string serverType: type: string enum: - internal - external inputSchema: {} required: - logo - serverDisplayName - displayName - description - serverType required: - type - toolName - toolCallId - state description: The tool approval requests that must be approved or rejected resume_supported: type: boolean enum: - true description: Whether this paused chat can be resumed via the API eval_trace: allOf: - $ref: '#/components/schemas/EvalTurnTraceV1' - description: >- Normalized persisted partial turn trace returned only for authorized eval requests required: - id - assistant_id - agent_id - created - created_date - content - research_mode - output_format - status - assistant_message_id - approvals - resume_supported example: id: cht_9x8y7z assistant_id: agt_1a2b3c agent_id: agt_1a2b3c created: 1730210400000 created_date: '2024-10-29T14:00:00.000Z' content: '' research_mode: false output_format: markdown status: approval_required assistant_message_id: msg_5f6g approvals: [] resume_supported: true EvalTurnTraceV1: type: object properties: version: type: number enum: - 1 status: type: string enum: - completed - approval_required - failed - aborted chat_id: type: string user_message_id: type: string assistant_message_id: type: string langfuse_trace_id: type: - string - 'null' model_override: type: - string - 'null' enum: - test - o1 - o3 - o1-mini - o3-mini - o4-mini - gpt-image-2 - azure-gpt-5.6-terra-credits - azure-gpt-5.6-luna-credits - azure-gpt-5.5-credits - azure-gpt-5.4-credits - azure-gpt-5.4-mini-credits - azure-gpt-5.1-credits - azure-finetuned-mini-1 - azure-finetuned-filtersearch-1 - azure-finetuned-filtersearch-2 - azure-finetuned-filtersearch-3 - vertex-finetuned-1 - vertex-finetuned-2 - azure-o1 - azure-o3 - azure-o1-mini - azure-o3-mini - azure-o4-mini - vertex-claude-3-7-sonnet@20250219 - vertex-claude-3-5-sonnet@20240620 - vertex-claude-3-5-sonnet-v2@20241022 - vertex-claude-3-haiku@20240307 - vertex-claude-3-opus@20240229 - vertex-claude-opus-4@20250514 - vertex-claude-sonnet-4@20250514 - vertex-claude-sonnet-4-5@20250929 - vertex-claude-opus-4-5@20251101 - vertex-claude-opus-4-6@default - vertex-claude-opus-4-7@global - vertex-claude-opus-4-7@eu - vertex-claude-sonnet-5@eu - vertex-claude-opus-4-8@global - vertex-claude-opus-4-8@eu - vertex-claude-sonnet-4-6 - vertex-claude-haiku-4-5@20251001 - bedrock-anthropic.claude-opus-4-5-20251101-v1:0 - bedrock-anthropic.claude-opus-4-6-v1 - bedrock-anthropic.claude-opus-4-7 - bedrock-anthropic.claude-opus-4-8 - bedrock-anthropic.claude-sonnet-4-6 - bedrock-anthropic.claude-sonnet-4-5-20250929-v1:0 - bedrock-us-anthropic.claude-sonnet-4-20250514-v1:0 - bedrock-eu-anthropic.claude-sonnet-4-20250514-v1:0 - bedrock-eu-anthropic.claude-3-7-sonnet-20250219-v1:0 - bedrock-eu-anthropic.claude-3-5-sonnet-20240620-v1:0 - bedrock-eu-anthropic.claude-3-5-haiku-20241022-v1:0 - bedrock-anthropic.claude-haiku-4-5-20251001-v1:0 - claude-sonnet-4-20250514 - claude-sonnet-4-6 - claude-sonnet-5 - claude-opus-4-6 - claude-opus-4-7 - claude-opus-4-8 - claude-haiku-4-5-20251001 - claude-sonnet-4-5-20250929 - claude-3-7-sonnet-latest - claude-3-7-sonnet-20250219 - claude-3-5-sonnet-20241022 - groq-mixtral - google-gemini-1.5-pro-001 - google-gemini-1.5-flash-001 - google-gemini-2.0-flash-001 - google-gemini-2.5-pro - google-gemini-2.5-flash - google-gemini-2.5-flash-lite - google-gemini-2.5-flash-image - google-gemini-3.1-flash-lite - google-gemini-3.1-flash-lite-eu - google-gemini-3.1-flash-image - google-gemini-3.5-flash-lite - google-gemini-3.5-flash-lite-eu - google-gemini-3.5-flash - google-gemini-3.5-flash-eu - google-gemini-3.6-flash - gemini-2.0-flash-001 - gemini-2.5-pro - gemini-2.5-flash - gemini-2.5-flash-lite - gemini-2.5-flash-image - gemini-3.1-flash-lite - gemini-3.1-flash-image - gemini-3.5-flash-lite - gemini-3.5-flash - gemini-3.6-flash - gemini-3-pro - gemini-3-flash - google-gemini-3-flash - google-gemini-3-pro - finetuned-mini - finetuned-mini-2 - finetuned-mini-3 - finetuned-filtersearch-1 - finetuned-gpt41mini-1 - finetuned-4o - qwen-7b - flow-judge - llama-3.2-3b - cerebras-llama-3.3-70b - nebius-kimi-k2.5 - nebius-gpt-oss-120b - nebius-gpt-oss-20b - nebius-qwen3-30b-thinking - nebius-nemotron-nano-30b - nebius-glm-4.5-air - nebius-minimax-m2.1 - azure-deepseek-v4-flash - tensorx-deepseek-v4-flash - tensorx-deepseek-v4-flash-0731 - gmicloud-deepseek-v4-flash - deepinfra-deepseek-v4-flash - deepinfra-deepseek-v4-flash-0731 - openrouter-deepseek-v4-flash - novita-deepseek-v4-flash - novita-deepseek-v4-pro - novita-mimo-v2.5 - digitalocean-mimo-v2.5 - deepinfra-mimo-v2.5 - novita-gemma-4-26b-a4b-it - novita-qwen3-coder-30b-a3b-instruct - novita-gpt-oss-120b - novita-gpt-oss-20b - novita-ling-2.6-flash - novita-minimax-m3 - deepinfra-minimax-m3 - novita-hy3 - deepinfra-hy3 - novita-step-3.7-flash - deepinfra-step-3.7-flash reasoning_effort: type: - string - 'null' enum: - low - medium - high - max served_models: type: - array - 'null' items: type: string description: >- Models that completed calls during the turn, in call order. Null means model telemetry was unavailable. started_at: type: string completed_at: type: - string - 'null' final_response: type: - string - 'null' tool_calls: type: array items: $ref: '#/components/schemas/EvalToolCallV1' output_files: type: array items: $ref: '#/components/schemas/EvalOutputFileV1' output_file_references: type: array items: $ref: '#/components/schemas/EvalOutputFileReferenceV1' usage: type: object properties: model_calls: type: - integer - 'null' minimum: 0 agent_steps: type: - integer - 'null' minimum: 0 input_tokens: type: - integer - 'null' minimum: 0 output_tokens: type: - integer - 'null' minimum: 0 total_tokens: type: - integer - 'null' minimum: 0 cache_read_input_tokens: type: - integer - 'null' minimum: 0 cache_write_input_tokens: type: - integer - 'null' minimum: 0 provider_cost_usd: type: - number - 'null' minimum: 0 required: - model_calls - agent_steps - input_tokens - output_tokens - total_tokens - cache_read_input_tokens - cache_write_input_tokens - provider_cost_usd context: type: object properties: initial_context_tokens: type: - integer - 'null' minimum: 0 maximum_context_tokens: type: - integer - 'null' minimum: 0 final_context_tokens: type: - integer - 'null' minimum: 0 recap_count: type: - integer - 'null' minimum: 0 truncation_count: type: - integer - 'null' minimum: 0 required: - initial_context_tokens - maximum_context_tokens - final_context_tokens - recap_count - truncation_count required: - version - status - chat_id - user_message_id - assistant_message_id - langfuse_trace_id - model_override - reasoning_effort - served_models - started_at - completed_at - final_response - tool_calls - output_files - output_file_references - usage - context EvalToolCallV1: type: object properties: sequence: type: integer minimum: 0 tool_call_id: type: string parent_tool_call_id: type: - string - 'null' source: type: string enum: - realm - provider raw_tool_name: type: string connector: type: - string - 'null' action: type: string requested_input: {} requested_input_truncated: type: boolean status: type: string enum: - proposed - approval_required - denied - succeeded - failed approval: type: - object - 'null' properties: status: type: string enum: - requested - approved - denied reason: type: - string - 'null' required: - status - reason output: {} output_truncated: type: boolean error: type: - string - 'null' required: - sequence - tool_call_id - parent_tool_call_id - source - raw_tool_name - connector - action - requested_input - requested_input_truncated - status - approval - output - output_truncated - error EvalOutputFileV1: type: object properties: file_path: type: string file_name: type: string mime_type: type: - string - 'null' download_url: type: string required: - file_path - file_name - mime_type - download_url EvalOutputFileReferenceV1: type: object properties: reference: type: string file_path: type: string file_name: type: string required: - reference - file_path - file_name securitySchemes: bearerAuth: type: http scheme: bearer x-default: YOUR_API_TOKEN ````