AutoGraph HTTP API reference

This page and the pages of this section describe the HTTP API of the AutoGraph service. Use it to automate the AutoGraph pipeline or integrate it into existing workflows. It produces the same result as the web interface. For what AutoGraph does and how it works, see the AutoGraph overview.

Prerequisites

• Arango Contextual Data Platform
• LLM and embedding API access (commonly OpenAI-compatible endpoints)
• Valid JWT for the API (Authorization: Bearer ...)
• Platform auth reachable from the service (for token validation and renewal), if your deployment uses it

Before importing data, you need to create a project. Projects keep datasets and configurations isolated from each other.

For detailed instructions on creating and managing projects, see the Projects section in the Arango Control Plane (ACP) documentation.

Install the service

To install and start the AutoGraph service, use the following endpoint of the Arango Control Plane (ACP):

The web interface installs the service for you when you start the first build of a project.

Send the install keys in the env map of the request body. Key names are lowercase snake_case and have to be spelled exactly as shown below. Keys with a different spelling are not passed on to the service and are silently ignored.

curl -X POST https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/autograph \
  -H "Authorization: Bearer <your-bearer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "env": {
      "db_name": "mydb",
      "genai_project_name": "myproject",
      "fps_recovery_username": "autograph-recovery",
      "chat_api_provider": "openai",
      "chat_secret_profile_id": "<chat-profile-id>",
      "chat_model": "gpt-5.4-nano",
      "embedding_api_provider": "openai",
      "embedding_secret_profile_id": "<embedding-profile-id>",
      "embedding_model": "text-embedding-3-small",
      "embedding_dim": "512"
    }
  }'

Required keys

Common optional keys

For all chat and embedding parameters, including provider-specific defaults, see LLM Configuration.

The Importer workers that build the Knowledge Graph are installed, run, and torn down by the orchestration. You do not install the Importer yourself unless you use it outside AutoGraph, see The Importer.

Supported file formats

The corpus build does not parse documents itself. It hands every input that is not already plain text or Markdown to the File Parser service, which samples it and converts it to Markdown. AutoGraph then embeds and clusters that Markdown.

The File Parser is an internal data platform service installed once per environment, without a web interface of its own. The Importer uses the same service when it builds the knowledge graph, so the whole AutoGraph pipeline accepts one consistent set of inputs:

• PDF: .pdf files including scanned documents, read using OCR
• Office documents: .doc, .docx, .ppt, and .pptx files
• Plain text: .txt and .md files

For the per-format detail and for how to size the parser on a self-hosted cluster, see Document conversion and the File Parser.

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. For the pipeline architecture, see Architecture.

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. To run the same sequence without code, use the AutoGraph Studio web interface.

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.

Once the Knowledge Graph is built, deploy a retriever and query it with AutoRAG.

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

Learn more

• LLM Configuration: Configure the chat and embedding providers the service calls.
• Incremental Graph Updates: Insert, delete, and replace individual documents in a graph that is already built.
• Document conversion and the File Parser: What the parser extracts from each format and how to size it.
• The Importer: The worker that builds the Knowledge Graph, and the parameters you can pass to it through importer_env.
• Architecture: The three-layer knowledge graph architecture and the resulting collections.
• Design Guide: How to structure your data with categories, layers, and components.
• Use Cases: Real-world enterprise applications and business impact metrics.

For the machine-readable API, see the AutoGraph API Reference .