AutoGraph Service Reference

This section documents the AutoGraph HTTP REST API. All endpoints require JWT authentication and are served on port 8080. For the pipeline architecture, see Architecture.

Authentication

All endpoints require a JWT in the Authorization header:

Authorization: Bearer <jwt_token>

The service handles token renewal automatically, including for long-running background jobs (corpus build, RAG strategizer, orchestration).

Endpoints

Endpoints are served at http://<host>:8080.

Pipeline

Document-level changes

Project operations

Standalone

For HTTP error codes and troubleshooting, see Error Handling.

The category contract

A category is the second scope level of a project and carries the label you set as module when you imported the files, see Import files.

Every endpoint that takes a category expects the bare label, such as legal, exactly as GET /v1/projects/{project}/overview reports it in categories[].name. The internal {project}_legal encoding is a server-side detail that you never have to construct. An already encoded value is still accepted as a legacy alias, but the bare form is the one to use.

POST /v1/corpus/builds, POST /v1/rag-strategizer/analyze, and POST /v1/orchestrate take a list of them in categories, the /v1/graph/* endpoints take a single one in category, and DELETE /v1/projects/{project}/categories/{category} takes one in the path.

Call Sequence

All calls require a valid Authorization: Bearer <token> header.

Standard workflow

1. GET /v1/health - confirm the service is ready.
2. Upload the documents to the File Manager under the scope [project, category]. The direct upload with POST /v1/import-multiple is deprecated. See Import Files.
3. POST /v1/corpus/builds - start the corpus build, preferably with categories. Returns 202 with a corpus_build_id and the graph_name. See Corpus Build.
4. Poll GET /v1/corpus/builds/{corpus_build_id} until status is completed. Check error_code even then, because a non-empty value on a completed build means a partial success. See Monitoring Build Status.
5. POST /v1/rag-strategizer/analyze - assign RAG strategies to clusters. project and complexity are required. Returns 202 with a strategize_job_id. See RAG Strategizer.
6. Poll GET /v1/rag-strategizer/jobs/{strategize_job_id} until status is completed. See Monitor a strategizer job.
7. (Optional) GET /v1/rag-strategizer/strategy - inspect the assigned strategies. See Retrieve RAG Strategies.
8. (Optional) PATCH /v1/rag-strategizer/strategy/{cluster_id} - override the strategy of a cluster if the assigned one is not suitable. Do this before you orchestrate. See Update a cluster strategy.
9. POST /v1/orchestrate - spawn Importer workers to build the knowledge graph. Returns 202 with an orchestration_id. See Trigger Orchestration.
10. Poll GET /v1/orchestrate/{orchestration_id}. Branch on status, which reaches completed only once every job is terminal and the imported partitions were found in the knowledge graph, and render phase as the progress. The response also carries the per-partition results, including the divergence of each FullGraphRAG partition. Read them before you start another orchestration, which evicts this run. See Monitor an orchestration.

At any point, GET /v1/projects/{project}/overview reports where the project stands: the document and cluster counts, whether the corpus, the strategies, or the knowledge graph are stale, and which categories still need work.

Embed-only workflow

Use this path when you already have documents in ArangoDB and only need vector embeddings and a search index on one attribute. No import or corpus build is required.

1. GET /v1/health
2. POST /v1/embed-field-in-collection - add vector embeddings to an existing ArangoDB collection. Repeat per (collection, field) pair. See Embeddings.

Adding a category to an existing corpus

Follow the standard workflow, but in step 3 list only the new category in categories and leave incremental at its default of false. The existing categories are left untouched.

Use incremental: true only to append documents to a category that already exists. A full rebuild of an already built category is rejected with REBUILD_NOT_ALLOWED, see Corpus Build.

Rebuilding a category

There is no in-place rebuild. To rebuild a category from scratch, remove it with DELETE /v1/projects/{project}/categories/{category}, then run a corpus build, the strategizer, and an orchestration again. This is also the supported recovery path for a partition that imported incompletely.

Document-level changes to an existing graph

Use these calls if the corpus graph is already built and you only want to change individual documents. See Incremental Graph Updates for the prerequisites, a comparison with a rebuild, and the full endpoint reference.

1. Call POST /v1/graph/insert, /v1/graph/delete, or /v1/graph/update, depending on what changed. Insert and update only cover Layers 1 and 2. Delete is synchronous and removes the Layer 3 data itself.
2. After an insert or a successful update, call POST /v1/orchestrate with the file_ids of the changed documents, so that Layer 3 contains the new content. A non-empty file_ids also skips the stale-partition filter, so a partition that is already imported stays eligible.
3. Check divergence_score and needs_reclustering in the jobs of GET /v1/orchestrate/{id}. Insert and update responses do not report them. After a delete, they are on each file’s result if its overall_status is COMMITTED.
4. (Optional) Call POST /v1/graph/recluster if the flag is true and you want to refresh the communities. Reclustering is never automatic.

Ordering rules

For guidance on structuring your data with categories, see the Design Guide.

Workflow Examples

Knowledge graph build

This example drives the build from File Manager categories. The direct upload with POST /v1/import-multiple, and a corpus build without a selector, are deprecated (see Import Files).

# Step 1: Health check
curl -H "Authorization: Bearer <token>" http://localhost:8080/v1/health

# Step 2: Build the corpus for the categories you uploaded to the File Manager.
# Returns 202 with corpus_build_id and graph_name.
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "embedding_strategy": "first_chunk",
    "categories": ["legal", "finance"],
    "strategy": { "top_k": 7, "cluster_threshold": 2 }
  }' \
  http://localhost:8080/v1/corpus/builds

# Step 3: Monitor build progress. Poll until status is completed or failed, and
# check error_code even on a completed build.
curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/v1/corpus/builds/<corpus_build_id>

# Step 4: Analyze the clusters. Returns 202 with strategize_job_id.
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"project": "my_project", "complexity": "high"}' \
  http://localhost:8080/v1/rag-strategizer/analyze

# Step 5: Monitor the strategizer job
curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/v1/rag-strategizer/jobs/<strategize_job_id>

# Step 6: Review the strategies
curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/v1/rag-strategizer/strategy

# Step 7: Start the orchestration. Returns 202 with orchestration_id.
# A 409 here means every eligible category is already in the knowledge graph.
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"project": "my_project", "replicas": 2, "max_retries": 3}' \
  http://localhost:8080/v1/orchestrate

# Step 8: Monitor the orchestration
curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/v1/orchestrate/<orchestration_id>

Checking the project state

curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/v1/projects/my_project/overview

Removing a category

# Graph cleanup and file deletion. delete_files is a query parameter.
curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  "http://localhost:8080/v1/projects/my_project/categories/legal?delete_files=true"

Field embedding on an existing collection

Use this when you already have documents in ArangoDB and only need vector embeddings and a search index on one attribute. No import or corpus build is required.

# Health check
curl -H "Authorization: Bearer <token>" http://localhost:8080/v1/health

# Embed one field (collection must exist; field must not end with _embedding)
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{"collection": "my_collection", "field": "content"}' \
  http://localhost:8080/v1/embed-field-in-collection

API Reference

For detailed API documentation, see the AutoGraph API Reference .