Index API
One-call endpoint to register and sync any source into a RetainDB project.
Applies to: Context API v1
POST /v1/index is the fastest path from a source to searchable content. Pass a project and an array of sources; RetainDB creates the source records and starts indexing.
When to use it
Use /v1/index when you want to register and sync sources in a single call without first creating a project or source separately through the dashboard. It is the recommended starting point for programmatic ingestion.
Request
{
"project": "my-project",
"sources": [
{
"type": "github",
"owner": "acme",
"repo": "backend",
"branch": "main"
}
],
"auto_index": true
}Top-level fields
| Field | Type | Required | Description |
|---|---|---|---|
project | string | No | Project name or ID. Falls back to RETAINDB_PROJECT env var. |
sources | array | Yes | 1–25 source objects to register and sync. |
auto_index | boolean | No | Start sync immediately after creation. Default: true. |
return_bundle | boolean | No | Include an index bundle in the response. Default: false. |
Source fields
| Field | Type | Description |
|---|---|---|
type | string | Connector type (see below). |
name | string | Human-readable name for the source. |
owner | string | GitHub/GitLab org or user. |
repo | string | Repository name. |
branch | string | Branch to index. Default: main. |
url | string | URL for url, web, or sitemap sources. |
paths | string[] | File paths to include (GitHub/GitLab). |
channel_ids | string[] | Channel IDs for slack or discord. |
token | string | Auth token for private sources. |
auth_ref | string | Reference to a stored OAuth credential. |
sync_schedule | string | Cron expression for automatic re-sync. |
auto_index | boolean | Override top-level auto_index for this source only. |
metadata | object | Custom metadata attached to the source. |
options | object | Connector-specific options. |
Supported source types
github, gitlab, github-tarball, url, sitemap, web, playwright, pdf, text, api_spec, dataset, database, confluence, notion, slack, discord, arxiv, huggingface, npm_package, pypi_package, video, custom, local
Response
{
"project": "proj_abc123",
"results": [
{
"type": "github",
"success": true,
"mode": "source",
"project": "proj_abc123",
"source_id": "src_xyz789",
"status": "queued",
"job_id": "job_def456",
"index_started": true
}
]
}Examples
Index a GitHub repository
curl -X POST "https://api.retaindb.com/v1/index" \
-H "Authorization: Bearer $RETAINDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project": "my-project",
"sources": [
{
"type": "github",
"owner": "acme",
"repo": "docs",
"branch": "main"
}
]
}'Index multiple sources at once
curl -X POST "https://api.retaindb.com/v1/index" \
-H "Authorization: Bearer $RETAINDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project": "my-project",
"sources": [
{ "type": "github", "owner": "acme", "repo": "backend" },
{ "type": "url", "url": "https://docs.acme.com", "name": "Acme Docs" },
{ "type": "notion", "auth_ref": "notion-oauth" }
]
}'Index without auto-sync
Pass auto_index: false to create the source without starting a sync job immediately.
{
"project": "my-project",
"sources": [{ "type": "github", "owner": "acme", "repo": "backend" }],
"auto_index": false
}SDK equivalent
import { RetainDBClient } from "@retaindb/sdk";
const client = RetainDBClient.fromEnv();
// The SDK wraps /v1/index via the ingest helper
await client.ingest({
project: "my-project",
sources: [
{ type: "github", owner: "acme", repo: "backend" }
],
});Next step
- Projects and Sources — Manage sources directly
- Memory Search — Query after indexing
- Connectors — Per-connector configuration reference
Was this page helpful?
Your feedback helps us prioritize docs improvements weekly.