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: /documents/{data_source_id}/{document_id}: get: tags: - Documents summary: Get a document description: >- Get a specific document by ID. This endpoint requires a Data Source ID. To get started: 1. Go to the Connectors page 2. Create a new API Connector 3. Copy the data source ID from the connector details page 4. Use this ID in the {data_source_id} path parameter ### Rate Limits 600 requests per minute. operationId: getDocument parameters: - schema: type: string description: ID of the custom API data source. required: true description: ID of the custom API data source. in: path example: ds_kb_main name: data_source_id - schema: type: string description: ID of the document. required: true description: ID of the document. in: path example: doc_42 name: document_id - schema: type: array items: type: string enum: - id - title - content - content_type - url - document_created_at - document_updated_at - meta description: >- Comma-separated list of fields to return. If not provided, only document IDs are returned. example: id,title,content required: false description: >- Comma-separated list of fields to return. If not provided, only document IDs are returned. in: query style: form explode: false name: fields responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Document' '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: Document: type: object properties: id: type: string pattern: ^[a-zA-Z0-9_-]+$ description: >- Optional unique identifier for the document. We enforce uniqueness in our end. If not provided, a UUID will be generated automatically and returned in the response. Must be alphanumeric and can include underscores and hyphens. The order of the documents in the response is the same as the order of the documents in the request, so you can match any generated IDs. title: type: string content: type: string contentType: type: string enum: - markdown - text - html url: type: string format: uri createdAt: type: string format: date-time description: UTC timestamp in ISO 8601 format (e.g. '2024-03-20T10:00:00Z') updatedAt: type: string format: date-time description: UTC timestamp in ISO 8601 format (e.g. '2024-03-20T10:00:00Z') meta: type: object additionalProperties: type: string readAccess: type: array items: type: string minItems: 1 description: >- Email addresses of the users that have read access to the document. If not provided, the document can be seen by anyone in Realm. Cannot be an empty array — omit the field instead. verified: type: boolean description: >- When true, marks this document as verified for this upsert. Send true on every upsert while the source system still treats it as authoritative; omitting it or sending false stops asserting source verification. required: - title - content - contentType example: id: doc_42 title: Getting started with Realm content: |- # Getting started Welcome to Realm. contentType: markdown url: https://docs.example.com/getting-started createdAt: '2024-03-20T10:00:00Z' updatedAt: '2024-03-20T10:00:00Z' meta: category: guide readAccess: - alice@example.com verified: true securitySchemes: bearerAuth: type: http scheme: bearer x-default: YOUR_API_TOKEN ````