Documentation

Documentation / Node SDK

Node SDK

@guardonic/sdk is open source (MIT). It sends agent run payloads to the Guardonic API with POST /v1/ingest and the x-api-key header. Source: github.com/guardonic/guardonic-node.

Point baseUrl at the API your operator gives you (hosted Guardonic API or your own guardonic-engine deployment). The SDK defaults to http://localhost:4000 for local development.

Install

From npm (when published):

$ npm install @guardonic/sdk

From a clone of the repo: build, then npm link, or add a file: / workspace dependency in a monorepo.

$ git clone https://github.com/guardonic/guardonic-node.git
$ cd guardonic-node
$ npm install
$ npm run build
$ npm link

Usage

import { Guardonic } from "@guardonic/sdk";

const client = new Guardonic({
apiKey: process.env.GUARDONIC_API_KEY!,
baseUrl: "https://your-api.example", // optional; default http://localhost:4000
});

const { runId } = await client.ingest({
agent: "support-bot",
status: "running",
events: [
{
type: "llm",
label: "Request",
detail: "gpt-4o · 1200 tok",
},
],
});
  • ingest() returns { ok: true, runId, contractVersion }.
  • Omit runId in the body to let the API create one; send the same runId on later calls to append events to that run.
  • On non-OK responses or invalid JSON, the client throws an Error with the server message when available.

Constructor

GuardonicOptions:

  • apiKey (required) — same value as the API / engine GUARDONIC_API_KEY.
  • baseUrl (optional) — origin only, no trailing slash; default http://localhost:4000.
  • fetch (optional) — inject fetch for tests or custom runtimes.

Ingest payload

IngestInput (all fields optional except what your pipeline requires):

  • runId — stable id for the run; omit to assign a new id.
  • agent, status — strings (e.g. agent name, running / completed).
  • events — array of GuardonicEventInput: type (required), label, detail, optional at (ISO time).
  • summary — arbitrary JSON object for extra metadata.

Exported types: GuardonicEventInput, IngestInput, IngestResult.

Local development

To exercise the SDK against a real API, run guardonic-engine (NestJS) and MongoDB, then use the default http://localhost:4000 or set baseUrl. The repo includes examples/demo.mjs after npm run build.

$ GUARDONIC_API_KEY=gdn_dev_poc GUARDONIC_BASE_URL=http://localhost:4000 node examples/demo.mjs

HTTP contract

The client calls POST {baseUrl}/v1/ingest with application/json and header x-api-key. Hosted Guardonic APIs that follow the same contract are compatible.

Realtime updates (e.g. for a dashboard) use Socket.IO on the /v1/realtime namespace on the engine; the SDK does not ship a WebSocket client yet — use socket.io-client or a small wrapper if you need browser or Node subscriptions.

Current stable contract version: 2026-04-15.v1.

Environment

Your app should provide the API key (and optionally base URL) via config or env — for example:

GUARDONIC_API_KEY=••••••••
# GUARDONIC_BASE_URL=https://api.example.com