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}: get: tags: - Documents summary: List documents for a connector description: >- Retrieve documents for a specific API Connector. This endpoint requires a Data Source ID. To get started: 1. Go to the API 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 ### Pagination The endpoint uses cursor-based pagination to handle large result sets efficiently. Here's how it works: 1. **First Request**: Make a request without a cursor to get the first page of results 2. **Subsequent Requests**: Use the `nextCursor` from the previous response to get the next page 3. **Cursor Format**: The cursor is a string containing digits only. 4. **End of Results**: When `nextCursor` is `undefined`, you've reached the end of the results Example pagination flow: 1. First request: `GET /documents/int_21XZai6JGvd1111J` → Returns first page with `nextCursor` 2. Next request: `GET /documents/int_21XZai6JGvd1111J?cursor=456` → Returns next page 3. Continue until `nextCursor` is `undefined` ### Field Selection By default, only document IDs are returned. Use the `fields` parameter to request additional fields: - Available fields: id, title, content, content_type, url, document_created_at, document_updated_at, meta - Example: `fields=id,title,content` ### Rate Limits 600 requests per minute. operationId: listDocuments 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: 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 - schema: type: string pattern: ^\d+$ description: >- Cursor for pagination. Required for fetching results beyond the first 100 documents. required: false description: >- Cursor for pagination. Required for fetching results beyond the first 100 documents. in: query example: '100' name: cursor - schema: type: number minimum: 1 maximum: 100 default: 20 description: >- Number of documents to return per page. Defaults to 20, maximum 100. required: false description: Number of documents to return per page. Defaults to 20, maximum 100. in: query example: 20 name: limit responses: '200': description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/DocumentsInput' - type: object properties: nextCursor: type: string example: documents: - id: doc_42 title: Getting started with Realm content: |- # Getting started Welcome to Realm. contentType: markdown url: https://docs.example.com/getting-started meta: category: guide readAccess: - alice@example.com verified: true '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: DocumentsInput: type: object properties: documents: type: array items: $ref: '#/components/schemas/Document' required: - documents example: documents: - id: doc_42 title: Getting started with Realm content: |- # Getting started Welcome to Realm. contentType: markdown url: https://docs.example.com/getting-started meta: category: guide readAccess: - alice@example.com verified: true 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 ````