Arango Control Plane HTTP API

The Arango Control Plane (ACP) service provides an HTTP API for installing, inspecting, upgrading, and removing platform services, as well as for managing the projects that group AutoGraph and AutoRAG work.

Base URL: https://<EXTERNAL_ENDPOINT>:8529/_platform/acp

Authentication uses a Bearer token in the Authorization header. See Obtaining a Bearer token for how to generate one.

Health Check

Returns the current health status of the service.

curl -X GET https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/health \
  -H "Authorization: Bearer <your-bearer-token>"

Response (200):

{
  "status": "OK"
}

Services

Once a service is installed, it is identified by the serviceId that the response returns. You need this ID for the status, upgrade, and uninstall endpoints.

Service Creation Request Body

All service creation endpoints share the same env and labels fields:

{
    "env": {
        "profiles": "gpu,internal",
        "<service-specific-key>": "<value>"
    },
    "labels": {
        "key1": "value1",
        "key2": "value2"
    }
}

• env: Service-specific parameters as key-value pairs. The required keys depend on the service type; see the corresponding service documentation, such as Importer and AutoRAG.
• labels (optional): Key-value pairs used to filter and identify services in the platform.
• profiles (optional): A comma-separated string inside env defining which resource profiles to apply (for example, "gpu,internal"). If not set, the service uses the default profile. Profiles must already exist in the platform.

The /v1/service endpoint additionally takes a service_name field, which lets you deploy any Helm chart:

{
    "service_name": "<helm-chart-service-name>",
    "env": { "<key>": "<value>" },
    "labels": { "<key>": "<value>" }
}

Deploy a Service

Installs a service of the given type. The example below deploys the Importer service.

curl -X POST https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/graphragimporter \
  -H "Authorization: Bearer <your-bearer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "env": {
      "db_name": "your_database_name",
      "project_name": "your_project_name",
      "chat_api_provider": "openai",
      "chat_api_url": "https://api.openai.com/v1",
      "embedding_api_provider": "openai",
      "embedding_api_url": "https://api.openai.com/v1",
      "chat_model": "gpt-5.4-nano",
      "embedding_model": "text-embedding-3-small",
      "chat_api_key": "your_openai_api_key",
      "embedding_api_key": "your_openai_api_key",
      "embedding_dim": "512"
    }
  }'

Where:

• db_name: Name of the ArangoDB database where the knowledge graph will be stored
• project_name: Name of an existing project (see Projects). Used as a prefix for all ArangoDB collections (for example, a project named docs creates docs_Documents, docs_Chunks, etc.)
• chat_api_provider: Set to "openai" for the OpenAI API, or "custom" for any other OpenAI-compatible API
• chat_api_url: API endpoint URL for the chat/language model service. Required for "custom"; defaults to the OpenAI URL for "openai"
• embedding_api_provider: Set to "openai" for the OpenAI API, or "custom" for any other OpenAI-compatible API
• embedding_api_url: API endpoint URL for the embedding model service. Required for "custom"; defaults to the OpenAI URL for "openai"
• chat_model: Specific language model to use for text generation and analysis
• embedding_model: Specific model to use for generating text embeddings
• chat_api_key: API key for authenticating with the chat/language model service
• embedding_api_key: API key for authenticating with the embedding model service
• embedding_dim (optional): Embedding dimension. The default value is 512. Only set manually if using a custom embedding model with a different dimension; must match the embedding model’s output dimension.

Response (200):

{
  "serviceInfo": {
    "serviceId": "arangodb-graphrag-importer-of1ml",
    "description": "Install complete",
    "status": "DEPLOYED",
    "namespace": "arangodb-platform-dev"
  }
}

Check the Status of a Service

Returns the current state of an installed service.

Path parameters:

curl -X GET https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/service/arangodb-graphrag-importer-of1ml \
  -H "Authorization: Bearer <your-bearer-token>"

Response (200):

{
  "serviceInfo": {
    "serviceId": "arangodb-graphrag-importer-of1ml",
    "description": "Install complete",
    "status": "DEPLOYED",
    "namespace": "arangodb-platform-dev"
  }
}

Upgrade a Service

Use this endpoint to change the environment variables or labels of a running service, or to upgrade it to the latest chart version. Every call upgrades the Helm chart to the latest version. You cannot select a specific version.

Path parameters:

curl -X PUT https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/service/arangodb-graphrag-importer-of1ml \
  -H "Authorization: Bearer <your-bearer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "env": {
      "db_name": "your_database_name",
      "project_name": "your_project_name",
      "chat_api_provider": "openai",
      "chat_api_url": "https://api.openai.com/v1",
      "embedding_api_provider": "openai",
      "embedding_api_url": "https://api.openai.com/v1",
      "chat_model": "<new-chat-model>",
      "embedding_model": "text-embedding-3-small",
      "chat_api_key": "your_openai_api_key",
      "embedding_api_key": "your_openai_api_key",
      "embedding_dim": "512"
    },
    "labels": { "key1": "value1" }
  }'

The request body is optional. Omitting it (or sending {}) triggers an upgrade to the latest chart version with no configuration changes.

• env (optional): Updated service-specific environment variables. The object replaces the current env rather than merging into it, so send every value the service needs, not only the ones you are changing. The example above resends the full env the service was installed with for that reason, changing only chat_model.
• labels (optional): Updated key-value pairs used to filter and identify the service in the platform.

Uninstall a Service

Removes an installed service from the platform.

Path parameters:

curl -X DELETE https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/service/arangodb-graphrag-importer-of1ml \
  -H "Authorization: Bearer <your-bearer-token>"

Response (200):

{
  "serviceInfo": {
    "serviceId": "arangodb-graphrag-importer-of1ml",
    "description": "Uninstall complete",
    "status": "UNINSTALLED",
    "namespace": "arangodb-platform-dev"
  }
}

List Services

Lists all installed services, optionally filtered by labels.

curl -X POST https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/list_services \
  -H "Authorization: Bearer <your-bearer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "labels": {
      "key1": "value1"
    }
  }'

An empty request body ({}) returns all installed services.

Projects

Projects group related AutoGraph, Importer, and AutoRAG services and keep their data separate. They are required for all three. For a conceptual overview, see Projects.

Create a Project

Creates a project in the specified database. The example below creates a project of type graphrag, the type used by the Importer, AutoGraph, and AutoRAG services:

curl -X POST https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/project \
  -H "Authorization: Bearer <your-bearer-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "docs",
    "project_type": "graphrag",
    "project_db_name": "documentation",
    "project_description": "A documentation project."
  }'

Where:

• project_name (required): Unique identifier for your project. Must be 1-63 characters and contain only letters, numbers, underscores (_), and hyphens (-).
• project_type (required): Type of project (for example, "graphrag").
• project_db_name (required): The ArangoDB database name where the project will be created.
• project_description (optional): A description of your project.

Once created, you can reference the project when you deploy a service. See Projects for how the project name is used.

List Project Names

Lists all project names in a database. This returns only the project names for quick reference.

Path parameters:

curl -X GET https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/all_project_names/<project_db_name> \
  -H "Authorization: Bearer <your-bearer-token>"

List Projects

Lists all projects with full metadata in a database. This returns complete project objects including metadata, associated services, and knowledge graph information.

Path parameters:

curl -X GET https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/all_projects/<project_db_name> \
  -H "Authorization: Bearer <your-bearer-token>"

Get Project Details

Retrieves comprehensive metadata for a specific project.

Path parameters:

curl -X GET https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/project_by_name/<project_db_name>/<project_name> \
  -H "Authorization: Bearer <your-bearer-token>"

The response includes:

• Project configuration
• Associated Importer and AutoRAG services
• Knowledge graph metadata
• Service status information
• Last modification timestamp

Delete a Project

Deletes a project. The project record is removed entirely; only the external resources it referenced (services, collections, graphs) remain.

Path parameters:

curl -X DELETE https://<EXTERNAL_ENDPOINT>:8529/_platform/acp/v1/project/<project_db_name>/<project_name> \
  -H "Authorization: Bearer <your-bearer-token>"