Skip to main content
Ingestion is the process of cloning a GitHub repository, parsing its source files with Tree-sitter, and writing the resulting functions, classes, variables, imports, and file nodes into the Neo4j knowledge graph. BugViper processes multiple languages including Python, TypeScript, JavaScript, Go, Rust, Java, and C++. Ingestion runs asynchronously. Both endpoints below return immediately; use the job status endpoint to poll for progress.

​
POST /api/v1/ingest/github

Queues a full ingestion of a GitHub repository. If an active ingestion job for the same repository is already running, BugViper returns the existing job rather than starting a duplicate. Jobs in pending or dispatched state that are older than 10 minutes are considered stale, marked failed, and a new job is started.
​
owner
string
required
GitHub organization name or username (e.g. acme-corp).
​
repo_name
string
required
Repository name as it appears on GitHub (e.g. my-api).
​
branch
string
Branch to ingest. Defaults to the repository’s default branch (usually main).
​
clear_existing
boolean
default:"false"
When true, all existing graph nodes for this repository are deleted before ingestion begins. Use this to fully re-index a repository from scratch.
Setting clear_existing: true permanently deletes all existing graph data for the repository — including any embeddings — before the new ingestion run starts. If ingestion fails partway through, the repository will have no data in the graph until the job completes successfully. Do not use this option on repositories that are actively being queried.

​
Response

​
job_id
string
UUID that uniquely identifies this ingestion job. Use this value to poll /api/v1/ingest/jobs/{job_id} for status updates.
​
status
string
Initial job status. Always "pending" when a new job is created.
​
message
string
Human-readable description of what was queued, e.g. "Ingestion started for acme-corp/my-api".
​
poll_url
string
API path to poll for job progress, e.g. "/api/v1/ingest/jobs/a1b2c3d4-...".

​
Example

curl -X POST https://your-bugviper-instance/api/v1/ingest/github \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "acme-corp",
    "repo_name": "my-api",
    "branch": "main",
    "clear_existing": false
  }'

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "message": "Ingestion started for acme-corp/my-api",
  "poll_url": "/api/v1/ingest/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Ingestion runs asynchronously. Poll the poll_url returned in the response to track progress. A typical repository takes anywhere from a few seconds to several minutes depending on size.

​
POST /api/v1/ingest///embed

Generates semantic embeddings for code nodes in an already-ingested repository. BugViper uses the OpenRouter embeddings API to produce vectors for each function, class, and variable node. These embeddings power the semantic search endpoint. This endpoint is safe to call multiple times — nodes that already have embeddings are skipped. Use it to recover from a failed embedding step after a successful ingestion, or to generate embeddings on a repository that was ingested without OPENROUTER_API_KEY set.
​
owner
string
required
GitHub organization name or username.
​
repo_name
string
required
Repository name.
​
Authorization
string
required
Firebase ID token. Format: Bearer <token>.

​
Response

​
repo_id
string
Repository identifier in owner/repo_name format.
​
nodes_embedded
number
Total number of nodes that received embeddings in this call. 0 means all nodes already had embeddings.
​
breakdown
object
Count of newly embedded nodes grouped by label (e.g. {"Function": 312, "Class": 47}). Labels with a count of zero are omitted.
​
message
string
Human-readable summary, e.g. "Embedded 359 nodes successfully" or "All nodes already had embeddings".

​
Example

curl -X POST https://your-bugviper-instance/api/v1/ingest/acme-corp/my-api/embed \
  -H "Authorization: Bearer YOUR_FIREBASE_ID_TOKEN"

{
  "repo_id": "acme-corp/my-api",
  "nodes_embedded": 359,
  "breakdown": {
    "Function": 312,
    "Class": 47
  },
  "message": "Embedded 359 nodes successfully"
}
Embedding requires the OPENROUTER_API_KEY environment variable to be set on the BugViper server. The endpoint returns 400 Bad Request if the key is missing.