API Reference

Every HTTP endpoint the studio exposes, grouped by who calls it. The base URL is the studio's own address — http://localhost:3000 in development.

Authentication

There are two identities in the platform and each has its own credential.

A session is created by POST /api/auth/login and lasts seven days. The cookie is httpOnly and sameSite="lax", and it carries the secure flag when NODE_ENV=production.

An agent holds two credentials, and each belongs to one channel. The apiKey is what the REST endpoints under /api/agent take; the agentSecret is what the socket handshake compares. Neither is ever sent in a header. See Socket Protocol for the socket side.

Conventions

Setup and system

{
  "status": "ready",
  "needsSetup": false,
  "databaseConfigured": true,
  "adminCreated": true,
  "version": "1.0.0"
}

status is uninitialized (no database configured), needs_admin (configured but no admin) or ready. version is the platform's own version string — see Version Compatibility.

{
  "isComplete": true,
  "currentStep": "complete",
  "startedAt": "2026-10-21T07:30:00.000Z",
  "needsResume": false
}

The body selects the step:

{ "step": "license",   "data": { "licenseKey": "ENT0-DKST-UDIO-2026" } }
{ "step": "database",  "data": { "dbType": "sqlite", "database": "dkstudio" } }
{ "step": "initialize" }
{ "step": "admin",     "data": { "email": "…", "name": "…", "password": "…", "confirmPassword": "…" } }
{ "step": "complete" }

The initialize step applies the schema for the configured engine.

Optionally takes { "deleteDatabase": true } to drop the PostgreSQL or MySQL database. For SQLite the database file is always deleted.

Authentication endpoints

{ "email": "admin@lab.example", "password": "…" }

Answers with the user and sets session (httpOnly) and session_client.

{
  "success": true,
  "user": { "id": "…", "email": "…", "name": "…", "role": "admin" }
}

{
  "isAuthenticated": true,
  "user": { "id": "…", "email": "…", "name": "…", "role": "admin" }
}

Takes a code query parameter, redirects to the SSO provider at https://sso.ingeek.com, and sets the auth_token and refresh_token cookies.

Agent-facing

These are the endpoints the agent calls.

Takes ?code=… and answers with the licence's type, scope and whether it can still be used.

{
  "code": "dk_l_…",
  "name": "Bench 01",
  "studioUrl": "http://localhost:3000",
  "workstation": { "hostname": "bench-01", "platform": "linux", "arch": "x64" },
  "capabilities": []
}

Answers with the agent's identity:

{
  "success": true,
  "agentId": "…",
  "apiKey": "…32 alphanumeric characters…",
  "agentSecret": "…64 hex characters…",
  "licenseType": "personal",
  "scope": "personal",
  "ownerUserId": "…",
  "reRegistered": false
}

message carries a human-readable summary of the outcome. Registering again with the agent's own agentId and agentSecret updates the agent in place, sets reRegistered to true and increments registrationCount.

{ "apiKey": "…" }

{
  "success": true,
  "agentId": "…",
  "name": "Bench 01",
  "capabilities": []
}

It does not change the agent's status — presence comes from the socket. An unknown key is 401 with Invalid API key.

{ "agentId": "…", "status": "active" }

Answers { "success": true, "timestamp": "…" }. Only last_seen_at is updated; the status field in the body is ignored.

{ "agentId": "…" }

Answers { "success": true }. The agent's stored status becomes unregistered and the agent row is kept.

Returns the agent's pending commands and flips them to in_progress. Each command arrives as the same command request envelope the socket carries:

{
  "commands": [
    {
      "v": 1,
      "type": "command",
      "kind": "request",
      "id": "…",
      "timestamp": "…",
      "payload": { "command": "shell", "args": { "script": "uname -a" } }
    }
  ]
}

The body is the command response envelope — the same one the socket carries:

{
  "v": 1,
  "type": "command",
  "kind": "response",
  "id": "…",
  "timestamp": "…",
  "payload": {
    "ok": true,
    "data": {
      "status": "success",
      "output": { "stdout": "…", "stderr": "", "exitCode": 0, "durationMs": 42 }
    }
  }
}

Answers { "success": true }. The command row is marked completed and the result is stored as JSON.

Studio

{
  "agents": [
    { "id": "…", "name": "Bench 01", "status": "online", "lastSeen": "…", "capabilities": [] }
  ],
  "timestamp": "…"
}

Only agents whose stored status is active and that have a live socket are returned.

{
  "agentId": "…",
  "command": "shell",
  "args": { "script": "uname -a", "cwd": "/tmp" },
  "timeout": 30000
}

Answers with a commandId:

{ "success": true, "commandId": "…", "message": "…" }

{
  "id": "…",
  "agentId": "…",
  "commandType": "shell",
  "status": "completed",
  "result": { "status": "success", "output": { "stdout": "…", "exitCode": 0 } },
  "startedAt": "…",
  "completedAt": "…"
}

status is pending, in_progress or completed.

{
  "totalProjects": 0,
  "activeTestRuns": 0,
  "devicesOnline": 0,
  "successRate": 0
}

Admin

{
  "agents": [
    {
      "id": "…",
      "name": "Bench 01",
      "status": "active",
      "connectionStatus": "online",
      "capabilities": [],
      "workstation": { "hostname": "bench-01" },
      "lastSeen": "…",
      "registrationCount": 1
    }
  ]
}

{
  "userId": "…",
  "licenses": [
    { "id": "…", "code": "dk_l_…", "type": "personal", "ownerUserId": "…", "status": "pending", "expiresAt": null }
  ],
  "agents": []
}

Takes { "type": "personal" | "lab", "location": "…", "label": "…", "expiresAt": "…" }. A personal licence belongs to the caller; a lab licence can only be issued by an administrator. Answers with the licence and its code — the only time the code is shown.

Answers with the agent's detail record.

Deletes the agent row and its command history. An id that matches no agent is 404 Agent not found.

Answers { "success": true } and sets the licence's status to revoked. The owner of a licence may revoke their own; an administrator may revoke any. A licence that has already been consumed cannot be revoked — the machine is on the ledger.

Administrators only. A licence that has already been consumed cannot be deleted.

{
  "users": [
    { "id": "…", "email": "…", "name": "…", "role": "admin", "createdAt": "…" }
  ]
}

{
  "email": "engineer@lab.example",
  "name": "Lab Engineer",
  "password": "…",
  "role": "engineer"
}

Answers { "success": true, "user": { … } }. role is admin, engineer or viewer; anything unrecognised becomes viewer. The email must be unique.

Takes { "id": "…" } in the body and answers { "success": true }.

Status codes

See also

• Command Reference — the commands these endpoints carry.
• Socket Protocol — the realtime counterpart to all of this.
• Configuration — the environment behind these endpoints.
• Error Codes — the status codes and error strings these endpoints return.