Ingest Repository

Queue a repository for ingestion into the vector database.

Endpoint

POST /ingestions/repository

Request Body

Parameter	Type	Required	Description
repoUrl	string	✅	Git repository URL
ref	string	❌	Branch, tag, or commit (default: main)
token	string	❌	Access token for private repositories
userId	string	❌	User identifier for tracking
repoId	string	❌	Custom repository identifier (auto-deduced from URL if not provided)
meta	object	❌	Custom metadata for filtering

Example Request

curl -X POST http://localhost:3000/ingestions/repository \
  -H "Content-Type: application/json" \
  -d '{
    "repoUrl": "https://github.com/username/repo.git",
    "ref": "main",
    "token": "ghp_xxx",
    "userId": "user-123",
    "repoId": "my-repo",
    "meta": {
      "team": "backend",
      "project": "api",
      "environment": "production"
    }
  }'

Response

{
  "status": "queued",
  "jobId": "01HQZX3Y4Z5A6B7C8D9E0F1G2H",
  "repoUrl": "https://github.com/username/repo.git",
  "ref": "main",
  "repoId": "repo"
}

Response Fields

Field	Type	Description
status	string	Always "queued" on success
jobId	string	ULID job identifier for tracking
repoUrl	string	The repository URL
ref	string	The branch/tag/commit being ingested
repoId	string	Auto-deduced or provided repository ID

Auto-deduced repoId

If repoId is not provided, it's automatically extracted from the repository URL:

Repository URL	Auto-deduced repoId
https://github.com/org/my-repo.git	my-repo
https://github.com/user/backend-api.git	backend-api
https://gitlab.com/team/auth-service.git	auth-service

Metadata

The meta field allows you to attach custom key-value pairs to all chunks during ingestion:

{
  "repoUrl": "https://github.com/org/backend-api.git",
  "meta": {
    "team": "platform",
    "environment": "production",
    "version": "2.0"
  }
}

Metadata Rules

• Only flat key-value pairs allowed
• Values must be string, number, or boolean
• Metadata is attached to all chunks from this repository
• Use metadata during search to filter results

Private Repositories

For private repositories, provide an access token:

GitHub

{
  "repoUrl": "https://github.com/org/private-repo.git",
  "token": "ghp_xxxxxxxxxxxx"
}

GitLab

{
  "repoUrl": "https://gitlab.com/org/private-repo.git",
  "token": "glpat-xxxxxxxxxxxx"
}

Status Codes

Code	Description
201	Job queued successfully
400	Invalid repository URL or parameters
401	Invalid or missing token for private repo

What Happens Next

1. The job is added to the BullMQ queue
2. A worker picks up the job and begins processing
3. The repository is cloned, parsed, and indexed
4. Metadata is attached to all chunks
5. Use Get Job Status to monitor progress