API data source

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

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.

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.

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, readAccess, and verified. Set verified to true on each upsert or upload while the source system currently treats the document as authoritative. If a later request for the same document omits verified or sends false, Realm stops asserting that source-managed verification:

{
  "documents": [
    {
      "title": "Official Security Policy",
      "content": "...",
      "contentType": "markdown",
      "verified": true
    }
  ]
}

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

Overview

Admin

Organization settings

Integrations

Security

List of data sources

Setting up an API data source

Pushing documents

Uploading files

Listing documents

Deleting documents

Access control

Sync behavior

​Setting up an API data source

​Pushing documents

​Uploading files

​Listing documents

​Deleting documents

​Access control

​Sync behavior

Setting up an API data source

Pushing documents

Uploading files

Listing documents

Deleting documents

Access control

Sync behavior