HTTP / JSON from JavaScript

Connecting to ArcadeDB from JavaScript / TypeScript

  • Native HTTP driver — npm install @arcadedb/driver, generated from ArcadeDB’s OpenAPI contract. Start here for most applications.

  • Native gRPC driver — npm install @arcadedb/driver-grpc, for streaming and bulk inserts.

  • PostgreSQL wire protocol — npm install pg, run SQL through a driver you may already have.

  • Neo4j BOLT — npm install neo4j-driver, run Cypher queries.

This page covers the remaining option: calling the HTTP/JSON API directly, with no driver at all.

ArcadeDB’s HTTP/JSON API is reachable from any HTTP client, so JavaScript can talk to it with nothing installed. Prefer @arcadedb/driver when you can — it gives you typed results, transactions, and error handling for one dependency. Reach for raw HTTP when you cannot add a dependency at all: a serverless function you want to keep cold-start-free, a build script, or a quick probe.

See the HTTP/JSON API reference for every endpoint and parameter.

Using fetch

fetch is built into Node.js 18 and later, and into every current browser — so this needs no packages.

const base = 'http://localhost:2480/api/v1';
const auth = 'Basic ' + Buffer.from('root:playwithdata').toString('base64');

const response = await fetch(`${base}/command/mydb`, {
  method: 'POST',
  headers: {
    Authorization: auth,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    language: 'sql',
    command: 'SELECT FROM Person LIMIT 10',
  }),
});

if (!response.ok) {
  throw new Error(`${response.status} ${await response.text()}`);
}

const data = await response.json();
console.log(data.result);
[
  {
    '@rid': '#1:0',
    '@type': 'Person',
    '@cat': 'v',
    name: 'Alice',
    age: 30
  }
]

Buffer is Node-only; in a browser, build the same header with btoa('root:playwithdata').

Two things worth knowing. fetch does not throw on an HTTP error status — a 401 or a 500 resolves normally, and only a network failure rejects — so check response.ok yourself, as above. And fetch has no timeout at all: wrap the call with signal: AbortSignal.timeout(5000) if a hung connection would be worse than a failed one.

The response is the full envelope, not a bare array: result holds the rows, alongside limit, returned, and truncated. A truncated of true means the server stopped serializing before the result set ended, so result is a partial answer that looks exactly like a complete one — see Native Drivers for what to do about it.

Using axios

axios handles the base64 encoding and throws on non-2xx responses, which is the main reason to prefer it over fetch here.

npm install axios
import axios from 'axios';

const res = await axios.post(
  'http://localhost:2480/api/v1/command/mydb',
  { language: 'sql', command: 'SELECT FROM Person LIMIT 10' },
  { auth: { username: 'root', password: 'playwithdata' } },
);

console.log(res.data.result);
[
  {
    '@rid': '#1:0',
    '@type': 'Person',
    '@cat': 'v',
    name: 'Alice',
    age: 30
  }
]

TypeScript

Both examples are valid TypeScript as written, and need no type packages beyond the @types/node a Node project already has: fetch and Buffer come from it, and axios ships its own types. Annotate the response shape yourself if you want the rows typed:

interface QueryResponse<T> {
  result: T[];
  limit: number;
  returned: number;
  truncated: boolean;
}

const data = (await response.json()) as QueryResponse<{ name: string; age: number }>;

Further Reading