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

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](/authentication) covers the roles, the credential kinds, the scopes, and what to do
when a request is refused.

## Quick start

<Tabs>
  <Tab title="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).
  </Tab>

  <Tab title="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).
  </Tab>

  <Tab title="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).
  </Tab>
</Tabs>

## Use Platform instead

[Platform](https://platform.antigen.sh) 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.