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: get: tags: - Chats summary: List chats description: |- List chats ### Rate Limits 600 requests per minute. operationId: listChats parameters: - schema: type: string pattern: ^\d+$ required: false in: query description: >- Cursor for pagination. Use this to fetch chats after a specific chat ID. example: '123' name: after_id - schema: type: integer minimum: 1 maximum: 100 required: false in: query description: Maximum number of chats to return. Defaults to 20 if not specified. example: 50 name: limit - schema: type: string enum: - asc - desc required: false in: query description: >- Sort order for the chats. 'asc' for oldest first, 'desc' for newest first. Defaults to 'desc'. example: desc name: order responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ListChatsResponse' '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 '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: ListChatsResponse: type: object properties: object: type: string enum: - list data: type: array items: 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 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 required: - object - data example: object: list data: - id: cht_9x8y7z assistant_id: agt_1a2b3c agent_id: agt_1a2b3c created: 1730212800000 created_date: '2024-10-29T14:00:00.000Z' content: Your Q3 revenue grew 12% quarter over quarter. 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 - gpt-5.6-luna - 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 ````