TypeScript SDK reference

@antigenco/sdk is the typed client for Antigen Runs. It offers two entry points into the same API. Use antigen.agent(config).run(targets) when the model and Guardrails belong together as one assessment configuration. Use antigen.runs when your application owns the request fields, or when it is reconnecting to a Run it created earlier. An integration owns three things: an organization API key, an approved target, and durable storage for the Run ID. Antigen supplies the approved target list; you choose from it and record why the target is in scope. A Run ID is a locator rather than a credential, so store it alongside the assessment record and rely on organization permissions for every later read or operation.

Install

npm install @antigenco/sdk

The SDK is ESM-only and requires Node 22 or later. It ships its own TypeScript declarations.

Authenticate

Pass an organization API key as the first argument. Keys begin with atg_sk_; read them from your secret source at startup and never commit or log them.

import Antigen from "@antigenco/sdk";

const apiKey = process.env.ANTIGEN_API_KEY;
if (!apiKey) throw new Error("Set ANTIGEN_API_KEY to an organization API key.");

const antigen = new Antigen(apiKey);

The atg_sk_ prefix identifies the credential kind, not its validity, expiry, or scope, so a shape check cannot tell you whether a key still works. The service answers that with a structured error carrying a requestId. Later examples on this page assume this antigen client and an approved target string already exist, so that each one shows only the call being described.

Quick start

This complete program picks an approved target, creates a Run, follows its events, and prints the first finding’s remediation. Save it as assess.ts and run it with npx tsx assess.ts.

import { writeFile } from "node:fs/promises";
import Antigen from "@antigenco/sdk";

const apiKey = process.env.ANTIGEN_API_KEY;
if (!apiKey) throw new Error("Set ANTIGEN_API_KEY to an organization API key.");

const antigen = new Antigen(apiKey);
const approved = await antigen.getApprovedTargets();
const target = approved.find(
  (candidate) => candidate === process.env.ANTIGEN_TARGET,
);
if (!target)
  throw new Error(`Set ANTIGEN_TARGET to one of: ${approved.join(", ")}`);

const run = await antigen
  .agent({
    model: "claude-sonnet-4-6",
    guardrails: "Assess only the approved target.",
  })
  .run([target]);
await writeFile(".antigen-run-id", `${run.id}\n`, { mode: 0o600 });

for await (const event of run) {
  console.log(`${event.sequence}: ${event.summary}`);
  await writeFile(".antigen-event-position", `${event.sequence}\n`, {
    mode: 0o600,
  });
}

const [finding] = await run.findings();
console.log(
  finding
    ? `Next action: ${finding.remediation}`
    : "Completed with no findings.",
);

The two files stand in for whatever durable storage your application already operates. The Run ID must be written as soon as creation succeeds, and an event sequence only after that event has been handled. Those two ordering rules are what make recovery deterministic.

Client

new Antigen

Constructs a client. The common form takes an API key; the object form is for callers that hold a user access token or need to reach a non-hosted environment.

new Antigen(apiKey: string, options?: Omit<AntigenOptions, "accessToken" | "apiKey">)
new Antigen(options: AntigenOptions)

Option	Type	Description
`apiKey`	`string`	An organization API key beginning with `atg_sk_`. Sent as `x-api-key`.
`accessToken`	`string`	A user access token, used instead of an API key. Sent as `authorization: Bearer`.
`baseUrl`	`string`	API origin. Defaults to `https://api.antigen.sh`. Use it for local development and Preview environments.
`fetch`	`typeof fetch`	A replacement `fetch` implementation, for proxies or instrumentation.

The object form is the one to reach for when a value other than an API key varies:

const antigen = new Antigen({
  accessToken: userAccessToken,
  baseUrl: process.env.ANTIGEN_BASE_URL ?? "https://api.antigen.sh",
});

Pass exactly one of apiKey and accessToken. Supplying both, neither, a blank credential, or an apiKey without the atg_sk_ prefix throws AntigenProtocolError from the constructor. baseUrl is validated the same way: it must be an http or https URL carrying no query, fragment, or embedded credentials. The client exposes antigen.runs for the Run collection and antigen.agent(config) for the assessment facade. Constructing a client performs no network request, so a well-formed but invalid credential is reported by the service on the first call, not here.

antigen.getApprovedTargets

Lists the targets approved for the caller’s organization. Call it before creating a Run.

antigen.getApprovedTargets(options?: RequestOptions): Promise<string[]>

const targets = await antigen.getApprovedTargets();
if (targets.length === 0)
  throw new Error("No approved targets for this organization.");

Select a returned value unchanged. If creation later returns TARGET_NOT_APPROVED, read this list again rather than editing the rejected target. An empty list is an authorization question for your organization administrator, not an integration bug.

Create a Run

antigen.agent

Creates an assessment facade that keeps model configuration and Guardrails next to Run creation.

antigen.agent(config: AgentConfig): Agent

Field	Type	Description
`model`	`string`	Required. The assessment model.
`guardrails`	`string`	Natural-language scope guidance sent with the Run.
`skills`	`readonly string[]`	Local paths to Markdown files or directories, read into the request at `run()` time.

Each skills entry may be a .md file or a directory, which is walked in deterministic order. Symbolic links are rejected, empty files are rejected, and each Skill’s name is its filename without the extension, so names must be unique across the whole set. Treat these files as reviewed application input and keep credentials out of them.

const agent = antigen.agent({
  model: "claude-sonnet-4-6",
  guardrails: "Assess only the approved target.",
});

Guardrails shape how the agent works. The approved target list is the enforced boundary. Keep one assessment configuration to one coherent objective.

agent.run

Creates a Run from the Agent’s configuration for one or more approved targets.

agent.run(targets: readonly string[], options?: RequestOptions): Promise<Run>

const run = await agent.run([target]);
await writeFile(".antigen-run-id", `${run.id}\n`, { mode: 0o600 });

targets must be non-empty and every entry must come from getApprovedTargets. Invalid input, transport failures, and service rejections reject rather than returning a partial Run, so a resolved promise always carries a real run.id. Persist run.id immediately. If the create response is ambiguous, read that saved ID with runs.get before deciding whether another assessment is necessary. A second create is a new assessment record, never a retry.

runs.create

Creates a Run from request fields your application supplies directly. Use this form when the application, rather than an Agent configuration, owns the request.

antigen.runs.create(input: CreateRunRequest, options?: RequestOptions): Promise<Run>

Field	Type	Description
`model`	`string`	Required. The assessment model.
`targets`	`string[]`	Required, non-empty. Every entry from `getApprovedTargets`.
`guardrails`	`string`	Natural-language scope guidance.
`skills`	`RunSkill[]`	Inline Skills as `{ name, content }` pairs, already loaded by the caller.

const run = await antigen.runs.create({
  model: "claude-sonnet-4-6",
  targets: [target],
  guardrails: "Assess only the approved target.",
});

Unlike agent.run, this form takes Skill content inline rather than reading local paths, so it works in runtimes without filesystem access. Pick one creation form per integration boundary.

Find a Run

Method	Use it when	Result
`runs.list`	You need recent Runs or a filtered page.	`Promise<RunsPage>`
`runs.get`	You are reconnecting to a saved opaque ID.	`Promise<Run>`

runs.list

Reads a page of Runs visible to the caller’s organization.

antigen.runs.list(input?: ListRunsRequest, options?: RequestOptions): Promise<RunsPage>

Field	Type	Description
`limit`	`number`	Page size, 1 through 100. Defaults to 50.
`cursor`	`string`	An opaque continuation value from a previous page.
`status`	`RunStatus`	Restrict the page to one lifecycle status.

const page = await antigen.runs.list({ limit: 50 });
for (const run of page.runs) console.log(run.id, run.current.status);
if (page.nextCursor) console.log(`More: ${page.nextCursor}`);

runs are full Run objects, so you can act on one without a second read. Preserve nextCursor unchanged and pass it back only for the next page. Do not derive authorization, identity, or ordering from a cursor or a Run ID.

runs.get

Reads a known Run by its saved opaque ID. This is the entry point for every recovery path.

antigen.runs.get(runId: string, options?: RequestOptions): Promise<Run>

const runId = (await readFile(".antigen-run-id", "utf8")).trim();
const run = await antigen.runs.get(runId);
console.log(run.current.status);

RUN_NOT_FOUND and authorization failures reject: the ID alone does not grant access. Read a saved Run before retrying any ambiguous create or lifecycle request.

Observe a Run

A Run separates the durable assessment record from what your caller has observed. run.current holds the last representation the client saw, without making a request. The methods below refresh it. Process evidence before advancing its saved checkpoint.

run.status

Reads and refreshes the latest durable representation of the Run.

run.status(options?: RequestOptions): Promise<RunState>

console.log((await run.status()).status);

RunState is a discriminated union on status, so the timestamps it carries depend on how far the Run has progressed: startedAt once running, stoppedAt when stopped, completedAt on a terminal state, and a failure object of { code, message } when status is failed. Read status after an ambiguous create, a lifecycle action, a local wait, or an event interruption, before deciding on the next operation.

run.events

Streams ordered events and resumes cleanly after a handled checkpoint.

run.events(options?: EventOptions): AsyncGenerator<RunEvent>

Option	Type	Description
`after`	`number`	Resume strictly after this processed event sequence. Must be a non-negative safe integer.

A Run is itself async-iterable, so for await (const event of run) is shorthand for run.events() with no options.

const saved = await readFile(".antigen-event-position", "utf8").catch(() => "");
const after = saved.trim() === "" ? undefined : Number(saved.trim());

for await (const event of run.events({ after })) {
  console.log(event.summary);
  await writeFile(".antigen-event-position", `${event.sequence}\n`, {
    mode: 0o600,
  });
}

Every event carries sequence, summary, timestamp, and an optional originating agent of planner, recon, executor, or system. Switch on type for the rest:

`type`	Additional fields	Meaning
`thinking`, `tool`, `progress`	n/a	Ordered progress narration.
`finding`	`findingId`, `severity`, `title`	A finding was recorded; read it with `run.findings`.
`lifecycle`	`from`, `to`	The Run changed status. A terminal `to` ends the stream.
`error`	`error`	Execution failed, with a `{ code, message }` failure.

The SDK reconnects a dropped stream on your behalf and recognizes exact duplicate replay within the most recent 256 events. Out-of-order or unknown older events are protocol errors rather than silent gaps. Persist event.sequence only after handling the event; saving first can skip unprocessed work, and never saving makes the same evidence look new after every interruption.

run.findings

Reads durable findings for the Run.

run.findings(options?: RequestOptions): Promise<Finding[]>

for (const finding of await run.findings()) {
  console.log(`${finding.severity}: ${finding.title}`);
  console.log(finding.remediation);
}

Field	Type	Description
`id`, `runId`	`string`	Identity, and the Run this finding belongs to.
`severity`	`"critical" \| "high" \| "medium" \| "low" \| "info"`	Assessed severity.
`title`, `description`	`string`	What was found.
`remediation`	`string`	The documented starting point for the next action.
`proof`	`{ request?, response? }`	Supporting evidence, when available.
`endpoint`, `cwe`	`string`	The affected endpoint and CWE classification, when applicable.
`createdAt`	`string`	When the finding was recorded.

A completed Run can have no findings; that is a valid assessment result, not an integration failure. Treat findings as evidence for a human risk decision, and preserve proof and remediation with the assessment record. A local failure does not mean a finding was removed.

run.wait

Waits locally until the Run reaches completed, failed, or cancelled.

run.wait(options?: WaitOptions): Promise<RunState>

Option	Type	Description
`waitTimeoutMs`	`number`	Total local wait deadline. Defaults to 1,800,000 (30 minutes).
`pollIntervalMs`	`number`	Poll interval. Defaults to 1,000, clamped to 100 through 30,000.

import Antigen, { AntigenWaitTimeoutError } from "@antigenco/sdk";

try {
  console.log((await run.wait({ waitTimeoutMs: 300_000 })).status);
} catch (error) {
  if (!(error instanceof AntigenWaitTimeoutError)) throw error;
  console.log("Local wait ended; reconnect to the saved Run later.");
}

stopped is not wait-terminal, so a stopped Run keeps the wait running until the deadline. The deadline is local: on AntigenWaitTimeoutError, reconnect with runs.get and run.events rather than assuming the Run ended or calling run.cancel.

Guide a Run

run.send

Delivers scoped guidance to an assessment already under way, without changing its approved purpose.

run.send(content: string, options?: RequestOptions): Promise<SendRunMessageResponse>

const delivery = await run.send(
  "Continue only within the approved target and Guardrails.",
);
console.log(`Delivered ${delivery.id} at ${delivery.deliveredAt}`);

content must be non-empty and stay inside the approved target and Guardrails. Prefer a specific, reviewable request over a broad change of purpose. If necessary work falls outside the approved scope, obtain authorization and create a separate assessment instead.

Control a Run

completed, failed, and cancelled are terminal. Use a lifecycle operation to express a decision, not to repair a local timeout. If one is rejected with INVALID_RUN_STATE, another transition already occurred: read the Run and choose an action valid for the observed state.

run.stop

Requests a reviewable pause, leaving the Run resumable.

run.stop(options?: RequestOptions): Promise<RunState>

console.log((await run.stop()).status);

run.resume

Requests continuation of a stopped Run you already hold.

run.resume(options?: RequestOptions): Promise<RunState>

console.log((await run.resume()).status);

Resuming does not re-evaluate target approval, so confirm the approved scope still applies first.

runs.resume

Resumes a stopped Run by ID and returns a Run object for it. Use this when the application has a saved ID but not a live Run, which is the usual case after a restart.

antigen.runs.resume(runId: string, options?: RequestOptions): Promise<Run>

const run = await antigen.runs.resume(runId);
for await (const event of run.events({ after })) console.log(event.summary);

agent.resume(runId, options) is an equivalent alias on the Agent facade, for code that is already working through an Agent. It ignores the Agent’s model and Guardrails, because a resumed Run keeps the configuration it was created with.

run.cancel

Ends the assessment. cancelled is terminal.

run.cancel(options?: RequestOptions): Promise<RunState>

console.log((await run.cancel()).status);

Cancel only when ending the assessment is the intended business decision, never as a response to a local timeout or a dropped connection.

Request options

Every method accepts RequestOptions as its last argument. Both fields bound the caller’s own work and neither changes a Run that Antigen has already accepted.

Option	Type	Description
`signal`	`AbortSignal`	Cancels the caller’s local operation.
`requestTimeoutMs`	`number`	Bounds one HTTP request.

import type { RequestOptions } from "@antigenco/sdk";

const options: RequestOptions = { requestTimeoutMs: 30_000 };
console.log(await antigen.getApprovedTargets(options));

Use a short request deadline for interactive actions and one that fits your job queue for background work. run.wait extends these with waitTimeoutMs and pollIntervalMs, and run.events extends them with after.

Errors

The SDK distinguishes local wait timeouts, protocol failures, and HTTP failures. Transport failures surface as the underlying fetch error.

Class	Thrown when	Useful fields
`AntigenHttpError`	The service returned a non-success status.	`status`, `requestId`, `body`
`AntigenProtocolError`	A response, event ordering, or local Skill file was unusable.	`message`
`AntigenWaitTimeoutError`	`run.wait` reached its local deadline.	`timeoutMs`

import Antigen, { AntigenHttpError } from "@antigenco/sdk";

try {
  await antigen.runs.create({ model: "claude-sonnet-4-6", targets: [target] });
} catch (error) {
  if (!(error instanceof AntigenHttpError)) throw error;
  console.error(`HTTP ${error.status} requestId=${error.requestId ?? "none"}`);
}

A structured service error carries a stable code in its body. Retain the requestId with the saved Run ID: it lets support identify the failing request without exposing credentials.

Code	HTTP	Meaning
`INVALID_REQUEST`	`400`	The request body or a path value failed validation.
`TARGET_NOT_APPROVED`	`400`	A submitted target is not approved. `details.targets` lists the rejected values.
`UNAUTHENTICATED`	`401`	No recognizable credential was presented.
`FORBIDDEN`	`403`	The credential is valid but lacks the required scope.
`RUN_NOT_FOUND`	`404`	No Run with that ID exists within what the credential can see.
`NOT_FOUND`	`404`	The request path matches no endpoint. Usually a `baseUrl` mistake.
`INVALID_RUN_STATE`	`409`	The Run’s current status does not accept that action.
`EXECUTION_UNAVAILABLE`	`503`	Execution capacity is temporarily unavailable.
`INTERNAL`	`500`	An unexpected service failure. Retain the `requestId`.

RUN_NOT_FOUND also answers a Run held by another organization, so it is not evidence that an ID was never issued. Branch on status for a code you do not recognize rather than matching the list exhaustively: the set can grow, and an unhandled code should not become a crash. AntigenHttpError is worth retrying when its status is 408, 429, or 5xx, and is not worth retrying otherwise. Creating a Run is the exception to retrying at all: there is no idempotency key, so a retried create that in fact succeeded leaves two Runs executing and billable. List Runs first.

Recover from an ambiguous result

When a create, lifecycle, or observation call fails, the local failure tells you what your caller knows. It does not establish what the Run did. Recovery is always the same shape:

Read the saved Run ID from your durable store.
Call runs.get, then run.status for its current state.
Continue run.events strictly after the last sequence you finished handling.
Read run.findings for durable remediation work.

Do not send a replacement create request because the first response was inconclusive, and do not call run.cancel because a wait expired. Both turn an unknown local state into a real change to the assessment record. Related concepts: Guides, Examples, HTTP API reference, and Reliability and security.

Start

Build an assessment

Developer tools

Operate safely

Install

Authenticate

Quick start

Client

new Antigen

antigen.getApprovedTargets

Create a Run

antigen.agent

agent.run

runs.create

Find a Run

runs.list

runs.get

Observe a Run

run.status

run.events

run.findings

run.wait

Guide a Run

run.send

Control a Run

run.stop

run.resume

runs.resume

run.cancel

Request options

Errors

Recover from an ambiguous result

​Install

​Authenticate

​Quick start

​Client

​new Antigen

​antigen.getApprovedTargets

​Create a Run

​antigen.agent

​agent.run

​runs.create

​Find a Run

​runs.list

​runs.get

​Observe a Run

​run.status

​run.events

​run.findings

​run.wait

​Guide a Run

​run.send

​Control a Run

​run.stop

​run.resume

​runs.resume

​run.cancel

​Request options

​Errors

​Recover from an ambiguous result

Install

Authenticate

Quick start

Client

new Antigen

antigen.getApprovedTargets

Create a Run

antigen.agent

agent.run

runs.create

Find a Run

runs.list

runs.get

Observe a Run

run.status

run.events

run.findings

run.wait

Guide a Run

run.send

Control a Run

run.stop

run.resume

runs.resume

run.cancel

Request options

Errors

Recover from an ambiguous result