Documentation

Documentation / Node SDK

Node SDK

@guardonic/sdk is licensed under the MIT License. It sends agent run payloads to the Guardonic API with POST /v1/ingest and the x-api-key header. The package and source repository are not yet generally available; contact Guardonic for current access.

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

The npm package is not public yet. If Guardonic has provided source access, build the SDK locally and link it into your application:

$ cd guardonic-node
$ npm install
$ npm run build
$ npm link

You can also use a file: or workspace dependency in a monorepo. For access, email [email protected].

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): customer key generated in dashboard Settings.
  • 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) with a migrated Supabase project, then use the default http://localhost:4000 or set baseUrl. The repo includes examples/demo.mjs after npm run build.

$ GUARDONIC_API_KEY=gdn_live_... 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