> ## 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.

# API data source

> Push documents to Realm from any system using the REST API

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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](/admin/api) for full details.
  </Step>

  <Step title="Push documents">
    Use the REST API to push documents to your data source. See the [Upsert Documents](/api-reference/documents/upsert-documents) API reference and the examples below.
  </Step>
</Steps>

## Pushing documents

Send a POST request to add or update documents. To update a document, send another request with the same `id`.

```bash theme={null}
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](/api-reference/documents) 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:

```json theme={null}
{
  "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:

```bash theme={null}
# 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](/api-reference/documents) for details.

## Listing documents

Retrieve documents from your data source with cursor-based pagination:

```bash theme={null}
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](/api-reference/documents) for all query parameters.

## Deleting documents

Delete all documents older than a given timestamp:

```bash theme={null}
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](/api-reference/documents) 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:

```json theme={null}
{
  "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