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/{chat_id}/approvals: post: tags: - Chats summary: Resume a paused chat after tool approval description: >- Submit ask-first approval decisions for a paused chat and continue the agent run. ### Rate Limits 600 requests per minute. operationId: resumeChatApprovals parameters: - schema: type: string required: true in: path description: >- The ID of the chat that is currently paused waiting for tool approval. example: '123' name: chat_id requestBody: content: application/json: schema: $ref: '#/components/schemas/ResumeChatApprovalRequest' 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. Either a previous answer for this chat is still generating (error code generation_in_flight; retry after retry_after_seconds), or the assistant message is no longer awaiting tool approval (non-retryable). content: application/json: schema: anyOf: - $ref: '#/components/schemas/GenerationInFlightConflict' - $ref: '#/components/schemas/ChatConflict' '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: ResumeChatApprovalRequest: type: object properties: assistant_message_id: type: string description: The paused assistant message that is awaiting approval responses: type: array items: type: object properties: tool_call_id: type: string description: The tool call identifier to respond to approved: type: boolean description: Whether the tool call should be approved reason: type: string description: Optional reason shown to the assistant when rejected required: - tool_call_id - approved description: Approval decisions keyed by tool call id 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. required: - include_turn_trace required: - assistant_message_id - responses example: assistant_message_id: msg_5f6g responses: - tool_call_id: call_abc123 approved: true - tool_call_id: call_def456 approved: false reason: Not authorized to send external email. 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 ChatConflict: type: object properties: error: type: string description: Human-readable explanation of the conflict required: - error example: error: Assistant message is not awaiting tool approval 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 ````