APIUpdated 2026-05-30

Sources API

Create, list, update, sync, and delete sources feeding the company brain.

Applies to: RetainDB API v1

Sources are the inputs that feed the company brain.

Use the Sources API when a backend, job, CLI, or agent needs to add or update sources without the dashboard.

Routes

Goal	Route
List sources	`GET /v1/sources?project=production`
Create a source	`POST /v1/sources`
Update a source	`PATCH /v1/sources/:id`
Trigger sync	`POST /v1/sources/:id/sync`
Delete a source	`DELETE /v1/sources/:id?project=production`

All routes require:

http

Authorization: Bearer $RETAINDB_API_KEY

List Sources

bash

curl "https://api.retaindb.com/v1/sources?project=production" \
  -H "Authorization: Bearer $RETAINDB_API_KEY"

Use this before agent runs to confirm important sources are ready.

Create A Manual Text Source

bash

curl -X POST "https://api.retaindb.com/v1/sources" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "production",
    "type": "text",
    "name": "Billing Runbook",
    "config": {
      "content": "Billing retries happen automatically for 3 days before escalation."
    }
  }'

Create A URL Source

bash

curl -X POST "https://api.retaindb.com/v1/sources" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "production",
    "type": "url",
    "name": "Checkout Docs",
    "config": {
      "url": "https://docs.example.com/checkout"
    }
  }'

Trigger Sync

bash

curl -X POST "https://api.retaindb.com/v1/sources/src_123/sync" \
  -H "Authorization: Bearer $RETAINDB_API_KEY"

Syncs are background jobs. Poll GET /v1/sources?project=... or use the dashboard to watch status.

Update Source Config

bash

curl -X PATCH "https://api.retaindb.com/v1/sources/src_123" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "production",
    "name": "Checkout Docs",
    "configPatch": {
      "url": "https://docs.example.com/checkout/v2"
    },
    "sync": true
  }'

Delete A Source

bash

curl -X DELETE "https://api.retaindb.com/v1/sources/src_123?project=production" \
  -H "Authorization: Bearer $RETAINDB_API_KEY"

Deleting a source should remove it from query results and deactivate source-derived documents, chunks, and memories.

Status Lifecycle

Status	Agent behavior
`pending`	do not rely on it yet
`connecting`	wait for auth/config validation
`syncing` / `indexing`	wait or show partial indexing state
`indexed` / `ready`	safe for agent queries
`failed`	show the error and retry after fixing config
`paused`	excluded until resumed

Connector Availability

Manual sources such as text, url, web, and extracted pdf content are the safest automation path.

Account-backed tools such as GitHub, Slack, Notion, Google Drive, Confluence, Jira, Linear, Dropbox, and Box require a connected account or OAuth flow. Do not create them as working sources unless the account connection exists and the dashboard shows the connector as enabled.

SDK

const client = RetainDBClient.fromEnv();

await client.sources.create("production", {
  name: "Billing Runbook",
  connector_type: "text",
  config: {
    content: "Billing retries happen automatically for 3 days."
  }
});

const sources = await client.sources.list("production");

Next: Company Brain API, Dashboard Sources, or Connect Agents.

Was this page useful?

Your feedback helps us make the product easier to ship with.