Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.withrealm.com/llms.txt

Use this file to discover all available pages before exploring further.

Push documents from any system into Realm using the REST API. This is useful for syncing data from internal tools, custom databases, or any source without a native data source. Navigate to Settings > Data sources and click Add next to API data source.

​
Setting up an API data source

1

Create the data source

On the Data sources page, click Add next to API data source and give it a name. After creating it, you can upload a custom icon on the data source page. The name and icon appear in search results so users can identify where the content came from.
2

Create an API key

Go to Settings > API Keys and click Create New Key. Enable the Write documents to Realm permission. Copy the key immediately, as it won’t be shown again. See API Keys for full details.
3

Push documents

Use the REST API to push documents to your data source. See the Upsert Documents API reference and the examples below.

​
Pushing documents

Send a POST request to add or update documents. To update a document, send another request with the same id. 
curl -X POST https://app.withrealm.com/api/external/alpha/documents/{data_source_id} \
  -H "Authorization: Bearer realm_api_..." \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "id": "doc-123",
        "title": "Quarterly Review",
        "content": "# Q4 Results\n\nRevenue grew 15%.",
        "contentType": "markdown"
      }
    ]
  }'
See the API Reference for the full document schema, including optional fields like url, meta, createdAt, and readAccess.

​
Uploading files

For binary files (PDFs, Word documents, etc.), use the two-step upload flow: 
# Step 1: Get an upload URL
curl -X POST https://app.withrealm.com/api/external/alpha/documents/{data_source_id}/upload \
  -H "Authorization: Bearer realm_api_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Product Spec", "fileName": "spec.pdf", "contentType": "application/pdf"}'

# Step 2: Upload the file to the returned URL
curl -X PUT "{upload_url}" \
  -H "Content-Type: application/pdf" \
  --data-binary @spec.pdf
Realm automatically extracts text from uploaded files. See the API Reference for details.

​
Listing documents

Retrieve documents from your data source with cursor-based pagination: 
curl https://app.withrealm.com/api/external/alpha/documents/{data_source_id}?limit=20 \
  -H "Authorization: Bearer realm_api_..."
Use the nextCursor from the response to fetch the next page. See the API Reference for all query parameters.

​
Deleting documents

Delete all documents older than a given timestamp: 
curl -X DELETE "https://app.withrealm.com/api/external/alpha/documents/{data_source_id}?older_than=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer realm_api_..."
You can also delete individual documents by ID. See the API Reference for all options.

​
Access control

By default, documents are visible to all users in your organization. To restrict access, include a readAccess array with the email addresses of users who should see the document: 
{
  "documents": [{
    "title": "Confidential Report",
    "content": "...",
    "contentType": "text",
    "readAccess": ["alice@company.com", "bob@company.com"]
  }]
}

​
Sync behavior

Unlike native data sources, API data sources do not sync automatically. You are responsible for keeping documents up to date. Common approaches:
  • Cron job that periodically exports data and pushes it to Realm
  • Webhook handler that pushes documents when they change in your source system
  • CI/CD pipeline that pushes documentation after each deploy