HTTP/JSON API

Returns a JSON document containing the HTTP API’s OpenAPI definition.

URL Syntax: /api/v1/openapi.json

Response:

Example:

Return:

Returns a header-only (no content) status about if the ArcadeDB server is ready.

URL Syntax: /api/v1/ready

This endpoint accepts GET or HEAD requests without authentication, and is useful for remote monitoring of server readiness. Use it as a Kubernetes readiness probe. HEAD is supported so tools that check health with a HEAD request (e.g. wget --spider) work out of the box.

Responses:

When arcadedb.server.readinessRequiresHA=true and HA is active, readiness additionally requires the node to have joined the Raft group: it returns 503 (Node has not yet joined the Raft group) until a leader has been elected. Once a leader is known, a second gate requires the node to be a member of the current Raft configuration and, for a follower, to have replayed the committed log to within arcadedb.server.readinessHAMaxLag entries of the commit index; until then it returns 503 (Node is not yet in the Raft configuration or has not caught up). This keeps a (re)joined follower with a wiped or lagging log out of traffic during a rolling restart, so the write quorum is not dropped. The default (false for readinessRequiresHA) preserves the behavior above. See Health probes.

Example:

Return:

Returns a header-only (no content) liveness status. Use it as a Kubernetes liveness probe.

URL Syntax: /api/v1/health

This endpoint accepts GET or HEAD requests without authentication and performs no database I/O. It returns 204 whenever the server process and HTTP layer are up; unlike readiness it never reports a busy state, so a warming-up node is not restarted. The one exception: on a High Availability cluster, a node that has given up recovering from a crash loop returns 503, so the orchestrator restarts it. See Health probes.

Response:

Example:

Return:

Returns the current configuration.

URL Syntax: /api/v1/server

The following mode query parameter values are available:

In default mode the settings array reports, for each server-level setting, the value this server is actually running on in value and the built-in default in default, with overridden telling you whether the two differ because the setting was given an explicit value - in the server configuration file, by an embedding application, or at runtime with set server setting. Secrets are masked: settings that are secrets in their entirety (the HA cluster token, any key containing password) report , and arcadedb.server.defaultDatabases, whose value merely *embeds credentials, keeps its database names, user names and groups while each password is replaced (since v26.10.1).

Responses:

Example:

Return:

Sends control commands to server.

URL Syntax: /api/v1/server

The following commands are available:

Both restore database and import database support SSE progress streaming: send Accept: text/event-stream in the request headers to receive real-time progress events instead of waiting for the response. With an X-Request-Id, a retry of a restore or import that completed is replayed rather than run again, in either encoding (see Retrying Requests Safely (X-Request-Id)).

Responses:

Databases opened on demand. Since v26.11.1 a database that exists on disk but is not open on the server, because arcadedb.server.databaseLoadAtStartup is false, is opened by the first HTTP request that names it (query, command, batch load, WebSocket insert session), as the Postgres, BOLT and gRPC protocols already did. Until v26.10.2 the HTTP API answered Database '<dbname>' is not available until the database was opened explicitly with open database. Only a directory that really holds a database (one with a schema.json or schema.prev.json file) is opened: any other name is refused as before, and a request never creates a directory. The user must still be authorized on the database. This makes databaseLoadAtStartup=false practical for a server that hosts many databases: it starts without opening any of them, and each one is opened by its first request (issue #10234).

A database closed with the close database server command is the exception: it was closed on purpose, for a restore of its files or a cold backup, so an HTTP request does not reopen it. It stays closed until open database (or a restore, an import or a drop of that name). The server remembers this in memory only and for the node that received the command: after a restart the database is opened again, at start or on its first request.

The same rule holds for the other protocols. A database that a close database command closed, or that an overwrite restore of its name is about to replace, is not opened by a Postgres, BOLT, gRPC, Redis or MongoDB connection, or by an MCP or Gremlin request, that names it: the client is told that the database is not available, as an HTTP request is (503 for HTTP, SQLSTATE 57P03 for Postgres, status UNAVAILABLE for gRPC, the transient Neo.TransientError.Database.DatabaseUnavailable for BOLT, a LOADING error reply for Redis, error 365 TemporarilyUnavailable for MongoDB; an engine error category of its own, UNAVAILABLE, so that none of them reports it as a server fault). A Redis key <database>.<key> whose database is held is refused the same way, and not kept as a plain key of the connection. (Since v26.11.1: before, these protocols opened it, so a cold backup copied a database that was open and being written to, and the writes a client made during an overwrite restore were acknowledged and then discarded when the restored copy replaced the database, issue #10533.) A database that is already open keeps serving reads while an overwrite restore replaces it, and refuses every write until the restore ends, on every protocol and also on a connection opened before the restore started: the write is answered as "not available", with the codes above, and a database setting change is refused the same way. The restore first waits for the commits already running. (Since v26.11.1: before, those writes were acknowledged and then lost with the database the restore replaced, issue #10689.) A name that is not a database at all is the client’s to correct, and every protocol says so rather than reporting a server fault: SQLSTATE 3D000 for Postgres, status NOT_FOUND for gRPC, Neo.ClientError.Database.DatabaseNotFound for BOLT, error 26 NamespaceNotFound for MongoDB, ERR Database '<name>' not found for Redis, 404 for HTTP (an engine error category of its own, DATABASE_NOT_FOUND, since v26.11.1, issue #10795). A connection that keeps naming a database across a close database + open database, a drop database + create database or an overwrite restore is served by the new database as soon as it is there (issue #10794).

Since v26.11.1, HTTP tells the two apart as every other protocol does (issue #10872): a name that is no database answers 404 with "error": "Database not found" and the exception com.arcadedb.exception.DatabaseNotFoundException; a database that is there and cannot serve the request now answers 503 with the exception com.arcadedb.exception.DatabaseNotAvailableException, an error naming the state, and the state in exceptionArgs, so a client is told it in production mode too, where the detail is not sent:

No Retry-After is sent: how long an operator keeps a database closed is not something the server knows. The Java remote client rebuilds both exceptions, with the state as DatabaseNotAvailableException.getReason(), and does not retry either of them.

Examples:

(Since v26.10.1) POST /api/v1/cluster/auth-session is a cluster-internal route that lets servers share authentication tokens (see Tokens in a cluster under Token-Based Authentication). It is not meant for clients and is listed here only so it is not mistaken for a public API. The request must arrive through the cluster-token channel (X-ArcadeDB-Cluster-Token header) on behalf of the root user: a request without that header is refused with 403, even with root credentials, and an invalid cluster token gets 401.

The body is {"token": "<AU-…​ token>", "action": "validate" | "revoke"} (action defaults to validate). validate answers 200 with {"user": …​, "createdAt": …​} when this server issued the session, and 404 otherwise (including for a copy held on behalf of another server); revoke drops the session and answers 204. A missing token or an unknown action answers 400.

Returns a list of available databases for the requesting user.

URL Syntax: /api/v1/databases

Responses:

Example:

Return:

Returns boolean answering if database exists.

URL Syntax: /api/v1/exists/{database}

Responses:

Example:

Return:

Returns the long-running maintenance operations currently in progress on this server for one database, with their step-by-step progress. CHECK DATABASE, REBUILD INDEX, COMPACT INDEX, BACKUP DATABASE and IMPORT DATABASE publish their progress here while they run. The endpoint answers from an in-memory snapshot without touching the database, so it is safe to poll at any frequency (the console and Studio poll it to render a live progress bar). In a cluster each server reports its own operations.

URL Syntax: /api/v1/progress/{database}

Responses:

Example:

Return (one entry per running operation, empty array when nothing is running):

percentage is -1 when the current step’s total is unknown (for example the backup or the import, whose sizes cannot be computed upfront).

Authenticates a user and returns an authentication token that can be used for subsequent requests instead of sending credentials each time. See Token-Based Authentication for more details.

URL Syntax: /api/v1/login

This endpoint requires HTTP Basic Authentication with valid credentials. On successful authentication, it returns a JSON response containing the authentication token.

Responses:

Example:

Return:

The returned token can be used in subsequent requests via the Authorization: Bearer header:

Invalidates an authentication token so it can no longer be used for requests. The token must be provided via the Authorization: Bearer header.

URL Syntax: /api/v1/logout

Responses:

Example:

After logout, any attempt to use the invalidated token will result in a 401 Unauthorized response.

Returns a list of all active authentication sessions. This endpoint is restricted to root users only for security reasons.

URL Syntax: /api/v1/sessions

Responses:

Example:

Return:

The elapsedMs field indicates how many milliseconds have passed since the last request using that token.

Mints a long-lived API token (at- prefix) for a script or service. Root only. The plaintext token is returned once, in result.token, and is never shown again: the server keeps only its hash. On a cluster the request is forwarded to the leader and the token is replicated to every node. GET /api/v1/server/api-tokens lists the tokens and DELETE /api/v1/server/api-tokens?token=<hash> revokes one. Studio’s API Tokens panel uses the same routes.

URL Syntax: /api/v1/server/api-tokens

Body: name (required), database (default *, every database), expiresAt (epoch milliseconds, 0 for no expiry) and permissions (the same structure as a group).

Responses:

Transport check (since v26.10.1). The token authenticates whoever holds it, so the server checks how the mint reached it. The transport counts as protected when the request came over HTTPS, from a loopback address, or from a reverse proxy listed in arcadedb.server.apiTokenTrustedProxies that reports https for every hop through X-Forwarded-Proto or the RFC 7239 Forwarded header. What happens otherwise depends on arcadedb.server.apiTokenRequireSecureTransport:

On a cluster the check also covers the hop between nodes: a mint forwarded to the leader over cleartext inter-node HTTP is refused with 412 too, even when the client itself used HTTPS.

Behind a TLS-terminating reverse proxy. When nginx, Envoy or a Kubernetes ingress terminates TLS and forwards to ArcadeDB over HTTP, the server sees a cleartext request from the proxy’s address. List that address (or its subnet) in arcadedb.server.apiTokenTrustedProxies, for example -Darcadedb.server.apiTokenTrustedProxies=10.0.0.5,10.1.0.0/16, and make sure the proxy sets X-Forwarded-Proto (nginx: proxy_set_header X-Forwarded-Proto $scheme;). The rules are strict on purpose:

The gRPC CreateApiToken RPC applies the same list, reading the x-forwarded-proto and forwarded metadata keys. Unlike HTTP it always refuses an unprotected mint, whatever apiTokenRequireSecureTransport says.

This command allows executing idempotent commands, like SELECT and MATCH:

URL Syntax GET: /api/v1/query/{database}/{language}/{command}

URL Syntax POST: /api/v1/query/{database}

Where:

When using the GET variant the query needs to be URL encoded.

These restrictions do not apply to the POST variant, where the language and command are send in the body.

(Since v26.10.2.) A SQL statement is classified by everything it runs, not only by its outermost statement. A write nested in a LET, a projection, a FROM subquery, a CASE, a RETURN or a script block (IF, FOREACH, WHILE) makes the whole statement a write, so /api/v1/query refuses it with 400 (the query is not idempotent) and writes nothing, for example SELECT FROM Account LET $x = (INSERT INTO Log SET a = 1) or SELECT FROM (INSERT INTO Log SET a = 1). Send such a statement to /api/v1/command. A nested read, such as SELECT $c FROM Account LET $c = (SELECT count(*) FROM Account), still runs. In v26.10.1 and earlier these nested writes ran through the query endpoint.

EXPLAIN is answered the same way by the GET and the POST variants and by /api/v1/command: the plan arrives in the explain (indented text) and explainPlan (structured) members of the response envelope, and result is empty — the plan is the answer, not a row. Requesting it with Accept: application/x-ndjson is refused with 400 ("EXPLAIN produces a plan, not a row stream"), because a stream of rows plus a stats trailer has nowhere to carry one. Before 26.10.1 the GET variant reached neither rule: it serialized the plan as an ordinary result row, and streamed it as an ndjson record line that no consumer of that encoding can read.

With Accept: application/x-ndjson the rows are streamed one per line (record), followed by a stats trailer. While the server is still producing the next row it writes an empty line every arcadedb.server.httpStreamingKeepAliveInterval milliseconds (default 5000, 0 disables), so a client that bounds silence does not mistake a slow query for a dead server. Consumers must ignore blank lines, which the Java driver does. The Java driver fails a stream after arcadedb.network.socketTimeout of silence, with a minimum of 30 seconds, as for any other call.

A failure after the stream has started cannot change the 200 status line, so it is reported in-band as a last error line instead of the stats trailer: {"error": {…​}}. It carries what the buffered response would have answered the same failure with:

Key on status, exception and retryAfter rather than parsing message. A stream that ends with neither a stats nor an error line did not arrive complete.

Responses:

Example:

The query endpoint may also be used via the POST method, which has no character restrictions such as / or ?:

The POST variant accepts additional parameters in the JSON body:

Example of forcing a transaction for a query to ensure consistent reads:

Executes a non-idempotent command (as an implicit transaction).

URL Syntax: /api/v1/command/{database}

Where:

Example to create the new document type "Class":

The payload, as a JSON, accepts the following parameters:

Responses:

Example of insertion of a new Client by using parameters:

Example of forcing an atomic transaction with autoCommit:

Example of disabling automatic transaction wrapping:

When a command modifies data, the POST /api/v1/command/{database} response includes a stats object alongside result, reporting how many entities the command created, deleted or changed. The object is omitted for read-only queries (a command that changes nothing has no stats field). It is populated for OpenCypher writes — including counts aggregated across UNION branches and CALL { …​ } subqueries — and mirrors the counters the Bolt driver exposes through its result summary.

The shape is an ArcadeDB-native camelCase object with a stable set of keys (each counter is always present, 0 when unused):

Example — a Cypher write returns the counters it produced:

The gRPC service carries the same counters in the write-result summary of ExecuteCommand; see gRPC API.

params given as a JSON array (or as an object keyed "0", "1", …​) binds its values by position. With SQL their number must match the placeholders of the statement: each ?, and each :name bound positionally, takes exactly one value (send null explicitly to bind a null), and in a sqlscript the placeholders of all its statements are counted together. A Postgres-style $N reads the value at position N and may leave lower positions unread. A request that does not match is refused with 400 before the statement runs (CommandSQLParsingException, the message names both counts). A list meant for one placeholder is one value, a nested array:

Named parameters (a JSON object with names as keys) are not counted. See also the Java API.

JSON has no native byte[] type, so HTTP/JSON clients cannot send binary parameters with the standard scalar/array shapes. The query and command endpoints recognise two reserved single-key marker objects in any parameter value (named or positional) and decode them to a Java byte[] before the parameter binder sees them. The primary use case is sending an INT8-encoded vector to a LSM_VECTOR index without the float32 round trip — see Vector Encoding.

A single-key map whose key is one of these is decoded; multi-key maps that happen to contain a $bytes or $int8 key are passed through unchanged so user data with leading-$ keys is not silently transformed. The decoder also recurses into nested arrays and maps, so a list of typed markers (e.g. a batch of int8 vectors as a single parameter) works.

Examples:

Malformed markers (invalid base64, non-numeric $int8 element, value out of [-128, 127], null payload) return 400 Bad Request with a message naming the marker and the offending value.

(Since v26.10.1) Returns the nearest neighbors of a query vector in a dense LSM_VECTOR or sparse LSM_SPARSE_VECTOR index, without writing the vector.neighbors SQL by hand. ArcadeDB does not compute embeddings: the caller supplies the vector. The same request body and limits apply to the MCP vector_search tool and the gRPC VectorSearch RPC.

URL Syntax: /api/v1/vector/{database}/search

The JSON body accepts:

The response carries:

Responses:

The route runs without a transaction. A 400 caused by a bad argument does not roll back a transaction the client opened with /begin.

Example:

Return:

(Since v26.10.1) Fuses a vector leg, an optional full-text leg and an optional graph expansion leg into one ranked list, using the engine’s vector.fuse function. The same request body and limits apply to the MCP hybrid_search tool and the gRPC HybridSearch RPC.

URL Syntax: /api/v1/vector/{database}/hybrid

The JSON body accepts:

The response carries vectorIndexName, sparse, scoring, fused, truncated, count, results, plus:

Fusion needs at least two legs that returned rows. When only the vector leg did, fused is false and each hit carries the native distance (dense) or score (sparse) instead of a fused score. Otherwise each hit has rid, fusedScore (higher is better), sources (the legs that produced it: vector, fulltext, expand) and properties, plus depth and path (RIDs from the seed, seed included) for a hit found by the expansion.

Responses:

Example:

Return (abridged):

(Since v26.10.1) Runs a Lucene-syntax query against a FULL_TEXT index and returns the matching documents, highest score first (ties ordered by RID). The same request body and limits apply to the MCP full_text_search tool and the gRPC FullTextSearch RPC.

URL Syntax: /api/v1/vector/{database}/fulltext

The JSON body accepts:

One of indexName or typeName is required. The response carries indexName, similarity (BM25 or CLASSIC), count and results, where each hit has rid, score and properties. The limit is applied per bucket, so a record deleted between the index scan and the load is skipped rather than replaced, and a search can return fewer than limit hits.

Responses:

Example:

Return:

Begins a transaction on the server managed as a session. The response header contains the session id. Set this id in the following requests to execute them in the same transaction scope. See also /commit and /rollback.

URL Syntax: /api/v1/begin/{database}

Where:

The payload, optional as a JSON object, accepts the following parameters:

A request without a body, or with a blank one, begins the transaction at the database default isolation level. A body that is not a valid JSON object (truncated, garbled, a scalar or a top-level array) is refused with 400 and no transaction is started: it is never taken as "no body", so a client that meant to ask for REPEATABLE_READ cannot silently get READ_COMMITTED.

Responses:

Example:

Returns the Session Id in the response header, example:

arcadedb-session-id: AS-ee056170-dc9b-4956-8d71-d7cfa01900d4

Use the session id in the request header of further commands you want to execute in the same transaction and execute /commit to commit the server side transaction or /rollback to rollback the changes. After a period of inactivity (default is 30 seconds), the server automatically rollback and purge expired transactions.

Commits a transaction on the server. Set the session id obtained with the /begin command as a header of the request. See also /begin and /rollback.

URL Syntax: /api/v1/commit/{database}

Where:

Set the session id returned from the /begin command in the request header. If the session (and therefore the server side transaction) is unknown, expired or already ended, 404 is returned: nothing was committed.

The commit ends the session, whether it succeeds or fails: a commit that fails rolls the transaction back, and the answer carries the header arcadedb-session-closed: true, so there is no need to send a /rollback afterwards. (Since v26.10.1: before, the session of a failed commit stayed registered until it timed out.)

A command that fails inside a session rolls the session’s transaction back. When the transaction held changes, they are lost, so the session is marked as rolled back: the next command naming it is refused with 404, and /commit answers 404 with a message saying that the transaction was rolled back, instead of 204. Send a /rollback (or the /commit) to end it. When nothing was lost (a failed read, an error before the first write) the session goes on in a fresh transaction. (Since v26.10.1: before, the commands after the failure ran in autocommit and /commit answered 204.)

A /commit retried while the first one is still running (a client that timed out and sent it again) waits up to 5 seconds for the first one to finish, then answers 204 if that commit succeeded and 404 if it failed. A retry that reaches another server, or arrives after a restart, cannot know the outcome and answers 404: send an X-Request-Id to make a retry safe in every case. (Since v26.11.1: before, the retry answered 404 even when the first commit succeeded.)

Response:

Example:

Rollbacks a transaction on the server. Set the session id obtained with the /begin command as a header of the request. See also /begin and /commit.

URL Syntax: /api/v1/rollback/{database}

Where:

Set the session id returned from the /begin command in the request header. If the session (and therefore the server side transaction) is expired, then an internal server error is returned.

The commit ends the session, whether it succeeds or fails: a commit that fails rolls the transaction back, and the answer carries the header arcadedb-session-closed: true, so there is no need to send a /rollback afterwards. (Since v26.10.1: before, the session of a failed commit stayed registered until it timed out.)

Response:

Example:

High-performance bulk import of vertices and edges using the GraphBatch engine under the hood. Supports JSONL and CSV input formats with streaming parsing — the server never loads the entire request body into memory, so you can push millions of records in a single request.

URL Syntax: /api/v1/batch/{database}

Where:

The Content-Type header determines the input format: