Get started

Start an authorized Antigen assessment with the SDK, CLI, or HTTP API.

Antigen helps security and engineering teams assess systems their organization has authorized. An assessment sets scope and Guardrails. A Run is its durable record of progress and findings.

The quick start below runs the same first assessment through each client. The TypeScript SDK and CLI are convenience clients over the same contract; the HTTP API stays available when you integrate directly.

Before you begin

You need three things: membership in an Antigen organization, a credential, and an approved target.

What	Who provides it	How you confirm it
Organization membership	Your organization administrator	Sign in and check the active organization.
Credential	Your organization administrator	An atg_sk_ API key for applications, or antigen login for an interactive member.
Approved target	Antigen	antigen targets, GET /v1/targets, or getApprovedTargets().

Confirm the target list returns the value you intend before you submit a Run. Authentication covers the roles, the credential kinds, the scopes, and what to do when a request is refused.

Quick start

TypeScript SDK

Install the SDK, set ANTIGEN_API_KEY to an organization API key, and set ANTIGEN_TARGET to one of your approved targets.

npm install @antigenco/sdk

Save the program below as assess.ts and run it on Node 22 or later with npx tsx assess.ts. It confirms the requested target is approved, records the Run ID and event position in application-owned files, then reports the first finding’s remediation.

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.",
);

Continue in the TypeScript SDK reference.

CLI

Install the CLI and sign in. Device login needs your organization UUID, from --organization-id or ANTIGEN_ORGANIZATION_ID.

npm install --global @antigenco/cli
antigen login --organization-id "$ANTIGEN_ORGANIZATION_ID"
antigen targets

antigen run creates a Run, streams its events, and prints findings in one command. With no options it assesses every approved target, so pass --targets when the assessment should be narrower.

antigen run --targets example.com

For an unattended workflow, set ANTIGEN_API_KEY instead of signing in, and use --json so the Run ID is machine-readable rather than copied by hand:

antigen create --model claude-sonnet-4-6 --target example.com --json \
  | jq -r '.id' > .antigen-run-id
antigen wait "$(cat .antigen-run-id)"
antigen findings "$(cat .antigen-run-id)" --json

A completed Run exits 0; a failed or cancelled Run exits 1, so CI can gate on the result directly. Continue in the CLI reference.

HTTP API

The HTTP API is served from https://api.antigen.sh. Authenticate every request with an organization API key in x-api-key. These commands need curl and jq, with ANTIGEN_API_KEY set in your environment.

List the targets approved for your organization:

curl --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  https://api.antigen.sh/v1/targets | jq .

Create a Run against one of them and save the returned ID. --fail-with-body prints the service’s structured error and returns a non-zero status if the request is rejected:

curl --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  -H 'content-type: application/json' \
  -d '{"model":"claude-sonnet-4-6","targets":["example.com"],"guardrails":"Assess only the approved target."}' \
  https://api.antigen.sh/v1/runs | jq -r '.id' > .antigen-run-id

Then read the Run and its findings:

RUN_ID=$(cat .antigen-run-id)
curl --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  "https://api.antigen.sh/v1/runs/$RUN_ID" | jq .
curl --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  "https://api.antigen.sh/v1/runs/$RUN_ID/findings" | jq .

Continue in the HTTP API reference.

Use Platform instead

Platform is the visual workflow over the same organization, approved targets, Runs, and findings. Sign in, choose an approved target, start a Run, and follow its progress and findings in the browser. It suits review and triage work that does not need to be scripted, and it supplements the programmatic clients rather than replacing them.

If you started a Run from the CLI, antigen open <run-id> opens that same Run in Platform.

Next steps

Whichever path you took, the Run you created is one durable record. Save its ID, read each finding’s remediation, and assign the next action through your organization’s review process.

• Guides for planning scope, preserving evidence, and recovering from failures.
• Concepts for Run lifecycle and finding terminology.
• Examples for complete application-owned programs.