ArangoDB v3.12 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 /_api/version

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

Query Parameters

  • details (boolean, optional): If set to true, the response will contain 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.

Responses

HTTP 200: is returned in all cases.

  • 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.

  • 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

    • 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

    • openssl-version (string): which openssl version do we link?

    • platform (string): the host os - linux, windows or darwin

    • 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

    • mode (string): The mode arangod runs in. Possible values: server, console, script

    • host (string): the host ID

Examples

Return the version information

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

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: 67
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
Show response body

Return the version information with details

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

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: 1602
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
Show response body

Get the storage engine type

GET /_api/engine

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

Responses

HTTP 200: is returned in all cases.

  • name (string): will be rocksdb

Examples

Return the active storage engine with the RocksDB storage engine in use:

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

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: 212
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
Show response body

Get the system time

GET /_admin/time

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

Responses

HTTP 200: Time was returned successfully.

  • error (boolean): boolean flag to indicate whether an error occurred (false in this case)

  • code (integer): the HTTP status code

  • time (number): The current system time as a Unix timestamp with microsecond precision of the server

Get server status information

GET /_admin/status

Returns status information about the server.

Responses

HTTP 200: Status information was returned successfully.

  • server (string): Always "arango".

  • license (string): ArangoDB Edition, either "community" or "enterprise".

  • version (string): The server version as a string.

  • mode (string): Either "server" or "console". Deprecated, use operationMode instead.

  • operationMode (string): Either "server" or "console".

  • 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.

  • pid (number): The process ID of arangod.

  • serverInfo (object): Information about the server status.

    • 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.

      • 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".

      • feature (string): Internal name of the feature that is currently being prepared, started, stopped or unprepared.

      • 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.

    • role (string): Either "SINGLE", "COORDINATOR", "PRIMARY" (DB-Server), or "AGENT".

    • writeOpsEnabled (boolean): Whether writes are enabled. Deprecated, use readOnly instead.

    • readOnly (boolean): Whether writes are disabled.

    • 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).

    • rebootId (number): The reboot ID. Changes on every restart. Cluster only (Agents, Coordinators, and DB-Servers).

    • state (string): Either "STARTUP", "SERVING", or "SHUTDOWN". Cluster only (Coordinators and DB-Servers).

    • address (string): The address of the server, e.g. tcp://[::1]:8530. Cluster only (Coordinators and DB-Servers).

    • serverId (string): The server ID, e.g. "CRDN-e427b441-5087-4a9a-9983-2fb1682f3e2a". Cluster only (Coordinators and DB-Servers).

  • 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.

  • 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.

  • agent (object): Information about the Agents. Cluster only (Agents)

    • 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.

    • endpoint (string): The endpoint of the queried Agent.

    • term (number): The current term number.

Examples

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

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: 720
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
Show response body

Return whether or not a server is available

GET /_admin/server/availability

Return availability information about a server.

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

HTTP 200: 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 and is currently not a follower in case of an Active Failover deployment setup.

HTTP 503: HTTP 503 will be returned in case the server is during startup or during shutdown, is set to read-only mode or is currently a follower in an Active Failover deployment setup.

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 the required database version

GET /_admin/database/target-version

Returns the database version that this server requires. The version is returned in the version attribute of the result.

Responses

HTTP 200: Is returned in all cases.

Get information about the deployment

GET /_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 Active Failover or 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

HTTP 200:

  • 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 type.

    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.

HTTP 404: The support info API is turned off.

Examples

Query support information from a single server

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

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: 1115
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
Show response body

Query support information from a cluster

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

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: 3512
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
Show response body

Server mode

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

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

Responses

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

Set the server mode to read-only or default

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

Request Body

  • mode (string, required): The mode of the server readonly or default.

Responses

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

HTTP 401: 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 /_admin/license

View the license information and status of an Enterprise Edition instance. Can be called on single servers, Coordinators, and DB-Servers.

Responses

HTTP 200:

  • 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).

  • license (string): The encrypted license key in Base64 encoding.

  • version (number): The license version number.

  • 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.

Examples

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

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: 162
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
Show response body

Set a new license

PUT /_admin/license

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

Query Parameters

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

Request Body

(string, required)

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

Responses

HTTP 400: If the license expires earlier than the previously installed one.

HTTP 201: License successfully deployed.

Examples

shell> curl -XPUT http://localhost:8529/_admin/license -d '"<license-string>"'

Server response in case of success:

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

Server response if the new license expires sooner than the current one (requires ?force=true to update the license anyway):

{
  "code": 400,
  "error": true,
  "errorMessage": "This license expires sooner than the existing. You may override this by specifying force=true with invocation.",
  "errorNum": 9007
}

In case of a different error related to an expired or invalid license, please contact ArangoDB sales.

Shutdown

Start the shutdown sequence

DELETE /_admin/shutdown

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

Query Parameters

  • soft (boolean, optional): 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)
    • Pregel runs (conducted by this Coordinator)
    • 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

Responses

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

Query the soft shutdown progress

GET /_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)
  • Pregel runs (conducted by this Coordinator)
  • 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.

Responses

HTTP 200: 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.

  • softShutdownOngoing (boolean): Whether a soft shutdown of the Coordinator is in progress.

  • AQLcursors (number): Number of AQL cursors that are still active.

  • transactions (number): Number of ongoing transactions.

  • pendingJobs (number): Number of ongoing asynchronous requests.

  • doneJobs (number): Number of finished asynchronous requests, whose result has not yet been collected.

  • pregelConductors (number): Number of ongoing Pregel jobs.

  • lowPrioOngoingRequests (number): Number of queued low priority requests.

  • lowPrioQueuedRequests (number): Number of ongoing low priority requests.

  • allClear (boolean): Whether all active operations finished.

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

  • changeLevel (boolean, optional): whether or not compacted data should be moved to the minimum possible level. The default value is false.

  • compactBottomMostLevel (boolean, optional): Whether or not to compact the bottommost level of data. The default value is false.

Responses

HTTP 200: Compaction started successfully

HTTP 401: if the request was not authenticated as a user with sufficient rights

Examples

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

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

{ 
}

Reload the routing table

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

Responses

HTTP 200: The routing information has been reloaded successfully.

Echo a request

POST /_admin/echo

The call returns an object with the servers request information

Request Body

(string, required)

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

Responses

HTTP 200: Echo was returned successfully.

  • authorized (boolean): Whether the session is authorized

  • user (string): The name of the current user that sent this request

  • isAdminUser (boolean): Whether the current user is an administrator

  • database (string): The name of the database this request was executed on

  • url (string): The raw request URL

  • protocol (string): The transport protocol, one of "http", "https", "velocystream"

  • portType (string): The type of the socket, one of "tcp/ip", "unix", "unknown"

  • server (object): Attributes of the server connection

    • address (string): The bind address of the endpoint this request was sent to

    • port (integer): The port this request was sent to

    • endpoint (string): The endpoint this request was sent to

  • client (object): Attributes of the client connection

    • address (integer): The IP address of the client

    • port (integer): The port of the TCP connection on the client-side

    • id (string): A server generated ID

  • internals (object): Contents of the server internals struct

  • prefix (object): The prefix of the database

  • headers (object): The list of the HTTP headers 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").

  • requestBody (string): Stringified version of the request body you sent

  • rawRequestBody (object): The sent payload as a JSON-encoded Buffer object

  • parameters (object): An object containing the query parameters

  • cookies (object): A list of the cookies you sent

  • 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

  • rawSuffix (array of strings): A list of the percent-encoded URL path suffixes

  • path (string): The relative path of this request (decoded, excluding /_admin/echo)

Execute a script

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

Request Body

(string, required)

The request body is the JavaScript code to be executed.

Responses

HTTP 200: 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.

HTTP 403: is returned if ArangoDB is not running in cluster mode.

HTTP 404: 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 /_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.

Note: 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

HTTP 200: is returned when the array of endpoints can be determined successfully.

HTTP 400: is returned if the action is not carried out in the system database.

HTTP 405: The server will respond with HTTP 405 if an unsupported HTTP method is used.

Examples

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

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: 38
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
Show response body
❮  Security

© ArangoDB - Graph and Beyond