ArangoDB v4.x is under development and not released yet.

This documentation is not final and potentially incomplete.

Administration HTTP API

You can get information about ArangoDB servers, toggle the maintenance mode, shut down server nodes, and start actions like compaction

Information

Get the server version

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/version

Returns the server name and version number.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.
Example: _system

Query Parameters

details boolean (default: false)
If set to true and if the user account you authenticate with has administrate access to the _system database, the response contains a details attribute with additional information about included components and their versions. The attribute names and internals of the details object may vary depending on platform and ArangoDB version.

HTTP Headers

Responses

200 OK
is returned in all cases.
- apiVersions array of strings
  Possible values in the array: "v1"
  The available versions of the HTTP API.
- deprecatedApiVersions array of strings
  Possible values in the array: (none)
  The versions of the HTTP API that are still supported by this ArangoDB server version but should no longer be used because of their pending removal in the next major version.
- details object, optional
  An object with additional details like compile flags, dependency versions, and so on.
  Only returned if the details query parameter is set to true in the request.
  architecture string
  The value is always: "64bit"
  The CPU architecture in terms of bitness.
  arm string
  Possible values: "true", "false"
  Whether the server binary has been compiled for an ARM CPU.
  asan string
  Possible values: "true", "false"
  Whether the server has been compiled with the ASAN address sanitizer enabled.
  assertions string
  Possible values: "true", "false"
  Whether the server has assertions compiled in (only in development builds).
  avx string
  Possible values: "true", "false"
  Whether the server binary has been compiled with AVX instruction support.
  avx2 string
  Possible values: "true", "false"
  Whether the server binary has been compiled with AVX2 instruction support.
  boost-version string
  Which version of the Boost library is used.
  build-date string
  The date when this binary was created.
  build-id string, optional
  The Git commit hash this was compiled from.
  build-repository string, optional
  Reference to the Git ID this was compiled from.
  compiler string
  The compiler that has been used.
  coverage string
  Possible values: "true", "false"
  Whether this build has code coverage instrumentation.
  cplusplus string
  The C++ standards version.
  curl-version string
  The linked cURL version, or "none" if not linked.
  debug string
  Possible values: "true", "false"
  Whether this is a debug build, "false" for production binaries.
  endianness string
  The value is always: "little"
  The byte order of the system, detected at runtime.
  enterprise-build-repository string, optional
  Reference to the enterprise Git ID this was compiled from.
  enterprise-version string, optional
  The value is always: "enterprise"
  Only present if this is a build that includes the non-public enterprise code.
  failure-tests string
  Possible values: "true", "false"
  Whether the facility to invoke fatal errors is compiled in, "false" for production binaries.
  faiss string
  The FAISS library version, if linked.
  fd-client-event-handler string
  Which method is used to handle fd-sets, typically poll on Linux.
  fd-setsize string
  If not poll, the fd setsize is valid for the maximum number of file descriptors.
  full-version-string string
  The full version string including the build ID and the versions of major dependencies.
  host string
  The host ID.
  icu-version string
  The version of the bundled ICU library.
  ipo string
  Possible values: "true", "false"
  Whether interprocedural optimization was enabled.
  iresearch-version string
  The ArangoSearch/IResearch library version.
  jemalloc string
  Possible values: "true", "false"
  Whether the jemalloc memory allocator is used, typically "true"
  libunwind string
  Whether libunwind is linked for stack unwinding.
  license string
  Possible values: "community", "enterprise"
  Whether this build of ArangoDB includes the non-public enterprise code. Reports "enterprise" for both the Community Edition and Enterprise Edition if you use the prepackaged binaries or official container images.
  maintainer-mode string
  Possible values: "true", "false"
  Whether the server has been compiled in maintainer mode, "false" for production binaries.
  memory-profiler string
  Possible values: "true", "false"
  Whether the memory profiler is enabled.
  ndebug string
  Possible values: "true", "false"
  Whether NDEBUG was defined for the build.
  openmp string
  The OpenMP version used for parallelization.
  openssl-version-compile-time string
  The OpenSSL version at compile time.
  openssl-version-run-time string
  The OpenSSL version at run time.
  optimization-flags string, optional
  The compiler optimization flags used for this build.
  oskar-build-repository string, optional
  Reference to the Git ID of the build environment this was compiled with.
  pic string
  The position-independent code setting.
  pie string
  The position-independent executable setting.
  platform string
  The value is always: "linux"
  The operating system the server has been compiled for.
  reactor-type string
  The value is always: "epoll"
  replication2-enabled string
  Possible values: "true", "false"
  Whether replication2 is enabled.
  rocksdb-version string
  The rocksdb version this release bundles.
  role string
  Possible values: "SINGLE", "PRIMARY", "COORDINATOR", "AGENT"
  The server role.
  "SINGLE": Standalone single server
  "PRIMARY": DB-Server of a cluster
  "COORDINATOR": Coordinator of a cluster
  "AGENT": Part of the cluster’s Agency
  server-version string
  The ArangoDB release version.
  sizeof int string
  Number of bytes for integers.
  sizeof long string
  Number of bytes for long integers.
  sizeof void* string
  Number of bytes for void pointers.
  sse42 string
  Whether the server binary has been compiled with SSE 4.2 instruction support.
  tsan string
  Possible values: "true", "false"
  Whether this was compiled with the thread sanitizer.
  unaligned-access string
  Possible values: "true", "false"
  Whether this system supports unaligned memory accesses.
  v8-version string
  The value is always: "none"
  The bundled V8 JavaScript engine version. V8 is not embedded in arangod anymore since ArangoDB v4.0.
  vpack-version string
  The version of the used VelocyPack implementation.
  zlib-version string
  The version of the bundled zlib compression library.
- license string
  Possible values: "community", "enterprise"
  Whether this build of ArangoDB includes the non-public enterprise code. Reports "enterprise" for both the Community Edition and Enterprise Edition if you use the prepackaged binaries or official container images.
- requestedApiVersion string
  Possible values: "v1"
  The HTTP API version specified for this request via the /_arango/{api-version} prefix, or the default API version if not specified.
- server string
  The value is always: "arango"
- version string
  The server version string in the format major.minor.sub (e.g. 3.12.11). The major and minor parts are numeric, and sub is a number that may have a version suffix starting with a hyphen minus (e.g. 3.11.14-5 or 4.0.0-devel).

Examples

Return the version information

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/version

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 78
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "server" : "arango", 
  "license" : "enterprise", 
  "version" : "3.12.0-nightly.20240305" 
}

Return the version information with details

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/version?details=true

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 1689
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "server" : "arango", 
  "license" : "enterprise", 
  "version" : "3.12.0-nightly.20240305", 
  "details" : { 
    "architecture" : "64bit", 
    "arm" : "false", 
    "asan" : "false", 
    "assertions" : "false", 
    "avx" : "true", 
    "avx2" : "false", 
    "boost-version" : "1.78.0", 
    "build-date" : "OFF", 
    "build-id" : "944ae87f180ccec0fabe78f549bf43202100e001", 
    "build-repository" : "refs/head/3.12 9b0f5c5d58c", 
    "compiler" : "clang [Ubuntu Clang 16.0.6 (15)]", 
    "coverage" : "false", 
    "cplusplus" : "202002", 
    "curl-version" : "none", 
    "debug" : "false", 
    "endianness" : "little", 
    "enterprise-build-repository" : "refs/head/3.12 734205bb", 
    "enterprise-version" : "enterprise", 
    "failure-tests" : "false", 
    "fd-client-event-handler" : "poll", 
    "fd-setsize" : "1024", 
    "full-version-string" : "ArangoDB 3.12.0-nightly.20240305 enterprise [linux] 64bit, using jemalloc, build refs/head/3.12 9b0f5c5d58c, VPack 0.2.1, RocksDB 7.2.0, ICU 73.1, V8 12.1.165, OpenSSL 3.2.1 30 Jan 2024", 
    "icu-version" : "73.1", 
    "ipo" : "true", 
    "iresearch-version" : "1.3.0.0", 
    "jemalloc" : "true", 
    "libunwind" : "true", 
    "license" : "enterprise", 
    "maintainer-mode" : "false", 
    "memory-profiler" : "true", 
    "ndebug" : "true", 
    "openssl-version-compile-time" : "OpenSSL 3.2.1 30 Jan 2024", 
    "openssl-version-run-time" : "OpenSSL 3.2.1 30 Jan 2024", 
    "optimization-flags" : "-mfxsr -mmmx -msse -msse2 -mcx16 -msahf -mpopcnt -msse3 -msse4.1 -msse4.2 -mssse3 -mpclmul -mavx -mxsave", 
    "pic" : "2", 
    "pie" : "2", 
    "platform" : "linux", 
    "reactor-type" : "epoll", 
    "replication2-enabled" : "false", 
    "rocksdb-version" : "7.2.0", 
    "server-version" : "3.12.0-nightly.20240305", 
    "sizeof int" : "4", 
    "sizeof long" : "8", 
    "sizeof void*" : "8", 
    "sse42" : "true", 
    "tsan" : "false", 
    "unaligned-access" : "false", 
    "v8-version" : "12.1.165", 
    "vpack-version" : "0.2.1", 
    "zlib-version" : "1.2.13", 
    "mode" : "server", 
    "role" : "SINGLE", 
    "host" : "localhost" 
  } 
}

Get the storage engine type

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/engine

Returns the name of the storage engine the server is configured to use, the endianness of its on-disk key format, as well as the index types it supports.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
Successfully retrieved the storage engine information.
- endianness string
  Possible values: "little", "big"
  The endianness of the key format the storage engine uses on disk.
- name string
  The value is always: "rocksdb"
  The name of the storage engine.
- supports object
  An object describing what the storage engine supports.
  aliases object
  An object describing the alternative names you can use for certain index types.
  indexes object
  The keys are the alternative index type names and the values are the index types they refer to.
  zkd string
  The value is always: "mdi"
  The zkd index type is an alias for mdi.
  indexes array of strings
  Possible values in the array: "primary", "edge", "ttl", "persistent", "geo", "mdi", "mdi-prefixed", "inverted", "vector"
  A list of the index types you can use.
401 Unauthorized
Missing read access to the given database.
- code integer
  The HTTP response status code.
  Example: 401
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Examples

Return the active storage engine:

curl --header 'accept: application/json' --dump - http://localhost:8529/_api/engine

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 245
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "name" : "rocksdb", 
  "supports" : { 
    "indexes" : [ 
      "primary", 
      "edge", 
      "hash", 
      "skiplist", 
      "ttl", 
      "persistent", 
      "geo", 
      "fulltext", 
      "mdi", 
      "mdi-prefixed", 
      "inverted" 
    ], 
    "aliases" : { 
      "indexes" : { 
        "hash" : "persistent", 
        "skiplist" : "persistent", 
        "zkd" : "mdi" 
      } 
    } 
  }, 
  "endianness" : "big" 
}

Get the storage engine statistics

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/engine/stats

Returns detailed statistics related to the RocksDB storage engine activity, including figures about data size, cache usage, individual column families, etc.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database. If the --server.harden startup option is enabled, administrate access to the _system database is required.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
Successfully retrieved the storage engine statistics.
401 Unauthorized
The user account you authenticated with lacks read access to the specified database, the credentials are wrong, or the user account is inactive.
- code integer
  The HTTP response status code.
  Example: 401
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
403 Forbidden
The --server.harden startup option is enabled but the user account you authenticated with lacks write access to the _system database.
- code integer
  The HTTP response status code.
  Example: 403
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Get the system time

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/time

The call returns an object with the time attribute. This contains the current system time as a Unix timestamp with microsecond precision.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
Time was returned successfully.
- code integer
  The HTTP response status code.
  Example: 200
- error boolean
  A flag indicating that no error occurred.
  Example: false
- time number
  The current system time as a Unix timestamp with microsecond precision of the server

Get server status information

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/status

Returns status information about the server.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database. If the --server.harden startup option is enabled, administrate access to the _system database is required.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
Status information was returned successfully.
- agency object, optional
  Information about the Agency. Cluster only (Coordinators and DB-Servers).
  agencyComm object
  Information about the communication with the Agency. Cluster only (Coordinators and DB-Servers).
  endpoints array of strings
  A list of possible Agency endpoints.
- agent object, optional
  Information about the Agents. Cluster only (Agents)
  endpoint string
  The endpoint of the queried Agent.
  id string
  Server ID of the queried Agent.
  leaderId string
  Server ID of the leading Agent.
  leading boolean
  Whether the queried Agent is the leader.
  term number
  The current term number.
- host string
  A host identifier defined by the HOST or NODE_NAME environment variable, or a fallback value using a machine identifier or the cluster/Agency address.
- hostname string, optional
  A hostname defined by the HOSTNAME environment variable.
- license string
  ArangoDB Edition, either "community" or "enterprise".
- pid number
  The process ID of arangod.
- server string
  The value is always: "arango"
- serverInfo object
  Information about the server status.
  address string, optional
  The address of the server, e.g. tcp://[::1]:8530. Cluster only (Coordinators and DB-Servers).
  maintenance boolean
  Whether the maintenance mode is enabled.
  persistedId string, optional
  The persisted ID, e. g. "CRDN-e427b441-5087-4a9a-9983-2fb1682f3e2a". Cluster only (Agents, Coordinators, and DB-Servers).
  progress object
  Startup and recovery information.
  You can check for changes to determine whether progress was made between two calls, but you should not rely on specific values as they may change between ArangoDB versions. The values are only expected to change during the startup and shutdown, i.e. while maintenance is true.
  You need to start arangod with the --server.early-connections startup option enabled to be able to query the endpoint during the startup process. If authentication is enabled, then you need to use the super-user JWT for the request because the user management is not available during the startup.
  feature string
  Internal name of the feature that is currently being prepared, started, stopped or unprepared.
  phase string
  Name of the lifecycle phase the instance is currently in. Normally one of "in prepare", "in start", "in wait", "in shutdown", "in stop", or "in unprepare".
  recoveryTick number
  Current recovery sequence number value, if the instance is currently recovering. If the instance is already past the recovery, this attribute will contain the last handled recovery sequence number.
  readOnly boolean
  Whether writes are disabled.
  rebootId number, optional
  The reboot ID. Changes on every restart. Cluster only (Agents, Coordinators, and DB-Servers).
  role string
  Either "SINGLE", "COORDINATOR", "PRIMARY" (DB-Server), or "AGENT".
  serverId string, optional
  The server ID, e.g. "CRDN-e427b441-5087-4a9a-9983-2fb1682f3e2a". Cluster only (Coordinators and DB-Servers).
  state string, optional
  Either "STARTUP", "SERVING", or "SHUTDOWN". Cluster only (Coordinators and DB-Servers).
- version string
  The server version as a string.

Examples

curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/status

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 726
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "server" : "arango", 
  "version" : "3.12.0-nightly.20240305", 
  "pid" : 230, 
  "license" : "enterprise", 
  "mode" : "server", 
  "operationMode" : "server", 
  "foxxApi" : true, 
  "host" : "localhost", 
  "hostname" : "b375e6be5d10", 
  "serverInfo" : { 
    "progress" : { 
      "phase" : "in wait", 
      "feature" : "", 
      "recoveryTick" : 0 
    }, 
    "maintenance" : false, 
    "role" : "COORDINATOR", 
    "writeOpsEnabled" : true, 
    "readOnly" : false, 
    "persistedId" : "CRDN-085d1776-5a95-496c-9b09-7382e9db7327", 
    "rebootId" : 1, 
    "address" : "tcp://localhost:8529", 
    "serverId" : "CRDN-085d1776-5a95-496c-9b09-7382e9db7327", 
    "state" : "SERVING" 
  }, 
  "coordinator" : { 
    "foxxmaster" : "CRDN-7c96e96b-2f14-42ca-98d7-5595548c4649", 
    "isFoxxmaster" : false 
  }, 
  "agency" : { 
    "agencyComm" : { 
      "endpoints" : [ 
        "tcp://localhost:8541", 
        "tcp://localhost:8551", 
        "tcp://localhost:8531" 
      ] 
    } 
  } 
}

Return whether or not a server is available

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_admin/server/availability

Return availability information about a server.

The response is a JSON object with an attribute “mode”. The “mode” can either be “readonly”, if the server is in read-only mode, or “default”, if it is not. Please note that the JSON object with “mode” is only returned in case the server does not respond with HTTP response code 503.

This is a public API so it does not require authentication. It is meant to be used only in the context of server monitoring.

Responses

200 OK
This API will return HTTP 200 in case the server is up and running and usable for arbitrary operations, is not set to read-only mode.
503 Service Unavailable
HTTP 503 will be returned during startup and shutdown, and in case the server is set to read-only mode.
In addition, HTTP 503 will be returned in case the fill grade of the scheduler queue exceeds the configured high-water mark (adjustable via startup option --server.unavailability-queue-fill-grade), which by default is set to 75 % of the maximum queue length.

Get information about the deployment

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/_system/_admin/support-info

Retrieves deployment information for support purposes. The endpoint returns data about the ArangoDB version used, the host (operating system, server ID, CPU and storage capacity, current utilization, a few metrics) and the other servers in the deployment (in case of cluster deployments).

As this API may reveal sensitive data about the deployment, it can only be accessed from inside the _system database. In addition, there is a policy control startup option --server.support-info-api that controls if and to whom the API is made available.

Responses

200 OK
- date string
  ISO 8601 datetime string of when the information was requested.
- deployment object
  An object with at least a type attribute, indicating the deployment mode.
  In case of a "single" server, additional information is provided in the top-level host attribute.
  In case of a "cluster", there is a servers object that contains a nested object for each Coordinator and DB-Server, using the server ID as key. Each object holds information about the ArangoDB instance as well as the host machine. There are additional attributes for the number of agents, coordinators, dbServers, and shards.
- host object, optional
  An object that holds information about the ArangoDB instance as well as the host machine. Only set in case of single servers.
404 Not Found
The support info API is turned off.

Examples

Query support information from a single server

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_db/_system/_admin/support-info'

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 1200
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "deployment" : { 
    "type" : "single" 
  }, 
  "host" : { 
    "role" : "SINGLE", 
    "maintenance" : false, 
    "readOnly" : false, 
    "version" : "3.12.5-nightly.20250419", 
    "build" : "refs/head/3.12 2624a86a2e6", 
    "license" : "enterprise", 
    "os" : "Linux version 6.8.0-1019-aws (buildd@lcy02-amd64-058) (x86_64-linux-gnu-gcc-12 (Ubuntu 12.3.0-1ubuntu1~22.04) 12.3.0, GNU ld (GNU Binutils for Ubuntu) 2.38) #21~22.04.1-Ubuntu SMP Thu Nov  7 17:33:30 UTC 2024", 
    "platform" : "linux", 
    "physicalMemory" : { 
      "value" : 33089757184, 
      "overridden" : false 
    }, 
    "numberOfCores" : { 
      "value" : 8, 
      "overridden" : false 
    }, 
    "processStats" : { 
      "processUptime" : 171.0257532596588, 
      "numberOfThreads" : 72, 
      "virtualSize" : 2574700544, 
      "residentSetSize" : 238465024, 
      "fileDescrtors" : 29, 
      "fileDescrtorsLimit" : 1048576 
    }, 
    "cpuStats" : { 
      "userPercent" : 14.020245071923283, 
      "systemPercent" : 7.037187000532765, 
      "idlePercent" : 75.82567927543953, 
      "iowaitPercent" : 2.7980820458177944 
    }, 
    "engineStats" : { 
      "cache.limit" : 7735568384, 
      "cache.allocated" : 1281056, 
      "rocksdb.estimate-num-keys" : 1654, 
      "rocksdb.estimate-live-data-size" : 0, 
      "rocksdb.live-sst-files-size" : 0, 
      "rocksdb.block-cache-capacity" : 9282682060, 
      "rocksdb.block-cache-usage" : 96, 
      "rocksdb.free-disk-space" : 135842553856, 
      "rocksdb.total-disk-space" : 155897610240 
    } 
  }, 
  "date" : "2025-04-25T14:55:31Z" 
}

Query support information from a cluster

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_db/_system/_admin/support-info'

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 6980
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "deployment" : { 
    "type" : "cluster", 
    "servers" : { 
      "CRDN-a6266e75-0d92-4cff-9fe1-8a15761f64e5" : { 
        "id" : "CRDN-a6266e75-0d92-4cff-9fe1-8a15761f64e5", 
        "alias" : "Coordinator0002", 
        "endpoint" : "tcp://localhost:8529", 
        "role" : "COORDINATOR", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.5-nightly.20250419", 
        "build" : "refs/head/3.12 2624a86a2e6", 
        "license" : "enterprise", 
        "os" : "Linux version 6.8.0-1019-aws (buildd@lcy02-amd64-058) (x86_64-linux-gnu-gcc-12 (Ubuntu 12.3.0-1ubuntu1~22.04) 12.3.0, GNU ld (GNU Binutils for Ubuntu) 2.38) #21~22.04.1-Ubuntu SMP Thu Nov  7 17:33:30 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33089757184, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 170.92322444915771, 
          "numberOfThreads" : 48, 
          "virtualSize" : 2240577536, 
          "residentSetSize" : 126996480, 
          "fileDescrtors" : 42, 
          "fileDescrtorsLimit" : 1048576 
        }, 
        "cpuStats" : { 
          "userPercent" : 14.034408199400708, 
          "systemPercent" : 7.042529283573958, 
          "idlePercent" : 75.79848815036775, 
          "iowaitPercent" : 2.8057749931898663 
        } 
      }, 
      "CRDN-c0f10e91-835d-45f7-aeca-d782bb65e1ab" : { 
        "id" : "CRDN-c0f10e91-835d-45f7-aeca-d782bb65e1ab", 
        "alias" : "Coordinator0003", 
        "endpoint" : "tcp://localhost:8549", 
        "role" : "COORDINATOR", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.5-nightly.20250419", 
        "build" : "refs/head/3.12 2624a86a2e6", 
        "license" : "enterprise", 
        "os" : "Linux version 6.8.0-1019-aws (buildd@lcy02-amd64-058) (x86_64-linux-gnu-gcc-12 (Ubuntu 12.3.0-1ubuntu1~22.04) 12.3.0, GNU ld (GNU Binutils for Ubuntu) 2.38) #21~22.04.1-Ubuntu SMP Thu Nov  7 17:33:30 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33089757184, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 171.83917713165283, 
          "numberOfThreads" : 48, 
          "virtualSize" : 2247917568, 
          "residentSetSize" : 125345792, 
          "fileDescrtors" : 40, 
          "fileDescrtorsLimit" : 1048576 
        }, 
        "cpuStats" : { 
          "userPercent" : 14.034774096065037, 
          "systemPercent" : 7.042499308348763, 
          "idlePercent" : 75.79816552810232, 
          "iowaitPercent" : 2.8057630509268128 
        } 
      }, 
      "PRMR-39e7f402-a7d3-4a45-bed0-6942368b7e29" : { 
        "id" : "PRMR-39e7f402-a7d3-4a45-bed0-6942368b7e29", 
        "alias" : "DBServer0002", 
        "endpoint" : "tcp://localhost:8540", 
        "role" : "PRIMARY", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.5-nightly.20250419", 
        "build" : "refs/head/3.12 2624a86a2e6", 
        "license" : "enterprise", 
        "os" : "Linux version 6.8.0-1019-aws (buildd@lcy02-amd64-058) (x86_64-linux-gnu-gcc-12 (Ubuntu 12.3.0-1ubuntu1~22.04) 12.3.0, GNU ld (GNU Binutils for Ubuntu) 2.38) #21~22.04.1-Ubuntu SMP Thu Nov  7 17:33:30 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33089757184, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 171.8409948348999, 
          "numberOfThreads" : 77, 
          "virtualSize" : 2089103360, 
          "residentSetSize" : 177307648, 
          "fileDescrtors" : 62, 
          "fileDescrtorsLimit" : 1048576 
        }, 
        "cpuStats" : { 
          "userPercent" : 14.034714359895466, 
          "systemPercent" : 7.042894963097903, 
          "idlePercent" : 75.79784290858325, 
          "iowaitPercent" : 2.8057511087654183 
        }, 
        "engineStats" : { 
          "cache.limit" : 7735568384, 
          "cache.allocated" : 1082864, 
          "rocksdb.estimate-num-keys" : 574, 
          "rocksdb.estimate-live-data-size" : 0, 
          "rocksdb.live-sst-files-size" : 0, 
          "rocksdb.block-cache-capacity" : 9282682060, 
          "rocksdb.block-cache-usage" : 96, 
          "rocksdb.free-disk-space" : 135842390016, 
          "rocksdb.total-disk-space" : 155897610240 
        } 
      }, 
      "PRMR-53e7543a-e342-45dd-8541-cd9876a525e3" : { 
        "id" : "PRMR-53e7543a-e342-45dd-8541-cd9876a525e3", 
        "alias" : "DBServer0001", 
        "endpoint" : "tcp://localhost:8550", 
        "role" : "PRIMARY", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.5-nightly.20250419", 
        "build" : "refs/head/3.12 2624a86a2e6", 
        "license" : "enterprise", 
        "os" : "Linux version 6.8.0-1019-aws (buildd@lcy02-amd64-058) (x86_64-linux-gnu-gcc-12 (Ubuntu 12.3.0-1ubuntu1~22.04) 12.3.0, GNU ld (GNU Binutils for Ubuntu) 2.38) #21~22.04.1-Ubuntu SMP Thu Nov  7 17:33:30 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33089757184, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 172.85408926010132, 
          "numberOfThreads" : 77, 
          "virtualSize" : 2067083264, 
          "residentSetSize" : 172011520, 
          "fileDescrtors" : 58, 
          "fileDescrtorsLimit" : 1048576 
        }, 
        "cpuStats" : { 
          "userPercent" : 14.034774096065037, 
          "systemPercent" : 7.042499308348763, 
          "idlePercent" : 75.79816552810232, 
          "iowaitPercent" : 2.8057630509268128 
        }, 
        "engineStats" : { 
          "cache.limit" : 7735568384, 
          "cache.allocated" : 1082864, 
          "rocksdb.estimate-num-keys" : 59, 
          "rocksdb.estimate-live-data-size" : 0, 
          "rocksdb.live-sst-files-size" : 0, 
          "rocksdb.block-cache-capacity" : 9282682060, 
          "rocksdb.block-cache-usage" : 96, 
          "rocksdb.free-disk-space" : 135842390016, 
          "rocksdb.total-disk-space" : 155897610240 
        } 
      }, 
      "PRMR-36a49129-c2b9-4f2c-b0e8-1ae45bbd925b" : { 
        "id" : "PRMR-36a49129-c2b9-4f2c-b0e8-1ae45bbd925b", 
        "alias" : "DBServer0003", 
        "endpoint" : "tcp://localhost:8530", 
        "role" : "PRIMARY", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.5-nightly.20250419", 
        "build" : "refs/head/3.12 2624a86a2e6", 
        "license" : "enterprise", 
        "os" : "Linux version 6.8.0-1019-aws (buildd@lcy02-amd64-058) (x86_64-linux-gnu-gcc-12 (Ubuntu 12.3.0-1ubuntu1~22.04) 12.3.0, GNU ld (GNU Binutils for Ubuntu) 2.38) #21~22.04.1-Ubuntu SMP Thu Nov  7 17:33:30 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33089757184, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 171.94052696228027, 
          "numberOfThreads" : 77, 
          "virtualSize" : 2072326144, 
          "residentSetSize" : 174235648, 
          "fileDescrtors" : 62, 
          "fileDescrtorsLimit" : 1048576 
        }, 
        "cpuStats" : { 
          "userPercent" : 14.034774096065037, 
          "systemPercent" : 7.042499308348763, 
          "idlePercent" : 75.79816552810232, 
          "iowaitPercent" : 2.8057630509268128 
        }, 
        "engineStats" : { 
          "cache.limit" : 7735568384, 
          "cache.allocated" : 1082864, 
          "rocksdb.estimate-num-keys" : 506, 
          "rocksdb.estimate-live-data-size" : 0, 
          "rocksdb.live-sst-files-size" : 0, 
          "rocksdb.block-cache-capacity" : 9282682060, 
          "rocksdb.block-cache-usage" : 96, 
          "rocksdb.free-disk-space" : 135842390016, 
          "rocksdb.total-disk-space" : 155897610240 
        } 
      }, 
      "CRDN-771dff78-4131-450a-a428-5ac6dd855a5f" : { 
        "id" : "CRDN-771dff78-4131-450a-a428-5ac6dd855a5f", 
        "alias" : "Coordinator0001", 
        "endpoint" : "tcp://localhost:8539", 
        "role" : "COORDINATOR", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.5-nightly.20250419", 
        "build" : "refs/head/3.12 2624a86a2e6", 
        "license" : "enterprise", 
        "os" : "Linux version 6.8.0-1019-aws (buildd@lcy02-amd64-058) (x86_64-linux-gnu-gcc-12 (Ubuntu 12.3.0-1ubuntu1~22.04) 12.3.0, GNU ld (GNU Binutils for Ubuntu) 2.38) #21~22.04.1-Ubuntu SMP Thu Nov  7 17:33:30 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33089757184, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 170.8470380306244, 
          "numberOfThreads" : 48, 
          "virtualSize" : 2235072512, 
          "residentSetSize" : 126971904, 
          "fileDescrtors" : 40, 
          "fileDescrtorsLimit" : 1048576 
        }, 
        "cpuStats" : { 
          "userPercent" : 14.034774096065037, 
          "systemPercent" : 7.042499308348763, 
          "idlePercent" : 75.79816552810232, 
          "iowaitPercent" : 2.8057630509268128 
        } 
      } 
    }, 
    "agents" : 3, 
    "coordinators" : 3, 
    "dbServers" : 3, 
    "shards" : { 
      "databases" : 1, 
      "collections" : 16, 
      "shards" : 28, 
      "leaders" : 16, 
      "realLeaders" : 5, 
      "followers" : 12, 
      "servers" : 3 
    } 
  }, 
  "date" : "2025-04-25T14:55:32Z" 
}

Startup options

The permissions required to use the /_admin/options and /_admin/options-description endpoints depend on the setting of the --server.options-api startup option. The /_admin/options-public endpoint is always available to any authenticated user with read access to a database and is not affected by that setting.

Get the startup option configuration

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/_system/_admin/options

Return the effective configuration of the queried arangod instance as set by startup options on the command-line and via a configuration file.

This endpoint may reveal sensitive information about the deployment!

The endpoint can only be accessed via the _system database. In addition, the --server.options-api startup option controls the required privileges to access the option endpoints and allows you to disable them entirely. The option can have the following values:

disabled: This endpoint is disabled.
jwt: This endpoint can only be accessed using a superuser JWT (default).
admin: This endpoint can only be accessed by users with write access to the _system database.
public: Every user with read access to the _system database can access this endpoint.

Responses

200 OK
An object with startup option names as keys and their effective value as values. The values can be of different data types, typically numbers, strings, or arrays thereof.
401 Unauthorized
You tried to authenticate with user credentials but a superuser token created from the JWT secret is required (--server.options-api set to jwt), you lack read access to the _system database (--server.options-api set to public), the credentials are wrong, or the user account is inactive.
- code integer
  The HTTP response status code.
  Example: 401
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
403 Forbidden
You don’t have write access to the _system database (--server.options-api set to admin) or you tried to access the endpoint using a database other than _system.
- code integer
  The HTTP response status code.
  Example: 403
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
405 Method Not Allowed
Returned if the HTTP method is not GET.
- code integer
  The HTTP response status code.
  Example: 405
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Get the available startup options

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/_system/_admin/options-description

Return the startup options available to configure the queried arangod instance, similar to the --dump-options startup option.

disabled: This endpoint is disabled.
jwt: This endpoint can only be accessed using a superuser JWT (default).
admin: This endpoint can only be accessed by users with write access to the _system database.
public: Every user with read access to the _system database can access this endpoint.

Responses

200 OK
An object with startup option names as keys and sub-objects as values. The structure of each sub-object is as follows:
- section (string): The part before the dot of a startup option (--section.param), or "" if it is a general option that doesn’t belong to a section
- description (string): A succinct explanation of the startup option
- longDescription (string, optional): Additional details about the startup option if available
- category (string): Either "option" for regular options or "command" if using the option performs an action and then terminates the process
- hidden (boolean): Whether the option is uncommon. If yes, then the --help command does not list it, but --help-all lists every startup option
- type (string): the data type of the option, typically one of "uint64", "uint32", "int64", "int32", "double", "boolean", "string", "string..."
- experimental (boolean): Whether the option relates to a feature that is not ready for production yet
- obsolete (boolean): Whether the option has been deprecated and no effect anymore
- enterpriseOnly (boolean): Whether the option is implemented in the non-public enterprise code.
- requiresValue (boolean): Whether the option can be specified without a value to enable it
- os (array of strings): The operating systems the startup option is supported on, always ["linux"]
- component (array of strings): A list of server roles the startup option is available on. If it is supported by all cluster node types as well as the single server deployment mode, then the value is ["coordinator", "dbserver", "agent", "single"]
- introducedIn (array of strings|null): A list of versions the startup option has been added in. Does not include later minor and major versions then the current version, and the information may get removed once all listed versions reach their end of life
- deprecatedIn (array of strings|null): A list of versions the startup option has been marked for deprecation in. It can still be used until fully removed. Does not include later minor and major versions then the current version, and the information may get removed once all listed versions reach their end of life
- values (string, optional): A description of the possible values you can set
- default (any, optional): The standard value if the option is not set
- dynamic (boolean): Whether the default value is calculated based on the target host configuration, e.g. available memory
- required (boolean): Whether the option must be specified
- base (number, optional): the unit for a numeric option
- minValue (number, optional): The minimum value for a numeric option
- maxValue (number, optional): The maximum value for a numeric option
- minInclusive (boolean, optional): Whether the minimum value is included in the allowed value range
- maxInclusive (boolean, optional): Whether the maximum value is included in the allowed value range
401 Unauthorized
You tried to authenticate with user credentials but a superuser token is required, the credentials are wrong, or the user account is inactive.
- code integer
  The HTTP response status code.
  Example: 401
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
403 Forbidden
You don’t have write access to the _system database or you tried to access the endpoint using a database other than _system.
- code integer
  The HTTP response status code.
  Example: 403
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
405 Method Not Allowed
Returned if the HTTP method is not GET.
- code integer
  The HTTP response status code.
  Example: 405
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Get the public startup option configuration

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/options-public

Return a small, curated subset of the configured server startup options that are safe to expose to any authenticated user with read access to the requested database.

Administrative tools can use this endpoint to adapt their behavior to the server configuration. For example, they can show the valid range for replicationFactor when creating a collection, or respect --database.extended-names when validating names on the client-side.

This endpoint is available regardless of the --server.options-api startup option setting, so that the Arango Contextual Data Platform web interface for instance can always access the public options.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
An object with public startup option names as keys and their effective values.
- cluster.api-jwt-policy string
  The permissions required for accessing /_admin/cluster/* endpoints.
- cluster.max-number-of-shards integer
  Maximum number of shards per collection.
- cluster.max-replication-factor integer
  Maximum replication factor for collections.
- cluster.min-replication-factor integer
  Minimum replication factor for collections.
- database.extended-names boolean
  Whether the traditional or extended naming constraints apply for collections, Views, etc.
- server.session-timeout number
  The timeout for JWT session tokens in seconds.
401 Unauthorized
Authentication is enabled and the user account you authenticated with doesn’t have at least read access to the specified database, the credentials are wrong, or the user account is inactive.
- code integer
  The HTTP response status code.
  Example: 401
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
405 Method Not Allowed
Returned if the HTTP method is not GET.
- code integer
  The HTTP response status code.
  Example: 405
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Server mode

Return whether or not a server is in read-only mode

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/server/mode

Return mode information about a server. The json response will contain a field mode with the value readonly or default. In a read-only server all write operations will fail with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping of databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).

This API requires authentication.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
This API will return HTTP 200 if everything is ok

Set the server mode to read-only or default

PUT http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/server/mode

Update mode information about a server. The JSON response will contain a field mode with the value readonly or default. In a read-only server all write operations will fail with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping of databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).

This is a protected API. It requires authentication and administrative server rights.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
Example: _system

Query Parameters

HTTP Headers

Request Body application/json object

mode string, required
The mode of the server readonly or default.

Responses

200 OK
This API will return HTTP 200 if everything is ok
401 Unauthorized
if the request was not authenticated as a user with sufficient rights

License

The endpoints for license management allow you to view the current license status and update the license of your ArangoDB Enterprise Edition deployment.

Get information about the current license

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/license

View the license information and status of the ArangoDB deployment.

Can be called on single servers, Coordinators, and DB-Servers.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database. If the --server.harden startup option is enabled, administrate access to the _system database is required.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
Returns the license information.
- diskUsage object, optional
  Information about the dataset size limit if you use the Community Edition.
  This attribute is not present if an Enterprise Edition license is applied.
  bytesLimit integer
  The maximum dataset size for your Community Edition deployment.
  bytesUsed integer
  The determined dataset size of your deployment.
  limitReached boolean
  Whether the dataset size exceeds the limit.
  secondsUntilReadOnly integer
  The time until read-only mode is entered if you are over the limit.
  secondsUntilShutDown integer
  The time until shutdown if you are over the limit.
  status string
  Possible values: "good", "limit-reached", "read-only", "shutdown"
  The state of your Community Edition deployment with regard to the dataset size limit at a glance.
  good: The dataset size of your deployment is below the 100 GiB limit.
  limit-reached: Your deployment exceeds the size limit and you have two days to bring the deployment back below 100 GiB. Consider acquiring an Enterprise Edition license to lift the limit.
  read-only: Your deployment is in read-only mode because it exceeded the size limit for two days. All read operations to the instance keep functioning for two more days. However, no data or data definition changes can be made.
  shutdown: The server shuts down after two days of read-only mode.
- features object, optional
  The properties of the license.
  This attribute is only present if an Enterprise Edition license is applied.
  expires number
  The expires key lists the expiry date as Unix timestamp (seconds since January 1st, 1970 UTC).
  Example: 1683173040
- hash string, optional
  The hash value of the license.
  This attribute is only present if an Enterprise Edition license is applied.
  Example: "982db5...44f3"
- license string, optional
  The encrypted license key in Base64 encoding.
  This attribute is only present if an Enterprise Edition license is applied.
  Example: "V0h/W...wEDw=="
- status string, optional
  Possible values: "good", "expiring", "read-only"
  The status attribute allows you to confirm the state of the applied license at a glance.
  good: The license is still valid for more than a week.
  expiring: The license is valid for less than a week. This status is not applicable if you use license activation (managed license, from v3.12.6 onward) rather than a license key, in which case the transition is directly from good to read-only when the activation expires.
  read-only: The license has expired. The instance is now restricted to read-only mode.
  This attribute is only present if an Enterprise Edition license is applied.
  Example: "good"
- upgrading boolean
  Whether the server is performing a database upgrade.
  Example: false
- version number, optional
  The license version number.
  This attribute is only present if an Enterprise Edition license is applied.
  Example: 1

Examples

curl --header 'accept: application/json' --dump - 'http://localhost:8529/_admin/license'

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 181
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "upgrading" : false, 
  "diskUsage" : { 
    "bytesUsed" : 263017, 
    "bytesLimit" : 107374182400, 
    "limitReached" : false, 
    "secondsUntilReadOnly" : 315569520, 
    "secondsUntilShutDown" : 315569520, 
    "status" : "good" 
  } 
}

Set a new license

PUT http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/license

Set a new license for an Enterprise Edition instance. Can be called on single servers, Coordinators, and DB-Servers.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database. If the --server.harden startup option is enabled, administrate access to the _system database is required.
Example: _system

Query Parameters

force boolean (default: false)
Whether to change the license even if it expires sooner than the current one.

HTTP Headers

Request Body application/json string

Example: "eyJncmFudCI6...(Base64-encoded license string)..."

Responses

201 Created
License successfully deployed.
- result object
  code integer
  The HTTP response status code.
  Example: 201
  error boolean
  A flag indicating that no error occurred.
  Example: false
400 Bad Request
If the license expires earlier than the previously installed one, or if the supplied license string is invalid.
- code integer
  The HTTP response status code.
  Example: 400
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
501 Not Implemented
If you try to apply a license using a custom build of the public source code.
- code integer
  The HTTP response status code.
  Example: 501
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Examples

curl --header 'accept: application/json' --dump - --data '"eyJncmFudCI6...(Base64-encoded license string)..."' -X PUT http://localhost:8529/_admin/license

Show output

HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 37
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{
  "result": {
    "error": false,
    "code": 201
  }
}

Get the deployment ID

Introduced in: v3.12.6

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/deployment/id

Get the unique identifier of this ArangoDB deployment.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
The deployment ID has been retrieved successfully.
- id string
  The UUID that uniquely identifies the deployment.
401 Unauthorized
The user account has insufficient permissions for the selected database.
- code integer
  The HTTP response status code.
  Example: 401
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Examples

curl --header 'accept: application/json' --dump - http://localhost:8529/_admin/deployment/id

Show output

HTTP/1.1 200 OK
X-Arango-Queue-Time-Seconds: 0.000000
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
Expires: 0
Pragma: no-cache
Cache-Control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
Content-Security-Policy: frame-ancestors 'self'; form-action 'self';
X-Content-Type-Options: nosniff
Server: ArangoDB
Connection: Keep-Alive
Content-Type: application/json; charset=utf-8
Content-Length: 45

{"id":"6172616e-676f-4000-0000-9396df268f7f"}

Crash dump management

List crash dumps

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/crashes

Introduced in: v3.12.8

Return the list of crash dump directory identifiers (UUIDs).

When the server crashes, the crash handler writes diagnostic data into a per-crash directory under <database-directory>/crashes/<uuid>/. Each dump includes information such as recent API calls and AQL queries, a backtrace, and system information.

The server keeps the most recent 10 crash dumps. Older ones are removed during startup.

This endpoint requires administrate access to the _system database.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and write access to the _system database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
Returns a list of crash dump identifiers (UUIDs).
- code integer
  Example: 200
- error boolean
  Example: false
- result array of strings
  Array of crash dump identifiers (UUIDs).
401 Unauthorized
Returned if authentication is enabled and the user does not have at least read access to the specified database, the credentials are wrong, or the user account is inactive.
- code integer
  The HTTP response status code.
  Example: 401
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
403 Forbidden
Returned if authentication is enabled and the user does not have write access to the _system database.
- code integer
  The HTTP response status code.
  Example: 403
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
503 Service Unavailable
The crash handler feature is not ready or has been disabled via the --crash-handler.enable-dumps startup option.
- code integer
  The HTTP response status code.
  Example: 503
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Get a crash dump

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/crashes/:crashId

Introduced in: v3.12.8

Return the contents of a specific crash dump. The response includes all files from the crash directory (e.g. backtrace.txt, system_info.txt, ApiRecording.json, AsyncRegistry.json) as an object mapping filenames to their contents. Crash dumps are stored under <database-directory>/crashes/<uuid>/.

This endpoint requires administrate access to the _system database.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and write access to the _system database.
Example: _system
crashId string
The UUID of the crash dump directory.

Query Parameters

HTTP Headers

Responses

200 OK
Returns the crash dump contents.
- code integer
  Example: 200
- error boolean
  Example: false
- result object
  crashId string
  The crash dump identifier (UUID).
  files object
  Object mapping file names to their contents (e.g. backtrace.txt, system_info.txt, ApiRecording.json, Activities.json, AsyncRegistry.json).
  Varying attribute names string
401 Unauthorized
Returned if authentication is enabled and the user does not have at least read access to the specified database, the credentials are wrong, or the user account is inactive.
- code integer
  The HTTP response status code.
  Example: 401
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
403 Forbidden
Returned if authentication is enabled and the user does not have write access to the _system database.
- code integer
  The HTTP response status code.
  Example: 403
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
404 Not Found
Returned if the crash dump folder based on the specified crashId cannot be found.
- code integer
  The HTTP response status code.
  Example: 404
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
503 Service Unavailable
The crash handler feature is not ready or has been disabled via the --crash-handler.enable-dumps startup option.
- code integer
  The HTTP response status code.
  Example: 503
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Delete a crash dump

DELETE http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/crashes/:crashId

Introduced in: v3.12.8

Delete a specific crash dump directory and its contents. Crash dumps are stored under <database-directory>/crashes/<uuid>/. The server keeps the most recent 10 crash dumps. Older ones are removed during startup.

This endpoint requires administrate access to the _system database.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and write access to the _system database.
Example: _system
crashId string
The UUID of the crash dump directory to delete.

Query Parameters

HTTP Headers

Responses

200 OK
The crash dump was deleted successfully.
- code integer
  Example: 200
- error boolean
  Example: false
- result object
  crashId string
  deleted boolean
  Example: true
401 Unauthorized
Returned if authentication is enabled and the user does not have at least read access to the specified database, the credentials are wrong, or the user account is inactive.
- code integer
  The HTTP response status code.
  Example: 401
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
403 Forbidden
Returned if authentication is enabled and the user does not have write access to the _system database.
- code integer
  The HTTP response status code.
  Example: 403
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
404 Not Found
Returned if the crash dump folder based on the specified crashId cannot be found.
- code integer
  The HTTP response status code.
  Example: 404
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.
503 Service Unavailable
The crash handler feature is not ready or has been disabled via the --crash-handler.enable-dumps startup option.
- code integer
  The HTTP response status code.
  Example: 503
- error boolean
  A flag indicating that an error occurred.
  Example: true
- errorMessage string
  A descriptive error message.
- errorNum integer
  The ArangoDB error number for the error that occurred.

Shutdown

Start the shutdown sequence

DELETE http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/shutdown

This call initiates a clean shutdown sequence. Requires administrative privileges.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
Example: _system

Query Parameters

soft boolean (default: false)
If set to true, this initiates a soft shutdown. This is only available on Coordinators. When issued, the Coordinator tracks a number of ongoing operations, waits until all have finished, and then shuts itself down normally. It will still accept new operations.
This feature can be used to make restart operations of Coordinators less intrusive for clients. It is designed for setups with a load balancer in front of Coordinators. Remove the designated Coordinator from the load balancer before issuing the soft-shutdown. The remaining Coordinators will internally forward requests that need to be handled by the designated Coordinator. All other requests will be handled by the remaining Coordinators, reducing the designated Coordinator’s load.
The following types of operations are tracked:
- AQL cursors (in particular streaming cursors)
- Transactions (in particular stream transactions)
- Ongoing asynchronous requests (using the x-arango-async: store HTTP header)
- Finished asynchronous requests, whose result has not yet been collected
- Queued low priority requests (most normal requests)
- Ongoing low priority requests

HTTP Headers

Responses

200 OK
is returned in all cases, OK will be returned in the result buffer on success.

Query the soft shutdown progress

GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_admin/shutdown

This call reports progress about a soft Coordinator shutdown (see documentation of DELETE /_admin/shutdown?soft=true). In this case, the following types of operations are tracked:

AQL cursors (in particular streaming cursors)
Transactions (in particular stream transactions)
Ongoing asynchronous requests (using the x-arango-async: store HTTP header)
Finished asynchronous requests, whose result has not yet been collected
Queued low priority requests (most normal requests)
Ongoing low priority requests

This API is only available on Coordinators.

Path Parameters

database-name string
The name of a database. Which database you use doesn’t matter as long as the user account you authenticate with has at least read access to this database and administrate access to the _system database.
Example: _system

Query Parameters

HTTP Headers

Responses

200 OK
The response indicates the fact that a soft shutdown is ongoing and the number of active operations of the various types. Once all numbers have gone to 0, the flag allClear is set and the Coordinator shuts down automatically.
- AQLcursors number
  Number of AQL cursors that are still active.
- allClear boolean
  Whether all active operations finished.
- doneJobs number
  Number of finished asynchronous requests, whose result has not yet been collected.
- lowPrioOngoingRequests number
  Number of queued low priority requests.
- lowPrioQueuedRequests number
  Number of ongoing low priority requests.
- pendingJobs number
  Number of ongoing asynchronous requests.
- softShutdownOngoing boolean
  Whether a soft shutdown of the Coordinator is in progress.
- transactions number
  Number of ongoing transactions.

Miscellaneous actions

Compact all databases

PUT http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_admin/compact

This command can cause a full rewrite of all data in all databases, which may take very long for large databases. It should thus only be used with care and only when additional I/O load can be tolerated for a prolonged time.

This endpoint can be used to reclaim disk space after substantial data deletions have taken place, by compacting the entire database system data.

The endpoint requires superuser access.

Request Body application/json object

changeLevel boolean (default: false)
whether or not compacted data should be moved to the minimum possible level.
compactBottomMostLevel boolean (default: false)
Whether or not to compact the bottommost level of data.

Responses

200 OK
Compaction started successfully
401 Unauthorized
if the request was not authenticated as a user with sufficient rights

Examples

curl -X PUT --header 'accept: application/json' --dump - http://localhost:8529/_admin/compact

Show output

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 2
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
}