Arango logo
arango.ai 

Importer Service Reference

Importer HTTP API endpoints, authentication, and recommended call sequence

This section documents the Importer HTTP API. All endpoints require JWT authentication and are served on port 8080. For the underlying collections and the async-job lifecycle, see Architecture.

Field names are lowerCamelCase over HTTP. This reference uses the protobuf field names, such as partition_id or job_id. The HTTP API emits the JSON names instead, so an actual response carries partitionId and jobId. Convert accordingly when you read a response or build a request body.

Authentication

All endpoints require a JWT in the Authorization header:

Authorization: Bearer <jwt_token>

The service handles token renewal automatically for long-running imports. Read-only endpoints (GET /v1/jobs and GET /v1/jobs/{job_id}) validate the token without renewing it.

Synchronous HTTP errors

These status codes apply to the immediate HTTP response of an API call:

ConditionHTTP
Missing or malformed Authorization header401
Token rejected401
Database access denied after auth403
Invalid rag_mode, partition_id, vector params, or missing file_name400
Unexpected server fault500
POST /v1/recluster while the import lock is held503

Many business failures (busy importer, multi-file validation) return HTTP 200 with "success": false in the JSON body. See Error Handling for the full table.

Endpoints

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

MethodPathDescriptionDetails
GET/v1/healthCheck service readinessImport Files
POST/v1/importImport a single fileImport Files
POST/v1/import-multipleImport a batch of filesImport Files
POST/v1/reclusterRebuild the community layer of one partitionIncremental Updates
GET/v1/jobs/{job_id}Get the status of a multi-file import or recluster jobImport Files
GET/v1/jobsList recent jobsImport Files

A replica can only run one import or recluster job at a time, under a single global lock that is not keyed by partition. While one job holds the lock, calls to the other endpoints are rejected. How they are rejected depends on the endpoint you call. The import endpoints return HTTP 200 with "success": false, whereas /v1/recluster returns HTTP 503 (gRPC UNAVAILABLE). See Concurrency.

There is no endpoint for deleting or updating a document. AutoGraph removes and replaces documents across all three layers. See Deleting a document and Updating a document.

Standalone single file

  1. GET /v1/health - confirm the service is ready.
  2. POST /v1/import - submit the file. Returns success: true and starts processing in the background. No job_id is returned.
  3. Monitor via the platform service status until the status reaches service_completed or a terminal failure status.
  4. Query ArangoDB or call AutoRAG against the resulting knowledge graph.

Standalone batch

  1. GET /v1/health
  2. POST /v1/import-multiple - save the returned job_id.
  3. Poll GET /v1/jobs/{job_id} (for example, every 10-30 seconds) until is_terminal is true.
  4. On service_completed, verify the graph; on failure, read current_status.message and consult Error Handling.

Via AutoGraph

When AutoGraph drives the pipeline, you do not call the Importer directly. AutoGraph orchestration submits one import per partition, sets partition_id from the corpus build, and sets rag_mode from the RAG Strategizer’s assignment. Monitor via the AutoGraph orchestration status and the platform service status. See AutoGraph Integration.

Reclustering

  1. Call POST /v1/recluster and save the returned job_id.
  2. Poll GET /v1/jobs/{job_id} until is_terminal is true.

See Incremental Updates for the request fields, what the operation rebuilds, and how to troubleshoot problems. To remove or replace a document, use AutoGraph’s POST /v1/graph/delete or POST /v1/graph/update.

  • Incremental Updates: Reclustering, and how documents are removed and replaced in Layer 3.
  • Parameters: Complete request parameter reference.
  • Error Handling: Troubleshooting, known limitations, and error markers in job status messages.
  • Limits and Quotas: Concurrency, size, timeout, and provider limits, and which of them are configurable.
  • API Reference : Full machine-readable API reference.

On this page