ArangoDB v3.13 is under development and not released yet. This documentation is not final and potentially incomplete.

HTTP interface for administration

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 /_db/{database-name}/_api/version

Returns the server name and version number. The response is a JSON object with the following attributes:

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.

Query Parameters

details boolean
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.
- details object
  an optional JSON object with additional details. This is returned only if the details query parameter is set to true in the request.
  architecture string
  The CPU architecture, i.e. 64bit
  arm string
  false - this is not running on an ARM cpu
  asan string
  has this been compiled with the asan address sanitizer turned on? (should be false)
  assertions string
  do we have assertions compiled in (=> developer version)
  boost-version string
  which boost version do we bind
  build-date string
  the date when this binary was created
  build-repository string
  reference to the git-ID this was compiled from
  compiler string
  which compiler did we use
  cplusplus string
  C++ standards version
  debug string
  false for production binaries
  endianness string
  currently only little is supported
  failure-tests string
  false for production binaries (the facility to invoke fatal errors is disabled)
  fd-client-event-handler string
  which method do we use to handle fd-sets, poll should be here 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
  host string
  the host ID
  icu-version string
  Which version of ICU do we bundle
  jemalloc string
  true if we use jemalloc
  maintainer-mode string
  false if this is a production binary
  mode string
  The mode arangod runs in. Possible values: server, console, script
  openssl-version string
  which openssl version do we link?
  platform string
  the host operating system, always linux
  reactor-type string
  epoll
  rocksdb-version string
  the rocksdb version this release bundles
  server-version string
  the ArangoDB release version
  sizeof int string
  number of bytes for integers
  sizeof void* string
  number of bytes for void pointers
  sse42 string
  do we have a SSE 4.2 enabled cpu?
  unaligned-access string
  does this system support unaligned memory access?
  v8-version string
  the bundled V8 javascript engine version
  vpack-version string
  the version of the used velocypack implementation
  zlib-version string
  the version of the bundled zlib
- server* string
  will always contain arango
- version* string
  the server version string. The string has the format major.minor.sub. major and minor will be numeric, and sub may contain a number or a textual version.

Examples

Return the version information

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

Show output

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 /_db/{database-name}/_api/engine

Returns the storage engine the server is configured to use. The response is a JSON object with the following attributes:

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.

Query Parameters

HTTP Headers

Responses

200 OK
is returned in all cases.
- name* string
  will be rocksdb

Examples

Return the active storage engine:

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

Show output

Get the system time

GET /_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.

Query Parameters

HTTP Headers

Responses

200 OK
Time was returned successfully.
- code* integer
  the HTTP status code
- error* boolean
  boolean flag to indicate whether an error occurred (false in this case)
- time* number
  The current system time as a Unix timestamp with microsecond precision of the server

Get server status information

GET /_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.

Query Parameters

HTTP Headers

Responses

200 OK
Status information was returned successfully.
- agency object
  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
  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.
- coordinator object
  Information about the Coordinators. Cluster only (Coordinators)
  foxxmaster array of strings
  The server ID of the Coordinator that is the Foxx master.
  isFoxxmaster array of strings
  Whether the queried Coordinator is the Foxx master.
- foxxApi* boolean
  Whether the Foxx API is enabled.
- 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
  A hostname defined by the HOSTNAME environment variable.
- license* string
  ArangoDB Edition, either "community" or "enterprise".
- mode* string
  Either "server" or "console". Deprecated, use operationMode instead.
- operationMode* string
  Either "server" or "console".
- pid* number
  The process ID of arangod.
- server* string
  Always "arango".
- serverInfo* object
  Information about the server status.
  address string
  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
  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
  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
  The server ID, e.g. "CRDN-e427b441-5087-4a9a-9983-2fb1682f3e2a". Cluster only (Coordinators and DB-Servers).
  state string
  Either "STARTUP", "SERVING", or "SHUTDOWN". Cluster only (Coordinators and DB-Servers).
  writeOpsEnabled* boolean
  Whether writes are enabled. Deprecated, use readOnly instead.
- version* string
  The server version as a string.

Examples

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

Show output

Return whether or not a server is available

GET /_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 /_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
  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/_admin/support-info

Show output

Query support information from a cluster

curl --header 'accept: application/json' --dump - http://localhost:8529/_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: 6566
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-085d1776-5a95-496c-9b09-7382e9db7327" : { 
        "id" : "CRDN-085d1776-5a95-496c-9b09-7382e9db7327", 
        "alias" : "Coordinator0001", 
        "endpoint" : "tcp://localhost:8529", 
        "role" : "COORDINATOR", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.0-nightly.20240305", 
        "build" : "refs/head/3.12 9b0f5c5d58c", 
        "license" : "enterprise", 
        "os" : "Linux version 5.15.0-1052-aws (buildd@lcy02-amd64-013) (gcc (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0, GNU ld (GNU Binutils for Ubuntu) 2.34) #57~20.04.1-Ubuntu SMP Mon Jan 15 17:04:56 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33106219008, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 39.9025239944458, 
          "numberOfThreads" : 36, 
          "virtualSize" : 1116704768, 
          "residentSetSize" : 106000384 
        }, 
        "cpuStats" : { 
          "userPercent" : 12.428773773611427, 
          "systemPercent" : 4.045974028782424, 
          "idlePercent" : 80.40697611556219, 
          "iowaitPercent" : 2.827424394779807 
        } 
      }, 
      "CRDN-90a2159c-2dd1-4cdd-bd26-bbbf16136079" : { 
        "id" : "CRDN-90a2159c-2dd1-4cdd-bd26-bbbf16136079", 
        "alias" : "Coordinator0002", 
        "endpoint" : "tcp://localhost:8539", 
        "role" : "COORDINATOR", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.0-nightly.20240305", 
        "build" : "refs/head/3.12 9b0f5c5d58c", 
        "license" : "enterprise", 
        "os" : "Linux version 5.15.0-1052-aws (buildd@lcy02-amd64-013) (gcc (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0, GNU ld (GNU Binutils for Ubuntu) 2.34) #57~20.04.1-Ubuntu SMP Mon Jan 15 17:04:56 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33106219008, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 39.88232755661011, 
          "numberOfThreads" : 36, 
          "virtualSize" : 1114083328, 
          "residentSetSize" : 103403520 
        }, 
        "cpuStats" : { 
          "userPercent" : 12.428773773611427, 
          "systemPercent" : 4.045974028782424, 
          "idlePercent" : 80.40697611556219, 
          "iowaitPercent" : 2.827424394779807 
        } 
      }, 
      "PRMR-2678bdce-1850-4f94-893b-f398ba10df50" : { 
        "id" : "PRMR-2678bdce-1850-4f94-893b-f398ba10df50", 
        "alias" : "DBServer0003", 
        "endpoint" : "tcp://localhost:8530", 
        "role" : "PRIMARY", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.0-nightly.20240305", 
        "build" : "refs/head/3.12 9b0f5c5d58c", 
        "license" : "enterprise", 
        "os" : "Linux version 5.15.0-1052-aws (buildd@lcy02-amd64-013) (gcc (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0, GNU ld (GNU Binutils for Ubuntu) 2.34) #57~20.04.1-Ubuntu SMP Mon Jan 15 17:04:56 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33106219008, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 40.900248765945435, 
          "numberOfThreads" : 65, 
          "virtualSize" : 935604224, 
          "residentSetSize" : 161751040 
        }, 
        "cpuStats" : { 
          "userPercent" : 12.428773773611427, 
          "systemPercent" : 4.045974028782424, 
          "idlePercent" : 80.40697611556219, 
          "iowaitPercent" : 2.827424394779807 
        }, 
        "engineStats" : { 
          "cache.limit" : 7739683840, 
          "cache.allocated" : 1082848, 
          "rocksdb.estimate-num-keys" : 10, 
          "rocksdb.estimate-live-data-size" : 0, 
          "rocksdb.live-sst-files-size" : 0, 
          "rocksdb.block-cache-capacity" : 9287620608, 
          "rocksdb.block-cache-usage" : 96, 
          "rocksdb.free-disk-space" : 142930042880, 
          "rocksdb.total-disk-space" : 155897610240 
        } 
      }, 
      "PRMR-d761f99e-d613-4efd-af1f-91e6334feba0" : { 
        "id" : "PRMR-d761f99e-d613-4efd-af1f-91e6334feba0", 
        "alias" : "DBServer0001", 
        "endpoint" : "tcp://localhost:8540", 
        "role" : "PRIMARY", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.0-nightly.20240305", 
        "build" : "refs/head/3.12 9b0f5c5d58c", 
        "license" : "enterprise", 
        "os" : "Linux version 5.15.0-1052-aws (buildd@lcy02-amd64-013) (gcc (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0, GNU ld (GNU Binutils for Ubuntu) 2.34) #57~20.04.1-Ubuntu SMP Mon Jan 15 17:04:56 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33106219008, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 40.88037610054016, 
          "numberOfThreads" : 65, 
          "virtualSize" : 939274240, 
          "residentSetSize" : 163307520 
        }, 
        "cpuStats" : { 
          "userPercent" : 12.428773773611427, 
          "systemPercent" : 4.045974028782424, 
          "idlePercent" : 80.40697611556219, 
          "iowaitPercent" : 2.827424394779807 
        }, 
        "engineStats" : { 
          "cache.limit" : 7739683840, 
          "cache.allocated" : 1082848, 
          "rocksdb.estimate-num-keys" : 188, 
          "rocksdb.estimate-live-data-size" : 0, 
          "rocksdb.live-sst-files-size" : 0, 
          "rocksdb.block-cache-capacity" : 9287620608, 
          "rocksdb.block-cache-usage" : 96, 
          "rocksdb.free-disk-space" : 142930042880, 
          "rocksdb.total-disk-space" : 155897610240 
        } 
      }, 
      "PRMR-227d8305-3735-4e6e-b33d-16d62dfcc1ee" : { 
        "id" : "PRMR-227d8305-3735-4e6e-b33d-16d62dfcc1ee", 
        "alias" : "DBServer0002", 
        "endpoint" : "tcp://localhost:8550", 
        "role" : "PRIMARY", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.0-nightly.20240305", 
        "build" : "refs/head/3.12 9b0f5c5d58c", 
        "license" : "enterprise", 
        "os" : "Linux version 5.15.0-1052-aws (buildd@lcy02-amd64-013) (gcc (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0, GNU ld (GNU Binutils for Ubuntu) 2.34) #57~20.04.1-Ubuntu SMP Mon Jan 15 17:04:56 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33106219008, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 41.87971639633179, 
          "numberOfThreads" : 65, 
          "virtualSize" : 956575744, 
          "residentSetSize" : 166555648 
        }, 
        "cpuStats" : { 
          "userPercent" : 12.428773773611427, 
          "systemPercent" : 4.045974028782424, 
          "idlePercent" : 80.40697611556219, 
          "iowaitPercent" : 2.827424394779807 
        }, 
        "engineStats" : { 
          "cache.limit" : 7739683840, 
          "cache.allocated" : 1082848, 
          "rocksdb.estimate-num-keys" : 200, 
          "rocksdb.estimate-live-data-size" : 0, 
          "rocksdb.live-sst-files-size" : 0, 
          "rocksdb.block-cache-capacity" : 9287620608, 
          "rocksdb.block-cache-usage" : 96, 
          "rocksdb.free-disk-space" : 142930042880, 
          "rocksdb.total-disk-space" : 155897610240 
        } 
      }, 
      "CRDN-7c96e96b-2f14-42ca-98d7-5595548c4649" : { 
        "id" : "CRDN-7c96e96b-2f14-42ca-98d7-5595548c4649", 
        "alias" : "Coordinator0003", 
        "endpoint" : "tcp://localhost:8549", 
        "role" : "COORDINATOR", 
        "maintenance" : false, 
        "readOnly" : false, 
        "version" : "3.12.0-nightly.20240305", 
        "build" : "refs/head/3.12 9b0f5c5d58c", 
        "license" : "enterprise", 
        "os" : "Linux version 5.15.0-1052-aws (buildd@lcy02-amd64-013) (gcc (Ubuntu 9.4.0-1ubuntu1~20.04.2) 9.4.0, GNU ld (GNU Binutils for Ubuntu) 2.34) #57~20.04.1-Ubuntu SMP Mon Jan 15 17:04:56 UTC 2024", 
        "platform" : "linux", 
        "physicalMemory" : { 
          "value" : 33106219008, 
          "overridden" : false 
        }, 
        "numberOfCores" : { 
          "value" : 8, 
          "overridden" : false 
        }, 
        "processStats" : { 
          "processUptime" : 40.876648902893066, 
          "numberOfThreads" : 36, 
          "virtualSize" : 1114083328, 
          "residentSetSize" : 105291776 
        }, 
        "cpuStats" : { 
          "userPercent" : 12.428773773611427, 
          "systemPercent" : 4.045974028782424, 
          "idlePercent" : 80.40697611556219, 
          "iowaitPercent" : 2.827424394779807 
        } 
      } 
    }, 
    "agents" : 3, 
    "coordinators" : 3, 
    "dbServers" : 3, 
    "shards" : { 
      "databases" : 1, 
      "collections" : 16, 
      "shards" : 28, 
      "leaders" : 16, 
      "realLeaders" : 5, 
      "followers" : 12, 
      "servers" : 3 
    } 
  }, 
  "date" : "2024-03-11T19:03:42Z" 
}

Startup options

The permissions required to use the /_admin/options* endpoints depends on the setting of the --server.options-api startup option.

Get the startup option configuration

GET /_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: the option endpoints are disabled
jwt: the option endpoints can only be accessed using a superuser JWT (default)
admin: the option endpoints can only be accessed by users with Administrate access level for the _system database
public: every user with access to the _system database can access the option endpoints

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.

Get the available startup options

GET /_db/_system/_admin/options-description

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

disabled: the option endpoints are disabled
jwt: the option endpoints can only be accessed using a superuser JWT (default)
admin: the option endpoints can be accessed by admin users in the _system database only.
public: every user with access to the _system database can access the option endpoints.

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 only available in the Enterprise Edition. The Community Edition does have most of the Enterprise Edition startup options and they are thus not reported
- 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

Server mode

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

GET /_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.

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 /_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.

Query Parameters

HTTP Headers

Request Body application/json object

mode* string
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 /_db/{database-name}/_admin/license

View the license information and status of 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.

Query Parameters

HTTP Headers

Responses

200 OK
Returns the license information.
- features object
  The properties of the license.
  expires* number
  The expires key lists the expiry date as Unix timestamp (seconds since January 1st, 1970 UTC).
- hash string
  The hash value of the license.
- license* string
  The encrypted license key in Base64 encoding, or "none" in the Community Edition.
- status string
  The status key allows you to confirm the state of the installed license on a glance. The possible values are as follows:
  good: The license is valid for more than 2 weeks.
  expiring: The license is valid for less than 2 weeks.
  expired: The license has expired. In this situation, no new Enterprise Edition features can be utilized.
  read-only: The license is expired over 2 weeks. The instance is now restricted to read-only mode.
- upgrading boolean
  Whether the server is performing a database upgrade.
- version number
  The license version number.

Examples

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

Show output

Set a new license

PUT /_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.

Query Parameters

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

HTTP Headers

Request Body application/json string

The request body has to contain the Base64-encoded string wrapped in double quotes.

Responses

201 Created
License successfully deployed.
- result* object
  code* integer
  The HTTP status code.
  error* boolean
  A flag indicating that no error occurred.
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 status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  The ArangoDB error number.
501 Not Implemented
If you try to apply a license in the Community Edition.
- code* integer
  The HTTP status code.
- error* boolean
  A flag indicating that an error occurred.
- errorMessage* string
  A descriptive error message.
- errorNum* integer
  The ArangoDB error number.

Examples

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

Show output

Shutdown

Start the shutdown sequence

DELETE /_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.

Query Parameters

soft boolean
Introduced in: v3.7.12, v3.8.1, v3.9.0
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 /_db/{database-name}/_admin/shutdown

Introduced in: v3.7.12, v3.8.1, v3.9.0

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.

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 /_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
whether or not compacted data should be moved to the minimum possible level. The default value is false.
compactBottomMostLevel boolean
Whether or not to compact the bottommost level of data. The default value is false.

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

Reload the routing table

POST /_db/{database-name}/_admin/routing/reload

Reloads the routing information from the _routing system collection if it exists, and makes Foxx rebuild its local routing table on the next request.

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.

Query Parameters

HTTP Headers

Responses

200 OK
The routing information has been reloaded successfully.

Echo a request

POST /_db/{database-name}/_admin/echo

The call returns an object with the servers request information

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.

Query Parameters

HTTP Headers

Request Body application/json object

body* string
The request body can be of any type and is simply forwarded.

Responses

200 OK
Echo was returned successfully.
- authorized* boolean
  Whether the session is authorized
- client* object
  Attributes of the client connection
  address* integer
  The IP address of the client
  id* string
  A server generated ID
  port* integer
  The port of the TCP connection on the client-side
- cookies* object
  A list of the cookies you sent
- database* string
  The name of the database this request was executed on
- headers* object
  The list of the HTTP headers you sent
- internals* object
  Contents of the server internals struct
- isAdminUser* boolean
  Whether the current user is an administrator
- parameters* object
  An object containing the query parameters
- path* string
  The relative path of this request (decoded, excluding /_admin/echo)
- portType* string
  The type of the socket, one of "tcp/ip", "unix", "unknown"
- prefix* object
  The prefix of the database
- protocol* string
  The transport protocol, one of "http", "https"
- rawRequestBody* object
  The sent payload as a JSON-encoded Buffer object
- rawSuffix* array of strings
  A list of the percent-encoded URL path suffixes
- requestBody* string
  Stringified version of the request body you sent
- requestType* string
  The HTTP method that was used for the request ("POST"). The endpoint can be queried using other verbs, too ("GET", "PUT", "PATCH", "DELETE").
- server* object
  Attributes of the server connection
  address* string
  The bind address of the endpoint this request was sent to
  endpoint* string
  The endpoint this request was sent to
  port* integer
  The port this request was sent to
- suffix* array of strings
  A list of the decoded URL path suffixes. You can query the endpoint with arbitrary suffixes, e.g. /_admin/echo/foo/123
- url* string
  The raw request URL
- user* string
  The name of the current user that sent this request

Execute a script

POST /_db/{database-name}/_admin/execute

Executes the JavaScript code in the body on the server as the body of a function with no arguments. If you have a return statement then the return value you produce will be returned as content type application/json. If the parameter returnAsJSON is set to true, the result will be a JSON object describing the return value directly, otherwise a string produced by JSON.stringify will be returned.

Note that this API endpoint will only be present if the server was started with the option --javascript.allow-admin-execute true.

The default value of this option is false, which disables the execution of user-defined code and disables this API endpoint entirely. This is also the recommended setting for production.

Path Parameters

database-name* string
The name of the database.

Query Parameters

HTTP Headers

Request Body application/json object

body* string
The request body is the JavaScript code to be executed.

Responses

200 OK
is returned when everything went well, or if a timeout occurred. In the latter case a body of type application/json indicating the timeout is returned. depending on returnAsJSON this is a json object or a plain string.
403 Forbidden
is returned if ArangoDB is not running in cluster mode.
404 Not Found
is returned if ArangoDB was not compiled for cluster operation.

Endpoints

The /_api/endpoint endpoint is deprecated. For cluster deployments, you can use /_api/cluster/endpoints instead to find all current Coordinator endpoints. See Cluster.

An ArangoDB server can listen for incoming requests on multiple endpoints.

The endpoints are normally specified either in the arangod configuration file or on the command-line, using the --server.endpoint startup option. The default endpoint for ArangoDB is tcp://127.0.0.1:8529 (IPv4 localhost on port 8529 over the HTTP protocol).

Note that all endpoint management operations can only be accessed via the default _system database and none of the other databases.

List the endpoints of a single server (deprecated)

GET /_db/_system/_api/endpoint

This route should no longer be used. It is considered as deprecated from version 3.4.0 on.

Returns an array of all configured endpoints the server is listening on.

The result is a JSON array of JSON objects, each with "entrypoint" as the only attribute, and with the value being a string describing the endpoint.

Retrieving the array of all endpoints is allowed in the system database only. Calling this action in any other database will make the server return an error.

Responses

200 OK
is returned when the array of endpoints can be determined successfully.
400 Bad Request
is returned if the action is not carried out in the system database.
405 Method Not Allowed
The server will respond with HTTP 405 if an unsupported HTTP method is used.

Examples

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

Show output