AutoGraph Project Operations

The endpoints on this page sit outside the sequential pipeline. You can inspect and configure a project at any time. The two delete endpoints are guarded against a running build or orchestration and return 409 while one is active.

The {project} path segment always has to name the project that the service runs against. What a mismatch returns differs per endpoint and is documented below.

Project Overview

Read the state of a project in one aggregate call: a corpus graph card, a knowledge graph card, a strategies block, and a per-category list with staleness flags.

Recommended path: Safe to call at any time, it is a read-only aggregate. Use it to drive a dashboard, to decide whether a build is needed before you call POST /v1/corpus/builds, and to find the categories that still have no strategies. Staleness is computed at read time, there is no stored flag that you have to refresh.

Parameters

Response

{
  "project": "my_project",
  "corpus_graph": {
    "name": "my_project_CorpusGraph",
    "status": "ready",
    "document_count": 428,
    "cluster_count": 12,
    "stale": true,
    "graph_explorer_url": "https://.../_db/my_project/_admin/aardvark/graph/my_project_CorpusGraph"
  },
  "knowledge_graph": {
    "name": "my_project_kg",
    "status": "stale",
    "entity_count": 3184,
    "relationship_count": 9022,
    "stale": true,
    "new_categories": ["finance"],
    "removed_categories": []
  },
  "strategies": {
    "stale": true,
    "categories_without_strategies": ["finance"]
  },
  "categories": [
    {
      "name": "legal",
      "document_count": 210,
      "needs_corpus_update": false,
      "needs_strategies": false
    },
    {
      "name": "finance",
      "document_count": 218,
      "needs_corpus_update": true,
      "needs_strategies": true
    }
  ],
  "category_count": 2,
  "total_documents": 428,
  "filtered_total_documents": 0
}

Deciding what to do next

A failed File Manager call is never rendered as an empty but successful page. You get an error status instead of a misleading all-zero overview. The response is scoped to your project: categories and file counts of other projects that share the same ArangoDB database are never returned.

HTTP Example

curl -H "Authorization: Bearer <token>" \
  https://<EXTERNAL_ENDPOINT>:8529/autograph/v1/projects/my_project/overview

Update Model Config Credentials

Set the chat and embedding provider, the models, and the secret profiles of a project. The service validates the credentials against the provider with a live inference call, applies the configuration to the running pod where it can, and persists it to the project metadata.

Recommended path: Call it before your first corpus build, and whenever you rotate keys or change models. Chat and embedding are configured independently. There is no idle-only restriction, so you can call it during a corpus build, but a running build keeps its existing clients and the change only takes effect on the next one.

For guidance on picking providers and models, see LLM Configuration.

Request

{
  "chat_api_provider": "openai",
  "chat_model": "gpt-5.4-nano",
  "chat_secret_profile_id": "chat-profile-id",
  "embedding_api_provider": "openai",
  "embedding_model": "text-embedding-3-small",
  "embedding_secret_profile_id": "embedding-profile-id",
  "multimodal_model": "gpt-5.4",
  "chat_api_url": "https://api.openai.com/v1",
  "embedding_api_url": "https://api.openai.com/v1"
}

Parameters

Only secret profile IDs are stored. Raw API keys are never persisted to the project metadata.

Response

{
  "applied": true,
  "valid": true,
  "applied_to_running_pod": true,
  "rebuild_required": false,
  "key_status": "valid",
  "field": "",
  "error_code": "",
  "message": ""
}

The following is an example of a rejection with 400, here for a chat secret profile that cannot be resolved:

{
  "applied": false,
  "valid": false,
  "applied_to_running_pod": false,
  "rebuild_required": false,
  "key_status": "",
  "field": "chat_secret_profile_id",
  "error_code": "SECRET_NOT_FOUND",
  "message": "Secret profile '00000000-0000-0000-0000-000000000000' not found"
}

The two metadata write faults are the exception. They are server errors, 503 and 500, and they carry the standard JSON error body instead of the response documented above, because nothing was wrong with the request itself.

Embedding identity is immutable

Once embedding_api_provider, embedding_model, and embedding_api_url have been saved for a project, they cannot be changed. A request that changes any of them is rejected with 400, valid: false, error_code: EMBEDDING_CONFIG_IMMUTABLE, and a field naming the offending value. Nothing is written to the metadata and nothing is applied to the pod.

A different embedding model produces vectors that do not match the ones already stored, and the corpus cannot be re-embedded without stranding the knowledge graph that was built from it. What is still allowed is rotating embedding_secret_profile_id, and any change to the chat provider, model, URL, or secret. To embed with a different model, create a new project.

Error codes

The stable error_code values of a validation failure are INVALID_API_KEY, KEY_EXPIRED, INSUFFICIENT_QUOTA, RATE_LIMITED, PERMISSION_DENIED, MODEL_NOT_FOUND, MODEL_REJECTED_REQUEST, ENDPOINT_UNREACHABLE, TIMEOUT, PROVIDER_ERROR, PROVIDER_EMPTY_RESPONSE, RESPONSES_API_UNAVAILABLE, API_KEY_REQUIRED, MODEL_REQUIRED, INVALID_BASE_URL, PROVIDER_NOT_FOUND, URL_REQUIRED, SECRET_PROFILE_REQUIRED, SECRET_NOT_FOUND, SECRET_RESOLUTION_ERROR, PROJECT_MISMATCH, EMBEDDING_CONFIG_IMMUTABLE, and UNKNOWN_VALIDATION_ERROR. They all come with a 400.

The metadata write codes METADATA_WRITE_TIMEOUT and METADATA_WRITE_FAILED are not validation failures. The configuration passed the validation but could not be stored, so they are server faults and come with a 503 and a 500 respectively.

Notes

• Validation is a minimal live inference probe, not a catalog lookup, with a 10-second timeout. It uses the chat_api_url and embedding_api_url from the request when you supply them, so send them if a valid model behind a custom OpenAI-compatible endpoint is rejected.
• Concurrent updates are serialized, not rejected. A global lock makes the second request wait for the first, so expect a slower response rather than a 409.
• A rejected candidate configuration is reported in the response only. Nothing is written to the metadata or applied to the pod, and it does not overwrite the status of a corpus build or a strategizer job.
• The persisted configuration lives at the project level in the metadata and survives a teardown and redeployment of the AutoGraph service.

Model configuration after a pod restart

After a pod restart, AutoGraph tries to reload the saved chat and embedding settings from the project metadata in the background, and then probes the effective configuration with a live inference call.

Reconciliation is best effort. If the saved configuration cannot be read, its secret profiles cannot be resolved, or it cannot be applied in-process, AutoGraph keeps the deploy-time configuration and probes that instead. Saved settings are therefore restored when the reconciliation succeeds, not guaranteed on every restart.

The service accepts health checks and read requests immediately, but the model-sensitive work of a corpus build, a strategizer run, and an orchestration is rejected with 400 until the reconciliation and the probe have finished. If the probe comes back with a definitive rejection, those requests stay blocked until a successful call to this endpoint applies a valid configuration to the running pod. Only definitive, non-retryable codes latch the gate this way. Transient ones such as ENDPOINT_UNREACHABLE, TIMEOUT, RATE_LIMITED, and PROVIDER_ERROR are logged and leave the gate open.

HTTP Example

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "chat_api_provider": "openai",
    "chat_model": "gpt-5.4-nano",
    "chat_secret_profile_id": "chat-profile-id",
    "embedding_api_provider": "openai",
    "embedding_model": "text-embedding-3-small",
    "embedding_secret_profile_id": "embedding-profile-id"
  }' \
  https://<EXTERNAL_ENDPOINT>:8529/autograph/v1/projects/my_project/model-config/credentials

Delete Category

Remove a category from the corpus graph and from the knowledge graph, and optionally delete its files from the File Manager.

Recommended path: Call it when you want to remove a category and clean up everything it contributed. This is also the supported way to recover a partition that imported incompletely: delete the category, build it again, re-run the strategizer, and orchestrate.

What is removed, in order

1. Knowledge graph (Layer 3). The rag_partition_id values of the category are resolved from rags, and every knowledge graph record in those partitions is removed: Relations first, then Entities, Chunks, Documents, Communities, and SemanticUnits. This is a no-op when the knowledge graph was never built.
2. Corpus graph (Layers 1 and 2). All sources, similarities, domains, corpus_relations, and rags rows of the category.
3. Files. Only when delete_files is true.

Steps 1 and 2 always run when the category exists. delete_files controls step 3 only. There is no way to delete the files while keeping the graph data, and no way to remove the corpus graph while keeping the knowledge graph.

Both graph steps run inside the build and orchestration lock, so a concurrent build cannot interleave. If the knowledge graph step fails, the request aborts with 500 before the corpus graph is touched. The rags rows survive so that you can retry, and Layer 3 data is never left orphaned.

Parameters

This endpoint takes no request body.

# Correct
DELETE /v1/projects/my_project/categories/legal?delete_files=true

# Ignored, files are kept
DELETE /v1/projects/my_project/categories/legal   -d '{"delete_files": true}'

Response

{
  "deleted": true,
  "category": "legal",
  "graph_updated": true,
  "files_deleted": 12,
  "locked_skipped": []
}

Deleting a category also removes its strategies, so building it again is a full corpus build, then the strategizer, then an orchestration.

HTTP Example

# Graph cleanup and file deletion
curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  "https://<EXTERNAL_ENDPOINT>:8529/autograph/v1/projects/my_project/categories/legal?delete_files=true"

# Graph cleanup only, the files stay in the File Manager
curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  "https://<EXTERNAL_ENDPOINT>:8529/autograph/v1/projects/my_project/categories/legal"

Delete Project

Tear down an entire project: every AutoGraph-owned service, graph, view, and collection, optionally its File Manager files, its project metadata, and the local staging directory. After a successful response has been sent, the AutoGraph service deletes itself.

Parameters

Response

{
  "deleted": true,
  "project": "my_project",
  "collections_deleted": ["my_project_sources", "my_project_Entities"],
  "graphs_deleted": ["my_project_kg", "my_project_CorpusGraph"],
  "services_deleted": ["svc-abc123"],
  "views_deleted": ["my_project_sources_search_view"],
  "files_deleted": 12,
  "locked_skipped": [],
  "warnings": []
}

Notes

• Locked files block completion. With delete_files=true, a file marked safe_to_delete: false is not deleted. It is listed in locked_skipped, added to warnings, and the response comes back with deleted: false. Because the file cleanup is incomplete, the project scope is not unregistered and the project metadata is not deleted on that attempt. Unlock the files and retry to finish the teardown.
• Only unambiguously project-owned resources are removed. A graph, view, or collection whose ownership is ambiguous, such as a custom graph that mixes project and shared collections, is preserved and reported in warnings. This is informational: it does not block deleted: true and it does not hold the deletion lock. Removing such a resource is a manual operator task in ArangoDB.
• Self-teardown happens only after deleted: true, and only after the response has been sent. On a partial failure the service stays up so that you can retry.
• deleted: true does not mean the pod is already gone. The self-teardown is asynchronous and best effort, it is only scheduled after the response, and its outcome is not reported back. Do not immediately recreate the same project against the just-deleted service, because a follow-up create can race a pod that is still running. Confirm that the old service ID has disappeared from the platform service listing first.
• A partially torn-down project is locked. Once a delete has removed at least one resource, further mutating calls, such as corpus builds, imports, orchestrations, strategizer runs, model-config updates, category deletes, and strategy overrides, are rejected with 409 until the delete is retried to completion. A delete that fails before it mutated anything does not lock the project.

HTTP Example

# Opt in to file deletion
curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  "https://<EXTERNAL_ENDPOINT>:8529/autograph/v1/projects/my_project?delete_files=true"

# Keep the File Manager files
curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  "https://<EXTERNAL_ENDPOINT>:8529/autograph/v1/projects/my_project"

Next Steps

• Corpus Build: Build or extend the corpus graph
• LLM Configuration: Choose providers and models
• Error Handling: HTTP codes and troubleshooting