ArangoDB Administration API
Get server information, manage licenses, shut down nodes, and more
OpenAPI Specification
openapi: 3.2.0
info:
contact:
name: ArangoDB Inc.
url: https://arango.ai
license:
name: Business Source License 1.1
url: https://github.com/arangodb/arangodb/blob/devel/LICENSE
summary: The HTTP API of the ArangoDB graph database system
title: ArangoDB Core Administration API
version: 3.12.10 (API v0)
description: Get server information, manage licenses, shut down nodes, and more
tags:
- description: Get server information, manage licenses, shut down nodes, and more
name: Administration
paths:
/_admin/compact:
put:
description: '> **WARNING:**
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.
'
operationId: compactAllDatabases
requestBody:
content:
application/json:
schema:
properties:
changeLevel:
default: false
description: 'whether or not compacted data should be moved to the minimum possible level.
'
type: boolean
compactBottomMostLevel:
default: false
description: 'Whether or not to compact the bottommost level of data.
'
type: boolean
type: object
responses:
'200':
description: 'Compaction started successfully
'
'401':
description: 'if the request was not authenticated as a user with sufficient rights
'
summary: Compact all databases
tags:
- Administration
/_admin/database/target-version:
get:
deprecated: true
description: '> **WARNING:**
This endpoint is deprecated and should no longer be used.
It is removed in ArangoDB v4.0. Use `GET /_api/version` instead.
Returns the database version that this server requires.
The version is returned in the `version` attribute of the result.
'
operationId: getDatabaseVersion
responses:
'200':
description: 'Is returned in all cases.
'
summary: Get the required database version (deprecated)
tags:
- Administration
/_admin/server/availability:
get:
description: '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.
'
operationId: getServerAvailability
responses:
'200':
description: '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':
description: '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.
'
summary: Return whether or not a server is available
tags:
- Administration
/_db/_system/_admin/options:
get:
description: "Return the effective configuration of the queried _arangod_ instance as\nset by startup options on the command-line and via a configuration file.\n\n{{< security >}}\nThis endpoint may reveal sensitive information about the deployment!\n{{< /security >}}\n\nThe endpoint can only be accessed via the `_system` database. In addition, the\n[`--server.options-api` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--serveroptions-api)\ncontrols the required privileges to access the option endpoints and allows\nyou to disable them entirely. The option can have the following values:\n- `disabled`: This endpoint is disabled.\n- `jwt`: This endpoint can only be accessed using a superuser JWT (default).\n- `admin`: This endpoint can only be accessed by users with\n write access to the `_system` database.\n- `public`: Every user with read access to the `_system` database can\n access this endpoint.\n"
operationId: getEffectiveStartupOptions
responses:
'200':
content:
application/json:
schema:
type: object
description: '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':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 401
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: '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.
'
'403':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 403
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: '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`.
'
'405':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 405
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'Returned if the HTTP method is not `GET`.
'
summary: Get the startup option configuration
tags:
- Administration
/_db/_system/_admin/options-description:
get:
description: "Return the startup options available to configure the queried _arangod_\ninstance, similar to the `--dump-options` startup option.\n\nThe endpoint can only be accessed via the `_system` database. In addition, the\n[`--server.options-api` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--serveroptions-api)\ncontrols the required privileges to access the option endpoints and allows\nyou to disable them entirely. The option can have the following values:\n- `disabled`: This endpoint is disabled.\n- `jwt`: This endpoint can only be accessed using a superuser JWT (default).\n- `admin`: This endpoint can only be accessed by users with\n write access to the `_system` database.\n- `public`: Every user with read access to the `_system` database can\n access this endpoint.\n"
operationId: getAvailableStartupOptions
responses:
'200':
content:
application/json:
schema:
type: object
description: "An object with startup option names as keys and sub-objects as values.\nThe structure of each sub-object is as follows:\n- `section` (string): The part before the dot of a startup option\n (`--section.param`), or `\"\"` if it is a general option that doesn't\n belong to a section\n- `description` (string): A succinct explanation of the startup option\n- `longDescription` (string, *optional*): Additional details about the\n startup option if available\n- `category` (string): Either `\"option\"` for regular options or `\"command\"`\n if using the option performs an action and then terminates the process\n- `hidden` (boolean): Whether the option is uncommon. If yes, then\n the `--help` command does not list it, but `--help-all` lists every\n startup option\n- `type` (string): the data type of the option, typically one of\n `\"uint64\"`, `\"uint32\"`, `\"int64\"`, `\"int32\"`, `\"double\"`, `\"boolean\"`,\n `\"string\"`, `\"string...\"`\n- `experimental` (boolean): Whether the option relates to a feature\n that is not ready for production yet\n- `obsolete` (boolean): Whether the option has been deprecated and\n no effect anymore\n- `enterpriseOnly` (boolean): Whether the option is implemented in\n the non-public enterprise code.\n- `requiresValue` (boolean): Whether the option can be specified\n without a value to enable it\n- `os` (array of strings): The operating systems the startup option\n is supported on, always `[\"linux\"]`\n- `component` (array of strings): A list of server roles the startup\n option is available on. If it is supported by all cluster node types\n as well as the single server deployment mode, then the value is\n `[\"coordinator\", \"dbserver\", \"agent\", \"single\"]`\n- `introducedIn` (array of strings\\|null): A list of versions the\n startup option has been added in. Does not include later minor and\n major versions then the current version, and the information may\n get removed once all listed versions reach their end of life\n- `deprecatedIn` (array of strings\\|null): A list of versions the\n startup option has been marked for deprecation in. It can still\n be used until fully removed. Does not include later minor and\n major versions then the current version, and the information may\n get removed once all listed versions reach their end of life\n- `values` (string, *optional*):\n A description of the possible values you can set\n- `default` (any, *optional*): The standard value if the option is not set\n- `dynamic` (boolean): Whether the default value is calculated based\n on the target host configuration, e.g. available memory\n- `required` (boolean): Whether the option must be specified\n- `base` (number, *optional*): the unit for a numeric option\n- `minValue` (number, *optional*): The minimum value for a numeric option\n- `maxValue` (number, *optional*): The maximum value for a numeric option\n- `minInclusive` (boolean, *optional*): Whether the minimum value is\n included in the allowed value range\n- `maxInclusive` (boolean, *optional*): Whether the maximum value is\n included in the allowed value range\n"
'401':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 401
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'You tried to authenticate with user credentials but a superuser token
is required, the credentials are wrong, or the user account is inactive.
'
'403':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 403
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'You don''t have write access to the `_system` database or you tried
to access the endpoint using a database other than `_system`.
'
'405':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 405
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'Returned if the HTTP method is not `GET`.
'
summary: Get the available startup options
tags:
- Administration
/_db/_system/_admin/support-info:
get:
description: '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.
'
operationId: getSupportInfo
responses:
'200':
content:
application/json:
schema:
properties:
date:
description: 'ISO 8601 datetime string of when the information was requested.
'
type: string
deployment:
description: '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`.
'
type: object
host:
description: 'An object that holds information about the ArangoDB instance as well as the
host machine. Only set in case of single servers.
'
type: object
required:
- date
- deployment
type: object
description: ''
'404':
description: 'The support info API is turned off.
'
summary: Get information about the deployment
tags:
- Administration
/_db/_system/_api/endpoint:
get:
deprecated: true
description: '> **WARNING:**
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.
> **INFO:**
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.
'
operationId: listEndpoints
responses:
'200':
description: 'is returned when the array of endpoints can be determined successfully.
'
'400':
description: 'is returned if the action is not carried out in the system database.
'
'405':
description: 'The server will respond with *HTTP 405* if an unsupported HTTP method is used.
'
summary: List the endpoints of a single server (deprecated)
tags:
- Administration
/_db/{database-name}/_admin/crashes:
get:
description: '<small>Introduced in: v3.12.8</small>
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.
'
operationId: listCrashDumps
parameters:
- description: '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
in: path
name: database-name
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
code:
example: 200
type: integer
error:
example: false
type: boolean
result:
description: 'Array of crash dump identifiers (UUIDs).
'
items:
format: uuid
type: string
type: array
required:
- error
- code
- result
type: object
description: 'Returns a list of crash dump identifiers (UUIDs).
'
'401':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 401
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: '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.
'
'403':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 403
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'Returned if authentication is enabled and the user does not have
write access to the `_system` database.
'
'503':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 503
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'The crash handler feature is not ready or has been disabled via the
[`--crash-handler.enable-dumps` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--crash-handlerenable-dumps).
'
summary: List crash dumps
tags:
- Administration
/_db/{database-name}/_admin/crashes/{crashId}:
delete:
description: '<small>Introduced in: v3.12.8</small>
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.
'
operationId: deleteCrashDump
parameters:
- description: '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
in: path
name: database-name
required: true
schema:
type: string
- description: 'The UUID of the crash dump directory to delete.
'
in: path
name: crashId
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
properties:
code:
example: 200
type: integer
error:
example: false
type: boolean
result:
properties:
crashId:
format: uuid
type: string
deleted:
example: true
type: boolean
required:
- deleted
- crashId
type: object
required:
- error
- code
- result
type: object
description: 'The crash dump was deleted successfully.
'
'401':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 401
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: '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.
'
'403':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 403
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'Returned if authentication is enabled and the user does not have
write access to the `_system` database.
'
'404':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 404
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'Returned if the crash dump folder based on the specified `crashId`
cannot be found.
'
'503':
content:
application/json:
schema:
properties:
code:
description: 'The HTTP response status code.
'
example: 503
type: integer
error:
description: 'A flag indicating that an error occurred.
'
example: true
type: boolean
errorMessage:
description: 'A descriptive error message.
'
type: string
errorNum:
description: 'The ArangoDB error number for the error that occurred.
'
type: integer
required:
- error
- code
- errorNum
- errorMessage
type: object
description: 'The crash handler feature is not ready or has been disabled via the
[`--crash-handler.enable-dumps` startup option](https://docs.arango.ai/arangodb/3.12/components/arangodb-server/options/#--crash-handlerenable
# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/arangodb/refs/heads/main/openapi/arangodb-administration-api-openapi.yml