Skip to main content
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 Connector.

​
Setting up an API connector

1

Create the data source

On the Data sources page, click Add next to API Connector 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/{connector_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/{connector_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/{connector_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/{connector_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