> ## Documentation Index
> Fetch the complete documentation index at: https://docs.antigen.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

Pick one of the parallel quick starts below. 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()`.                     |

Organization roles are admin, member, and read-only. Admins manage membership and API keys, members
create and operate Runs, and read-only members read Runs and findings without creating them.
[Authentication](/authentication) covers credential kinds, scopes, and authorization errors in full.

Confirm the target list returns the value you intend before you submit a Run. If the list is empty,
a target is rejected, or access is forbidden, stop rather than editing a target string or borrowing
another organization's credential. Ask your administrator to verify membership and the credential,
and request a target change from Antigen if the target you need is absent.

Neither knowing a target value nor holding a Run ID grants access. Every request is authorized in
the caller's organization context, which is also why the safe response to a permission error is to
fix the permission rather than to create a second Run.

## 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.

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/sdk/typescript).

## Quick start: CLI

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

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/cli).

## Quick start: 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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/http-api).

## 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](/guides) for planning scope, preserving evidence, and recovering from failures.
* [Concepts](/concepts) for Run lifecycle and finding terminology.
* [Examples](/examples) for complete application-owned programs.