AutoGraph - API Reference

Top K value (optional, exposed parameter)

Clustering levels: 1 = single-level, 2 = two-level (default: 2)

Additional custom parameters

Must be the run currently holding the single-flight slot

The orchestration ID that was asked to stop

True when the running orchestration accepted the request

The run's status at acknowledgement time (still "running" until it terminalises)

Human-readable summary, including how the slot is released

Category (user-facing term; internal alias: module)

Number of documents in this category (FM subtree count)

True when this category's sources are ahead of / not covered by the corpus graph

True when this category has no RAG strategy yet

Current status: "idle", "pending", "running", "completed", "failed"

Progress percentage (0.0-100.0)

Status message

Corpus graph name (e.g. "{project}_CorpusGraph")

"building" | "ready" | "failed"

Number of source documents in the corpus (sources collection)

Number of Leiden clusters (domains collection) — NOT chunks

True when sources or strategies are out of date w.r.t. inputs

Deep link to the Arango UI graph explorer

Embedding strategy (e.g., "first_chunk")

Build strategy with configurable parameters

Deprecated. DEPRECATED: use categories. Explicit RAG input file IDs to fetch from File Manager.

Deprecated. DEPRECATED alias for categories. Same FM category-label resolution when categories is empty. Provide only one of categories, modules, or file_ids.

If true, preserve existing collections and only add/update specified modules

field 6 (scope) retired; replaced by categories below. Preferred. Category labels resolved via File Manager under GENAI_PROJECT_NAME. An already-encoded module label (today's persisted form) is also accepted as a legacy alias. Mutually exclusive with modules and file_ids (returns 400 if multiple provided). See user_facing_documentation.md §3 for full contract (precedence, default, examples).

Generated corpus build ID (e.g., "cb_01H...")

Named graph the build will produce (resolved deterministically at request time)

Must match configured GENAI_PROJECT_NAME (path param)

Bare category label to delete (path param); an already-encoded module is also accepted as a legacy alias

If true, also delete the category's files from the File Manager

True when the delete flow completed

Echo of the deleted category

True when corpus/KG data for the category was removed

Number of files removed from the File Manager

Files skipped because they were locked (not deleted)

Files to delete, identified by File Manager file_id (primary).

Alternative targets identified by filename; resolved by category + filename when file_id is not used. Independent of file_ids ("and/or").

Category (module alias) the targets belong to (shared across the batch). Optional when the project has exactly one category (auto-resolved); required and must name an existing category otherwise. doc_names are resolved by category + filename; each file_id target is asserted to belong to the resolved category (a mismatch is rejected).

Per-file deletion results

RAG partitions that were updated

RAG partitions that were removed entirely

Per-partition L3 delete outcome

Whole-batch commit / rollback / failure

Clusters that were updated, regardless of whether a RAG partition exists for them yet

Clusters that were removed entirely, regardless of whether a RAG partition exists for them yet

Id for this synchronous delete (also the concurrency-lock key)

ID of the file this result is for

Outcome of the deletion for this file

Error description, if any

RAG partition associated with the file

Cluster the file belonged to (the cluster document _key, e.g. "cluster_legal_0"; matches InsertFileStatus.cluster_key)

Number of similarity edges removed

AIS-1444: partition's divergence after this delete (cumulative churn / baseline); set once the Layer-3 delete leg has run

AIS-1444: true when divergence_score now exceeds the partition's threshold

Path parameter; must match configured GENAI_PROJECT_NAME

Query parameter (?delete_files=true), NOT a request body. The DELETE HTTP binding declares no `body`, so grpc-gateway populates this from the query string and ignores any JSON body. Defaults to false: a full File Manager wipe requires the caller to opt in deliberately via ?delete_files=true. Also delete safe File Manager files when true

Arango _key of the surviving document

Arango _id of the surviving document

Module the document belongs to

Filename the document is keyed by

Every input file that mapped onto it, in input order; the LAST one's content survived

File Manager ids for the same files, in the same order (empty entries omitted)

True when these files also overwrote a document from an earlier build

Name of the collection (e.g. "A")

Document attribute to embed (e.g. "content"); stored in _embedding

e.g. "completed"

Human-readable message

Collection name

Source field name

Name of the field where embeddings are stored (e.g. content_embedding)

Number of documents that received embeddings

Number of documents that already had embedding (skipped)

Collection size (coll.count); reconcile against updated+skipped+failed+ineligible

Number of documents that failed (empty value or error)

Rows with null/absent source field and no embedding (neither embedded nor failed)

Document name (required)

File content in bytes (required)

URL to be cited in inline citations (optional)

Flexible metadata string (optional, user-defined format)

Corpus build ID to check status for

Corpus build ID

Status: "pending", "running", "completed", "failed"

Human-readable status message

Progress percentage (0-100)

Error message if status is "failed"

Unix timestamp when build started

Unix timestamp when build completed (if finished)

Machine-readable code (e.g. LLM_RATE_LIMITED) when failed

Named graph for the build; seeded from pending/running (same value as POST), retained on failure; counts below are set on completion

Number of source documents (populated when completed; 0 otherwise)

Number of domain clusters (populated when completed; 0 otherwise)

FM files new to the corpus this build (incremental FM builds; 0 otherwise)

Corpus orphans removed vs current FM listing (incremental FM builds; 0 otherwise)

Corpus docs still present in FM (incremental FM builds; 0 otherwise)

Deduplication reporting (AIS-1819). Corpus documents are keyed by (module, filename), so two input files sharing both produce ONE document -- intended, but previously invisible: a 100-file build could leave 99 documents with nothing reported anywhere. Populated on completion. Dedup is by name only; identical extracted content under different filenames stays two documents. See user_facing_documentation.md §"Document identity and deduplication". Input files that were successfully written this build

Distinct documents those files produced (files_written minus documents_deduplicated)

Input files absorbed into a document another file already owned

One entry per collapsed document, naming every source file that mapped onto it

Orchestration ID returned by POST /v1/orchestrate

The orchestration ID queried

"running" | "completed" | "failed" | "cancelled" -- terminal only when every job is terminal

Total number of import jobs (0 while phase is "initializing" -- the job set is not known yet)

Jobs completed successfully (includes skipped_jobs)

Jobs that failed (after all retries)

Human-readable summary

Per-job details (all jobs, including pending/running)

AIS-1816. "initializing" | "starting_importers" | "importing" | "verifying" | "finished" -- see the message comment above

Jobs currently assigned to an importer replica

Jobs loaded but not yet dispatched

Jobs counted in completed_jobs that imported nothing (no requested file_ids in that partition)

Entities the importer reported writing this run, summed over terminal jobs. 0 is NOT evidence that nothing was imported: a VectorRAG partition writes Documents, Chunks and Relations but no entities by design, so a successful VectorRAG-only run reports 0 here. Read jobs[].imported / skipped_jobs to tell a real no-op from an entity-free import.

Wall-clock since the run was triggered

Since an importer worker last answered; a large value on a "running" run means the fleet has gone quiet

Whether the knowledge graph was checked to actually contain the partitions the importer reported as imported. Absent means not checked yet (the run is not terminal) or the check could not be performed (KG lookup itself failed -- reported in message, and never turned into a false import failure).

Partitions whose jobs reported success but which are absent from the knowledge graph; non-empty forces status "failed"

AIS-1847: the strategy-level tally, so a caller can report how many strategies succeeded and failed -- and why each failure failed -- without filtering `jobs` itself. Absent means no strategy set was ever loaded (the run died in setup, or corpus_rags held no profiles): that is NOT the same as a run where none succeeded, and a zeroed summary would read as a finished run that happened to do no work.

Project name (must match GENAI_PROJECT_NAME) — required

File Manager scope subtree filter (0–5 labels)

Case-insensitive substring match on file name (forwarded to FM)

Exact-name filter (forwarded to FM)

FM paging limit (0 = FM default); forwarded to FM

FM paging offset; must be >= 0. Negative values are clamped to 0 server-side before forwarding to FM (which rejects negatives with 400).

Unfiltered top-level category listing; never narrowed by search/name/limit/offset

Number of categories in the (unfiltered) categories list above

Unfiltered document total for the project: the sum of the category document_counts above.

File Manager filtered page total for a browse/paging request (any of search/name/limit/offset set): the FM 'total' for that filtered/paged view. 0 (unset) when no browse/paging params are present.

Strategize job ID to check status for

Status: "idle", "pending", "running", "completed", "failed"

Overall phase progress percentage (0.0-100.0)

Total clusters to analyze in Phase 1

Clusters that have finished analysis (including empty/failed)

Human-readable status or failure reason (e.g. Unknown categories)

List of all RAG strategies

Total number of strategies

Count of strategies by type (e.g., "VectorRAG": 5, "FullGraphRAG": 3, and any future strategy types)

status can be "SERVING" or "NOT_SERVING"

message is always "Service is healthy" (OAS-12591). The endpoint is unauthenticated so Kubernetes probes can reach it, and it reports only whether this process is up -- no dependency, provider or tracing state. Earlier versions embedded a JSON per-provider LLM-tracing snapshot here (AIS-1530); that was removed. Consumers keying on `status` are unaffected.

List of files to process

Module label for this batch of files (e.g., "legal", "marketing")

Whether the operation succeeded

Success or error message

Detailed error message if success is false

Batch of files to insert, each referenced by file_id

Category label (e.g. "legal") whose corpus partition scopes similarity + clustering, resolved server-side under GENAI_PROJECT_NAME as in POST /v1/corpus/builds. Empty resolves to the project's only category; required once a project has more than one.

Document name; must match the name encoded in file_id (required)

File Manager id supplying the content (required)

Echoes InsertFileInput.doc_name

Whether this file was inserted

Populated when success is false

e.g. "legal_0_a"

Assigned cluster, e.g. "cluster_legal_0" (field 5 to match DeleteFileStatus.cluster_key)

File Manager id, echoed for files referenced by file_id

KG named graph (e.g. "{project}_kg")

"not_built" | "building" | "built" | "stale"

Distinct entities in the KG; 0 on a VectorRAG-only project -- Entities exist for FullGraphRAG partitions only, not a failed import

Distinct relationships in the KG

True when KG partitions diverge from current strategies

categories not yet imported into the KG

categories whose strategy no longer exists

Config persisted to metadata (overall success)

Validation passed

In-place update succeeded (live immediately); false = restart required

True when embedding config changed (model/provider/api_url; existing vectors invalidated)

"valid" | "invalid" | "expired" | "rate_limited" | "insufficient_quota"

On validation error (valid=false), these fields are populated: Field name that failed

Error code enum

Human-readable error

Partition ID of the job

FullGraphRAG or VectorRAG (from strategy profile in rags). A completed VectorRAG job creates Documents/Chunks/Relations only -- that partition cannot serve LOCAL/GLOBAL/UNIFIED queries (AIS-1748)

pending | running | completed | failed

Number of retries attempted

Error details if failed (from importer current_status.message)

Module label (corpus_rags.module); empty for legacy no-module projects

AIS-1444: the partition's divergence, computed at the right time -- right after Layer 3 actually created/grew this partition's entities. This is the authoritative score (the insert/update responses no longer carry a premature one); it is also persisted on the rags node. Populated on the terminal poll once the job is completed. cumulative churn / baseline after this orchestration

true when divergence_score exceeds the partition's threshold

AIS-1816: what this job actually wrote, so "completed" is auditable per partition rather than being taken on trust. entities the importer reported writing (import_result.entities_added); absent until the job is terminal. 0 is a real value, not "nothing imported": a VectorRAG job writes documents/chunks and no entities -- check imported instead

false on a completed job that performed no import (requested file_ids matched nothing in this partition) -- a no-op success, not written output

Current status: "idle", "pending", "running", "completed", "failed"

Progress percentage (0.0-100.0)

Status message

Cluster ID (e.g., "cluster_0", extracted from INGESTED_AS relation edge or derived from rag_partition_id)

Strategy type: "VectorRAG", "FullGraphRAG", or future types. Determines the partition's retrieval capability: FullGraphRAG partitions have Entities/Communities and serve LOCAL/GLOBAL/UNIFIED; VectorRAG partitions have neither and serve none of them (AIS-1748)

Partition ID (e.g., "domain_0_a", "domain_1_b")

Extracted entity types for this domain

Number of documents in this cluster

Extensible strategy-specific parameters (e.g., rag_mode, batch_size, enable_chunk_embeddings, PDF parsing flags, etc.)

Partition this result is for

True when a recluster was scheduled (or coalesced into an in-flight one)

Populated when this partition could not be scheduled (e.g. blank id)

True when any corpus category lacks a strategy or a strategy is out of date

Corpus categories missing a RAG strategy

Strategies loaded for this run

Reached a terminal success (includes skipped)

Failed after all retries

Counted in succeeded, but imported nothing

Loaded but not yet terminal: queued or in flight

One per failed strategy; empty when failed == 0

The partition whose profile this strategy is

"FullGraphRAG" | "VectorRAG"

corpus_rags.module; empty for legacy no-module projects

The importer's own words, after all retries; absent when the job was failed without one

Attempts made before giving up

GenAI project name (required)

Number of worker replicas to spawn

Max retry attempts per failed job (default: 3)

Env overrides for importer

Secret manager profile IDs for chat

Secret manager profile ID for embedding

Module labels to scope orchestration; empty = all

When non-empty, orchestration is narrowed to the strategized clusters that actually contain these File Manager file_ids, and each such partition imports only those ids (AIS-1809); a partition whose intersection is empty is skipped as a completed no-op, not a failure; a request in which NO id matches any document in any strategized cluster is rejected up front with HTTP 409 NoMatchingFilesError naming the unmatched ids (it would spawn importer pods for zero work and hold the single-flight slot), so ids no longer need validating before calling; matching uses only the file_id stamped on corpus sources by corpus build (autograph v0.0.13+) -- there is no filename fallback for a targeted request; empty means the whole cluster (existing behavior)

ID returned when orchestration starts

True when background orchestration was dispatched (immediate unary response only)

e.g. "Orchestration started" on immediate return (totals/job_results start at zero)

AIS-1815: requested file_ids with no match in any strategized cluster; set on partial match, empty otherwise

Must match configured GENAI_PROJECT_NAME

Required; omitted/unknown values are rejected (400)

Default false; only true with high or very_high

Module aliases for scoped re-gen; empty = all

Max clusters to analyze in parallel (LLM calls). 0 = default (5).

Job ID for the async strategizer run

RAG partitions to recluster, e.g. "legal_0_a" (capped per request)

One entry per requested partition id

Batch of files to update, each referenced by file_id

Deprecated. DEPRECATED: use category. Same category-label resolution.

Preferred. Category label (bare or already-encoded, see InsertDocumentsRequest.category) scoping similarity + clustering. Alias for module when module is empty.

ID returned when the update starts

True when the background update was dispatched

e.g. "Update started" on immediate return

Empty on dispatch (reserved; combined per-file outcome is surfaced via the status slot)

Echoes InsertFileInput.doc_name

Whether the delete leg fully committed

Whether the insert leg succeeded

Populated when the update did not fully succeed

Cluster assigned by the insert leg, e.g. "cluster_legal_0"

RAG partition after re-insert, e.g. "legal_0_a"

Echoes InsertFileInput.file_id

Cluster the file belonged to before the delete leg (observability)

Project name (validated against env)

Chat provider: "openai" | "triton" | "custom" — required

Embedding provider: "openai" | "custom" — required

Chat/completions model name — required

Embedding model name — required

Chat secret manager profile id — required (never a raw key)

Embedding secret manager profile id — required (never a raw key)

Multimodal model name — optional

Chat API base URL — required when chat_api_provider is "custom"; optional otherwise

Embedding API base URL — required when embedding_api_provider is "custom"; optional otherwise

Cluster ID (path param)

"VectorRAG" or "FullGraphRAG"

Forced empty for VectorRAG

Forced false for VectorRAG

The updated RAG strategy