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:

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.

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.

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.

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, accepts the following parameters:

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

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

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: