HTTP/JSON API

Overview Endpoints

Action Method Endpoint

Get OpenAPI definition

GET

/api/v1/openapi.json

Get server status

GET

/api/v1/ready

Get server information

GET

/api/v1/server

Send server command

POST

/api/v1/server

List databases

GET

/api/v1/databases

Does database exist

GET

/api/v1/exists/{database}

Login (get auth token)

POST

/api/v1/login

Logout (invalidate token)

POST

/api/v1/logout

List active sessions

GET

/api/v1/sessions

Execute a query

GET

/api/v1/query/{database}/{language}/{query}

Execute a query

POST

/api/v1/query/{database}

Execute database command

POST

/api/v1/command/{database}

Begin a new transaction

POST

/api/v1/begin/{database}

Commit a transaction

POST

/api/v1/commit/{database}

Rollback a transaction

POST

/api/v1/rollback/{database}

Batch import vertices and edges

POST

/api/v1/batch/{database}

Overview Query & Command Parameters

Parameter Type Values

language

Required

sql, sqlscript, graphql, cypher, gremlin, mongo, and others

command

Required

encoded command string

awaitResponse

Optional

set synchronous (true, default) or asynchronous (false) command

limit

Optional

maximum number of results

params

Optional

map of parameters

serializer

Optional

graph, record, studio

autoCommit

Optional

Boolean. true to force atomic transaction, false to disable, omit for automatic behavior

Introduction

The ArcadeDB Server is accessible from the remote through the HTTP/JSON protocol. The protocol is very simple. For this reason, you don’t need a driver, because every modern programming language provides an easy way to execute HTTP requests and parse JSON.

For the examples in this chapter we’re going to use curl. Every request must be authenticated by passing user and password as HTTP basic authentication (in HTTP Headers). In the examples below we’re going to always use "root" user with password "arcadedb-password".

Under Windows (Powershell) single and double quotes inside a single or double quoted string need to be replaced with their Unicode entity representations \u0022 (double quote) and \u0027 (single quote). This is for example the case in the data argument (-d) of POST requests.

Token-Based Authentication

Available since version 26.2.1.

In addition to HTTP Basic Authentication, ArcadeDB supports token-based authentication. This allows you to login once with credentials and receive a token that can be used for subsequent requests, avoiding the need to send username and password with every request.

This is particularly useful when:

  • Building applications that make multiple API calls

  • You want to avoid storing credentials in your application

  • You need to manage user sessions with explicit logout capability

Authentication Flow:

  1. Call POST /api/v1/login with Basic Auth credentials to obtain a token

  2. Use the token in subsequent requests via Authorization: Bearer <token> header

  3. Call POST /api/v1/logout to invalidate the token when done

Example workflow:

# 1. Login and get a token
$ curl -X POST http://localhost:2480/api/v1/login \
       --user root:arcadedb-password

# Response: {"token":"AU-2af64e60-8455-423a-bc64-ed0e19729f04","user":"root"}

# 2. Use the token for subsequent requests
$ curl http://localhost:2480/api/v1/query/mydb/sql/select%201 \
       -H "Authorization: Bearer AU-2af64e60-8455-423a-bc64-ed0e19729f04"

# 3. Logout when done
$ curl -X POST http://localhost:2480/api/v1/logout \
       -H "Authorization: Bearer AU-2af64e60-8455-423a-bc64-ed0e19729f04"

Authentication tokens expire after a configurable period of inactivity (default is 30 minutes). See server.httpAuthSessionExpireTimeout to configure this timeout.

Server-Side Transactions

ArcadeDB implements server-side transaction over HTTP stateless protocol by using sessions. A session is created with the /begin request and returns a 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 request /commit to commit the server side transaction or /rollback to rollback the changes. After a period of inactivity (default is 30 seconds, see server.httpTxExpireTimeout), the server automatically rolls back and purges expired transactions.

Transaction Scripts

In case SQL (sql) is supposed to be used as language for a transactions, the language variant SQL Script (sqlscript) is also available. A sqlscript can consist of one or multiple SQL statements, which is collectively treated as a transaction. Hence, for such a batch of SQL statements, no begin and commit commands are necessary, since begin and commit implicitly enclose any sqlscript command.

Streaming Change Events

This feature only works on the server where changes are executed. In a replicated environment, the changes executed on other servers would not fire events on all the servers in the cluster, but only on the local server. The cluster support is coming soon.

The Java API supports real-time change notifications, which the HTTP API implements via a websocket. You can opt into notifications for all changes that occur on a database, or filter by the operation (i.e. create, update, delete) or underlying entity type.

To connect, point your favorite WebSocket client to the ws://SERVER:PORT/ws endpoint. You will need to authenticate with HTTP Basic, which for some clients (like most browsers) is only possible via the URI, like this: ws://USERNAME:PASSWORD@SERVER:PORT/ws. Others will require that you set the Authorization header directly. Check the documentation for your client of choice for details.

To subscribe/unsubscribe to change events, send JSON messages using the following structure:

Property Required Description

action

Required

subscribe or unsubscribe.

database

Required

The database name.

type

Optional

The entity type to filter by.

changeTypes

Optional

Array of change types you’d like to receive. Must be create, update, or delete.

Example: to subscribe to all changes (create, update, delete) for the type Movie in the database movies, use:

{"action": "subscribe", "database": "movies", "type": "Movie"}

If instead, you only want updates, send:

{"action": "subscribe", "database": "movies", "type": "Movie", "changeTypes": ["update"]}

If you want every change on the database (use with caution!):

{"action": "subscribe", "database": "movies"}

Once subscribed, you will get JSON messages for any matching changes with the following properties:

Property Description

database

The source database.

changeType

create, update or delete.

record

The full record that generated the change event.

Responses

The server answers a HTTP request with a response. This response can have a body, which will always be in the JSON format. Generally, a successful response (HTTP status codes 2xx) contains a result field, while an erroneous request (HTTP status code 4xx) has an error field, and a server error (HTTP status code 5xx), in addition to the error field, provides a detail and an exception field.

Tutorial

Let’s first create an empty database "school" on the server:

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "create database school"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Now let’s create the type "Class":

$ curl -X POST http://localhost:2480/api/v1/command/school \
       -d '{"language": "sql", "command": "create document type Class"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

We could insert our first Class by using SQL:

$ curl -X POST http://localhost:2480/api/v1/command/school \
       -d '{"language": "sql", "command": "insert into Class set name = '\''English'\'', location =  '\''3rd floor'\''"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Or better, using parameters with SQL:

$ curl -X POST http://localhost:2480/api/v1/command/school \
       -d '{"language": "sql", "command": "insert into Class set name = :name, location = :location", "params": {"name": "English", "location": "3rd floor"}}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Reference

Get OpenAPI Definition (GET)

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

URL Syntax: /api/v1/openapi.json

Response:

Example:

$ curl -X GET "http://localhost:2480/api/v1/openapi.json"

Return:

{"openapi":"3.0.3", ... }

Check if server is ready (GET)

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

URL Syntax: /api/v1/ready

This endpoint accepts (GET) requests without authentication, and is useful for remote monitoring of server readiness.

Response:

Example:

$ curl -I -X GET "http://localhost:2480/api/v1/ready"

Return:

HTTP/1.1 204 OK

Get server information (GET)

Returns the current configuration.

URL Syntax: /api/v1/server

The following mode query parameter values are available:

  • basic returns minimal server information.

  • default returns full server configuration (default value when no parameter is given).

  • cluster returns cluster layout.

Responses:

  • 200 OK

  • 403 invalid credentials

Example:

$ curl -X GET "http://localhost:2480/api/v1/server?mode=basic" \
       --user root:arcadedb-password

Return:

{"version": "26.5.1", "serverName": "ArcadeDB_0"}

Send server command (POST)

Sends control commands to server.

URL Syntax: /api/v1/server

The following commands are available:

  • list databases returns the list of databases installed in the server

  • create database <dbname> creates database with name dbname

  • drop database <dbname> deletes database with name dbname

  • open database <dbname> opens database with name dbname

  • close database <dbname> closes database with name dbname

  • create user { "name": "<username>", "password": "<password>", "databases": { "<dbname>": "admin", "<dbname>": "admin" } } creates user credentials username and password and admin access to databases dbname.

  • drop user <username> deletes user username

  • get server events [<filename>] returns a list of server events, optionally a filename of the form server-event-log-yyyymmdd-HHMMSS.INDEX.jsonl (where INDEX is a integer, i.e. 0) can be given to retrieve older event logs

  • shutdown kills the server gracefully.

  • set server setting <key> <value> sets the server setting with key to value, see the list of server-level settings

  • set database setting <dbname> <key> <value> sets the database’s <dbname> with key to value, see the list of database-level settings

  • connect cluster <address> connects this server to a cluster with address

  • disconnect cluster disconnects this server from a cluster

  • align database <dbname> aligns database <dbname>, see the associated SQL command

  • restore database <dbname> <url> restores a database from a backup file. The URL can be a local path (file://), HTTP/HTTPS URL, or classpath resource. The database must not already exist. See how-to/operations/restore.adoc#restore.

  • import database <dbname> <url> creates a new database and imports data from the given URL (OrientDB export, GraphML, GraphSON, CSV, JSON). Combines create database and IMPORT DATABASE in a single command.

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.

Only root users can run these command, except the list databases command, which every user can run, and this user’s accessible databases are listed.

Responses:

  • 200 OK

  • 400 invalid command

  • 403 invalid credentials

  • 500 invalid JSON request body

Examples:

List databases

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "list databases"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": ["school", "mydatabase"]}

Create database

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "create database mydatabase"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Drop database

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "drop database mydatabase"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Open database

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "open database mydatabase"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Close database

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "close database mydatabase"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Restore database

Restores a database from a backup file (local or remote). This is the fastest way to provision a database from a backup archive.

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "restore database mydatabase https://example.com/backups/mydatabase.zip"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Restoring from a local file:

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "restore database mydatabase file:///path/to/mydatabase-backup.zip"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Create user

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "create user {\"name\": \"myuser\", \"password\": \"mypassword\", \"databases\": {\"mydatabase\": \"admin\"}}"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Drop user

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "drop user myuser"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Shutdown server

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "shutdown"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Get server events

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "get server events"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": [{"time": "2023-06-18 15:37:40.378", "type": "INFO", "component": "Server", "message": "ArcadeDB Server started in \u0027development\u0027 mode (CPUs\u003d8 MAXRAM\u003d4,00GB)"}]}

Set server setting

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "set server setting arcadedb.server.name player0"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Set database setting

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "set database setting mydb arcadedb.flushOnlyAtClose true"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Connect cluster

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "connect cluster 192.168.0.1"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Disconnect cluster

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "disconnect cluster"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

Align database

$ curl -X POST http://localhost:2480/api/v1/server \
       -d '{"command": "align database mydb"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Return:

{"result": "ok"}

List Databases (GET)

Returns a list of available databases for the requesting user.

URL Syntax: /api/v1/databases

Responses:

  • 200 OK

  • 403 invalid credentials

Example:

$ curl -X GET http://localhost:2480/api/v1/databases \
       --user root:arcadedb-password

Return:

{"result": ["school", "mydatabase"]}

Does database exist (GET)

Returns boolean answering if database exists.

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

Responses:

  • 200 OK

  • 400 no database passed

Example:

$ curl -X GET http://localhost:2480/api/v1/exists/school \
       --user root:arcadedb-password

Return:

{"result": true}

Login - Get Authentication Token (POST)

Available since version 26.2.1.

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:

  • 200 OK - returns token and username

  • 403 invalid credentials

Example:

$ curl -X POST http://localhost:2480/api/v1/login \
       --user root:arcadedb-password

Return:

{"token": "AU-2af64e60-8455-423a-bc64-ed0e19729f04", "user": "root"}

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

$ curl http://localhost:2480/api/v1/databases \
       -H "Authorization: Bearer AU-2af64e60-8455-423a-bc64-ed0e19729f04"

Logout - Invalidate Authentication Token (POST)

Available since version 26.2.1.

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:

  • 204 OK - token invalidated (or was already invalid)

Example:

$ curl -X POST http://localhost:2480/api/v1/logout \
       -H "Authorization: Bearer AU-2af64e60-8455-423a-bc64-ed0e19729f04"

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

List Active Authentication Sessions (GET)

Available since version 26.2.1.

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:

  • 200 OK - returns list of active sessions

  • 403 forbidden (non-root user)

Example:

$ curl http://localhost:2480/api/v1/sessions \
       --user root:arcadedb-password

Return:

{
  "result": [
    {
      "token": "AU-2af64e60-8455-423a-bc64-ed0e19729f04",
      "user": "root",
      "elapsedMs": 12345
    },
    {
      "token": "AU-6fa459ea-ee8a-3ca4-894e-db77e160355e",
      "user": "admin",
      "elapsedMs": 5678
    }
  ],
  "count": 2
}

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

Execute a query (GET|POST)

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:

  • database is the database name

  • language is the query language used. is the query language used, between "sql", "sqlscript", "graphql", "cypher", "gremlin", "mongo" and any other language supported by ArcadeDB and available at runtime.

  • command the command to execute in encoded format

  • params (optional), is the map of parameters to pass to the query engine via the POST body, where parameters are introduced with a colon :.

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

Due to security reasons (encoded) slashes / (%2F) which are used for divisions or block comments, cannot be used in queries via the GET method with the query/ endpoint.
Question marks (?) cause the server to stop reading the query string when sent via GET. To use question marks (inside strings) one can use format('%c',63); in this case make sure to replace all percent symbols (%) in the format string with %%.

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

Even though a POST method is used, the query in command has to be idempotent.

Responses:

  • 200 OK

  • 400 invalid language, invalid query

  • 403 invalid credentials

  • 500 database does not exist, cannot execute query

Example:

$ curl -X GET http://localhost:2480/api/v1/query/school/sql/select%20from%20Class \
       --user root:arcadedb-password

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

$ curl -X POST http://localhost:2480/api/v1/query/school \
       -d '{"language": "sql", "command": "select from Class"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

The POST variant accepts additional parameters in the JSON body:

  • autoCommit (optional) controls transaction behavior (same as in Execute database command):

    • true: Forces the query to execute within an atomic transaction

    • false: Disables transaction wrapping (query executes directly)

    • not specified: Uses automatic behavior (no transaction for read-only queries)

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

$ curl -X POST http://localhost:2480/api/v1/query/mydb \
       -d '{"language": "sql", "command": "SELECT FROM Account WHERE balance > 1000", "autoCommit": true}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Execute database command (POST)

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

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

Where:

  • database is the database name

Example to create the new document type "Class":

$ curl -X POST http://localhost:2480/api/v1/command/school \
       -d '{"language": "sql", "command": "create document type Class"}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

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

  • language is the query language used, between "sql", "sqlscript", "graphql", "cypher", "gremlin", "mongo" and any other language supported by ArcadeDB and available at runtime.

  • command the command to execute in encoded format

  • awaitResponse (optional) a boolean which is by default "true", if set to "false" the command will be executed asynchronously and only acknowledgement of receiving the command is responded. The completion of the command is noted in the log, yet no results of the command can be returned.

  • limit (optional) is the maximum number of results to return

  • params (optional), is the map of parameters to pass to the query engine, where parameters are prefixed with a colon :.

  • retries (optional), is the number of times the command (transaction) is retried.

  • autoCommit (optional) controls transaction behavior:

    • true: Forces the command to execute within an atomic transaction that auto-commits on success

    • false: Disables automatic transaction wrapping (command executes directly without transaction)

    • not specified (default): Uses automatic behavior (commands are wrapped in atomic transactions unless a session is active)

    • NOTE: This parameter is ignored when using session-based transactions (see Begin a transaction). If you provide autoCommit: true with an active session, a warning will be logged and the session transaction will be used instead.

  • serializer (optional) specify the serializer used for the result:

    • graph: returns a graph separating vertices from edges

    • record: returns everything as records

    • studio: by default it’s like record but with additional metadata for vertex records, such as the number of outgoing edges in @out property and total incoming edges in @in property. This serializer is used by Studio.

Asynchronous commands (using "awaitResponse": false) are queued, and their processing is configurable via async* database settings.

Responses:

  • 200 OK

  • 202 Accepted

  • 400 invalid language, invalid command

  • 403 invalid credentials

Example of insertion of a new Client by using parameters:

$ curl -X POST http://localhost:2480/api/v1/command/company \
       -d '{"language": "sql", "command": "create vertex Client set firstName = :firstName, lastName =  :lastName", params: {"firstName": "Jay", "lastName": "Miner"}}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Example of forcing an atomic transaction with autoCommit:

$ curl -X POST http://localhost:2480/api/v1/command/mydb \
       -d '{"language": "sql", "command": "INSERT INTO Account SET balance = 1000", "autoCommit": true}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Example of disabling automatic transaction wrapping:

$ curl -X POST http://localhost:2480/api/v1/command/mydb \
       -d '{"language": "sql", "command": "SELECT FROM Account LIMIT 1", "autoCommit": false}' \
       -H "Content-Type: application/json" \
       --user root:arcadedb-password

Begin a transaction (POST)

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:

  • database is the database name

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

  • isolationLevel is the isolation level for the current transaction, either READ_COMMITTED (default) or REPEATABLE_READ.

Responses:

  • 204 OK

  • 400 invalid value

  • 401 transaction already started

  • 403 invalid credentials

  • 500 invalid database, invalid JSON, invalid body

Example:

$ curl -I -X POST http://localhost:2480/api/v1/begin/school \
       --user root:arcadedb-password

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.

Commit a transaction (POST)

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:

  • database is the database name

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.

Response:

  • 204 OK

  • 403 invalid credentials

  • 500 transaction expired, not found, not begun

Example:

$ curl -I -X POST http://localhost:2480/api/v1/commit/school \
       -H "arcadedb-session-id: AS-ee056170-dc9b-4956-8d71-d7cfa01900d4" \
       --user root:arcadedb-password

Rollback a transaction (POST)

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:

  • database is the database name

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.

Response:

  • 204 OK

  • 403 invalid credentials

  • 500 transaction expired, not found, not begun

Example:

$ curl -I -X POST http://localhost:2480/api/v1/rollback/school \
       -H "arcadedb-session-id: AS-ee056170-dc9b-4956-8d71-d7cfa01900d4" \
       --user root:arcadedb-password

Batch import vertices and edges (POST)

Available since ArcadeDB 26.4.1.

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:

  • database is the database name

The Content-Type header determines the input format:

  • application/x-ndjson or application/jsonl — JSONL (newline-delimited JSON)

  • text/csv — CSV

All vertices must appear before edges in the request body. Edges reference vertices either by temporary ID or by existing database RID.

JSONL Format

Each line is a JSON object with the following meta fields:

Field Required Description

@type

Yes

"vertex" (or "v") for vertices, "edge" (or "e") for edges

@class

Yes

The vertex or edge type name (must exist in schema)

@id

No

Client-assigned temporary ID for vertices. Used by edges to reference newly created vertices.

@from

Edges only

Source vertex reference: a temporary ID (e.g., "t1") or an existing RID (e.g., "#12:0")

@to

Edges only

Destination vertex reference: a temporary ID or an existing RID

All other fields are treated as properties.

Example:

{"@type":"vertex","@class":"Person","@id":"t1","name":"Alice","age":30}
{"@type":"vertex","@class":"Person","@id":"t2","name":"Bob","age":25}
{"@type":"edge","@class":"KNOWS","@from":"t1","@to":"t2","since":2020}
{"@type":"edge","@class":"KNOWS","@from":"#12:0","@to":"t2","weight":0.8}

CSV Format

The first line is the column header. A --- sentinel row separates the vertex section from the edge section, followed by a new header row for edges.

Example:

@type,@class,@id,name,age
vertex,Person,t1,Alice,30
vertex,Person,t2,Bob,25
---
@type,@class,@from,@to,since
edge,KNOWS,t1,t2,2020

CSV parsing supports RFC 4180 quoting (double-quote escaping). Numeric values are auto-detected as integers or floats. Boolean values (true/false) are also auto-detected.

Query Parameters

All parameters are optional and map directly to GraphBatch builder options:

Parameter Default Description

batchSize

100000

Maximum edges buffered before auto-flush

lightEdges

false

If true, property-less edges are stored as connectivity only (saves ~33% I/O)

wal

false

Enable Write-Ahead Logging for crash safety

parallelFlush

true

Parallelize edge connection across async threads

preAllocateEdgeChunks

true

Pre-allocate edge segments on vertex creation

edgeListInitialSize

2048

Initial segment size in bytes (64-8192)

bidirectional

true

Connect both outgoing and incoming edges

commitEvery

50000

Edges per sub-transaction within a flush

expectedEdgeCount

0

Hint for auto-tuning batch size

Response

The response is a JSON object with import statistics:

{
  "verticesCreated": 2,
  "edgesCreated": 1,
  "elapsedMs": 42,
  "idMapping": {
    "t1": "#9:0",
    "t2": "#9:1"
  }
}

The idMapping field is included only when temporary IDs (@id) were used. It maps each temporary ID to the actual RID assigned by the database.

Responses:

  • 200 OK

  • 400 invalid input format, missing required fields, unknown temporary ID, vertices after edges

  • 403 invalid credentials

This endpoint is NOT atomic by design. The underlying GraphBatch commits internally in chunks for maximum throughput. The response tells you exactly how many records were committed. Treat it as a bulk-loading operation, not a transactional one.
For maximum throughput, group vertices by type in the input. The endpoint batches consecutive same-type vertices into a single createVertices() call. Interleaving types forces smaller, less efficient batches.

Examples

JSONL import with light edges:

$ curl -X POST "http://localhost:2480/api/v1/batch/mydb?lightEdges=true" \
       -H "Content-Type: application/x-ndjson" \
       --data-binary @graph-data.jsonl \
       --user root:arcadedb-password

CSV import:

$ curl -X POST http://localhost:2480/api/v1/batch/mydb \
       -H "Content-Type: text/csv" \
       --data-binary @graph-data.csv \
       --user root:arcadedb-password

Inline JSONL with WAL enabled:

$ curl -X POST "http://localhost:2480/api/v1/batch/mydb?wal=true" \
       -H "Content-Type: application/x-ndjson" \
       --user root:arcadedb-password \
       -d '{"@type":"vertex","@class":"Person","@id":"p1","name":"Alice"}
{"@type":"vertex","@class":"Person","@id":"p2","name":"Bob"}
{"@type":"edge","@class":"KNOWS","@from":"p1","@to":"p2"}'

Python example:

import requests

data = (
    '{"@type":"vertex","@class":"Person","@id":"p1","name":"Alice"}\n'
    '{"@type":"vertex","@class":"Person","@id":"p2","name":"Bob"}\n'
    '{"@type":"edge","@class":"KNOWS","@from":"p1","@to":"p2"}\n'
)

resp = requests.post(
    "http://localhost:2480/api/v1/batch/mydb?lightEdges=true",
    auth=("root", "arcadedb-password"),
    headers={"Content-Type": "application/x-ndjson"},
    data=data,
)
print(resp.json())
# {'verticesCreated': 2, 'edgesCreated': 1, 'elapsedMs': 15, 'idMapping': {'p1': '#9:0', 'p2': '#9:1'}}

JavaScript (Node.js) example:

const resp = await fetch("http://localhost:2480/api/v1/batch/mydb", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-ndjson",
    "Authorization": "Basic " + btoa("root:arcadedb-password"),
  },
  body: [
    '{"@type":"vertex","@class":"Person","@id":"p1","name":"Alice"}',
    '{"@type":"vertex","@class":"Person","@id":"p2","name":"Bob"}',
    '{"@type":"edge","@class":"KNOWS","@from":"p1","@to":"p2"}',
  ].join("\n"),
});
console.log(await resp.json());