REST & realtime API

The VOLT server exposes a JSON API under /api and a Socket.IO endpoint at /socket.io on the same origin. The web app uses both. Your programs use the API with a team secret key, directly or through the TypeScript and Python SDKs.

The routes are declared in packages/shared/contracts/src/modules/<module>/routes.ts. The server mounts exactly those, and the client calls them, so that directory is the authoritative list, with each route's input and output types next to it.

Authentication

Protected routes take a bearer token in the Authorization header. The API reads credentials from that header only.

Authorization: Bearer <token>

There are two kinds of token, and the server tells them apart by the vsk_ prefix:

A secret key works only on its own team's routes; any other /api/teams/:teamId/… answers 403 Team::AccessDenied. Every request made with a key is logged for its usage metrics (GET /api/teams/:teamId/secret-keys/:secretKeyId/usage). GET /api/teams/secret-keys/me returns the key you call it with, including its team, role, name and keyPrefix; it is how a program learns its team ID.

VOLT=https://volt.example.com
KEY=vsk_...

TEAM=$(curl -s -H "Authorization: Bearer $KEY" "$VOLT/api/teams/secret-keys/me" | jq -r .data.team)
curl -s -H "Authorization: Bearer $KEY" "$VOLT/api/teams/$TEAM/trajectories?page=1&limit=20"

A few routes take no token: GET /api/system/config (the deployment mode), the sign-in and sign-up routes, and the /api/public/… routes, which serve public trajectories and accept a token when there is one. The server also answers GET /healthz outside /api.

Responses

A successful response is an envelope with the data under data:

{ "status": "success", "data": { "...": "..." } }

A route that returns nothing answers 204 with no body. A list answers with a page of results and its pagination:

{
  "status": "success",
  "data": [{ "_id": "...", "...": "..." }],
  "pagination": { "page": 1, "limit": 20, "total": 57, "totalPages": 3, "hasMore": true },
  "_meta": {}
}

Lists take page (1-based, default 1) and limit query parameters. Each route sets its default limit and caps it. _meta carries extra information some lists add, such as the columns of a listing.

An error has the same envelope with status: "error", a stable code of the form Module::Reason and the HTTP status:

{ "status": "error", "code": "Authentication::Required", "message": "Authentication::Required", "statusCode": 401 }

A path the server does not have answers Express's own 404 page, which is HTML.

Route groups

Team-scoped resources live under /api/teams/:teamId/. The groups below follow the contract modules.

Write routes follow the same shape: a resource's sub-collection names the action, as in POST …/secret-keys/:secretKeyId/revocations or POST …/plugins/registry/installations with { "name": "@voltlabs/opendxa", "version": "2.5.1" }.

Realtime: Socket.IO

The server runs a Socket.IO server on its HTTP port at the default path, /socket.io, with the websocket and polling transports. The web app uses it for live job lists, analysis logs, presence, collaboration on the canvas and whiteboards, VOLT AI chats and cluster metrics.

Authenticate in the handshake with a session token. Secret keys are not accepted here. A connection without a token is a guest; one with an invalid token is refused.

import { io } from 'socket.io-client';

const socket = io('https://volt.example.com', { auth: { token: sessionToken } });
socket.emit('subscribe_to_team', { teamId });
socket.on('analysis.status.changed', (event) => console.log(event));

Team events

Emit subscribe_to_team with { teamId, previousTeamId? } to join the room team:<teamId>; the server checks that you are a member, and leave_team leaves it. In that room the server forwards these domain events, each with its payload plus timestamp and eventName:

trajectory.created, trajectory.updated, trajectory.deleted, analysis.created, analysis.deleted, analysis.status.changed, analysis.stage.changed, scene-artifact.upserted, plugin.created, plugin.deleted, team.created, team.deleted, team-member.deleted, team-role.created, team-role.updated, team-role.deleted, secret-key.created, secret-key.deleted, notebook.deleted, whiteboard.deleted.

Your socket receives team.jobs.initial, a snapshot of the team's jobs, when you subscribe; the room receives team.job.updated each time a job changes status, and a new team.jobs.initial after running jobs are removed. The room also carries the presence events user:online, user:offline and user:list, which team:heartbeat keeps current.

Other channels

A handler that rejects a request emits error with { code, details } to your socket.

Cluster daemons connect to the same server with their own protocol; see @voltstack/daemon-cluster-client.