HTTP API reference

The HTTP API is the direct integration surface for applications that manage their own credentials, persistence, and review workflow. Its origin is https://api.antigen.sh. Authenticate every request with an organization API key in x-api-key. Keys begin with atg_sk_. Send the key only in that header: never in a URL, a browser history, a source file, or a log. Use content-type: application/json for Run creation and guidance. A local caller deadline bounds only that caller. It does not create, stop, resume, or cancel a Run.

Conventions

Every response carries contractVersion, currently "v1". Successful reads return the resource directly; errors return an error object described under Errors. Each endpoint requires a scope on the credential. See Authentication for how credentials are issued and how authorization errors are resolved.

Scope	Endpoints
`targets:read`	`GET /v1/targets`
`runs:read`	`GET /v1/runs`, `GET /v1/runs/{runId}`, `GET /v1/runs/{runId}/events`
`runs:write`	`POST /v1/runs`, guidance, and all lifecycle actions
`findings:read`	`GET /v1/runs/{runId}/findings`

Endpoints that accept no query parameters reject any query string with 404. This is deliberate: an unrecognized filter silently ignored is worse than a rejected request.

Discovery and creation

List approved targets

GET /v1/targets Lists targets approved for the caller’s organization.

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

{
  "contractVersion": "v1",
  "targets": ["example.com", "api.example.com"]
}

Select a target from this response for POST /v1/runs. If creation returns TARGET_NOT_APPROVED, re-read this endpoint rather than editing the rejected target.

Create a Run

POST /v1/runs Creates one authorized Run for a coherent assessment objective.

Field	Type	Description
`model`	`string`	Required. The assessment model.
`targets`	`string[]`	Required, non-empty. Each value from `GET /v1/targets`.
`guardrails`	`string`	Natural-language scope guidance sent with the Run.
`skills`	`{ name, content }[]`	Inline Skills. Both fields are non-empty strings; unknown fields are rejected.

REQUEST=$(jq -nc --arg target "$ANTIGEN_TARGET" \
  '{model:"claude-sonnet-4-6",targets:[$target],guardrails:"Assess only the approved target."}')
curl --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  -H 'content-type: application/json' \
  -d "$REQUEST" \
  https://api.antigen.sh/v1/runs | jq .

{
  "contractVersion": "v1",
  "id": "run_01J8Z3M6K7Q2X4",
  "model": "claude-sonnet-4-6",
  "targets": ["example.com"],
  "status": "creating",
  "createdAt": "2026-07-31T09:14:22.104Z",
  "updatedAt": "2026-07-31T09:14:22.104Z"
}

Persist id immediately with the assessment record. If the response is ambiguous, read that saved ID with GET /v1/runs/{runId} before considering another creation request. A second POST /v1/runs is a new assessment record, not a retry.

List and read Runs

List Runs

GET /v1/runs Reads an organization-visible page of Runs.

Query parameter	Description
`limit`	Page size, 1 through 100. Defaults to 50.
`cursor`	An opaque continuation value from a previous page.
`status`	One of `creating`, `running`, `stopping`, `stopped`, `resuming`, `completed`, `failed`, `cancelled`.

curl --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  'https://api.antigen.sh/v1/runs?limit=50&status=running' | jq .

{
  "contractVersion": "v1",
  "runs": [
    {
      "id": "run_01J8Z3M6K7Q2X4",
      "contractVersion": "v1",
      "model": "claude-sonnet-4-6",
      "targets": ["example.com"],
      "status": "running",
      "createdAt": "2026-07-31T09:14:22.104Z",
      "updatedAt": "2026-07-31T09:18:03.887Z",
      "startedAt": "2026-07-31T09:14:44.010Z"
    }
  ],
  "nextCursor": "eyJhZnRlciI6InJ1bl8wMUo4WjNNNks3UTJYNCJ9"
}

nextCursor is present only when another page exists. Pass it back unchanged. Do not derive authorization, identity, or ordering from a cursor or a Run ID.

Read a Run

GET /v1/runs/{runId} Reads one known Run by its saved opaque ID.

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

The response fields depend on how far the Run has progressed. startedAt appears once it is running, stoppedAt when it is stopped, and completedAt on a terminal status. A failed Run also carries failure with a code of EXECUTION_UNAVAILABLE or RUN_EXECUTION_FAILED and a message.

{
  "contractVersion": "v1",
  "id": "run_01J8Z3M6K7Q2X4",
  "model": "claude-sonnet-4-6",
  "targets": ["example.com"],
  "status": "completed",
  "createdAt": "2026-07-31T09:14:22.104Z",
  "updatedAt": "2026-07-31T09:41:52.660Z",
  "startedAt": "2026-07-31T09:14:44.010Z",
  "completedAt": "2026-07-31T09:41:52.660Z"
}

RUN_NOT_FOUND and FORBIDDEN both reject: the ID alone does not grant access. Read this endpoint after any ambiguous create or lifecycle request, then resume observation with GET /v1/runs/{runId}/events after your last handled checkpoint.

Events and findings

Stream Run events

GET /v1/runs/{runId}/events Opens an ordered server-sent event stream for a Run. The response uses content-type: text/event-stream and stays open until the Run reaches a terminal state or the caller disconnects. Resume with either a numeric after query parameter or an opaque Last-Event-ID header. They are alternatives: never send both.

curl --no-buffer --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  "https://api.antigen.sh/v1/runs/$RUN_ID/events?after=$AFTER"

Each frame carries the opaque event ID, the event type, and a JSON envelope:

id: evt_01J8Z3P2R9
event: finding
data: {"contractVersion":"v1","event":{"id":"evt_01J8Z3P2R9","runId":"run_01J8Z3M6K7Q2X4","sequence":42,"type":"finding","agent":"executor","summary":"Reflected input in search parameter","timestamp":"2026-07-31T09:31:10.552Z","findingId":"fnd_01J8Z3P2RA","severity":"high","title":"Reflected cross-site scripting"}}

`event` type	Additional `data.event` fields	Meaning
`thinking`, `tool`, `progress`	—	Ordered progress narration.
`finding`	`findingId`, `severity`, `title`	A finding was recorded.
`lifecycle`	`from`, `to`	The Run changed status. A terminal `to` ends the stream.
`error`	`error`	Execution failed, with `{ code, message }`.

Persist sequence only after handling that event, and resume with after=<sequence>. When you store the opaque id instead, send it as Last-Event-ID and omit after; the two cursors are not interchangeable. An invalid cursor is rejected with INVALID_REQUEST.

Read Run findings

GET /v1/runs/{runId}/findings Reads durable findings and remediation guidance for one Run.

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

{
  "contractVersion": "v1",
  "runId": "run_01J8Z3M6K7Q2X4",
  "findings": [
    {
      "id": "fnd_01J8Z3P2RA",
      "runId": "run_01J8Z3M6K7Q2X4",
      "severity": "high",
      "title": "Reflected cross-site scripting",
      "description": "The search parameter is reflected without contextual encoding.",
      "remediation": "Encode the parameter for its HTML output context before rendering.",
      "proof": { "request": "GET /search?q=…", "response": "HTTP/1.1 200 OK…" },
      "endpoint": "/search",
      "cwe": "CWE-79",
      "createdAt": "2026-07-31T09:31:10.552Z"
    }
  ]
}

severity is one of critical, high, medium, low, or info. proof, endpoint, and cwe appear only when available. An empty findings array is a valid outcome for a completed Run, not an integration failure.

Guidance and lifecycle

Send guidance

POST /v1/runs/{runId}/messages Delivers scoped guidance to an existing Run. The JSON body requires a content string; keep the guidance within the Run’s approved target and Guardrails.

REQUEST=$(jq -nc --arg content 'Prioritize the approved target and preserve evidence.' \
  '{content:$content}')
curl --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  -H 'content-type: application/json' \
  -d "$REQUEST" \
  "https://api.antigen.sh/v1/runs/$RUN_ID/messages" | jq .

{
  "contractVersion": "v1",
  "id": "msg_01J8Z3T4V1",
  "runId": "run_01J8Z3M6K7Q2X4",
  "deliveredAt": "2026-07-31T09:35:02.318Z"
}

For an ambiguous response, read the Run before sending another message. Work outside the approved scope needs its own authorized assessment.

Lifecycle actions

stop, resume, and cancel all return the Run in its requested new state.

Action	Request	Result
`POST /v1/runs/{runId}/stop`	`{}` body required	Non-terminal, resumable `stopped`.
`POST /v1/runs/{runId}/resume`	`{}` body required	Continues a `stopped` Run.
`POST /v1/runs/{runId}/cancel`	No body	Terminal `cancelled`.

stop and resume parse a JSON body and reject a malformed one with INVALID_REQUEST, so send {} and content-type: application/json. cancel reads no body at all. DELETE /v1/runs/{runId} is an exact alias for cancel, for clients that prefer the verb.

curl --fail-with-body --silent --show-error \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  -H 'content-type: application/json' \
  -d '{}' \
  "https://api.antigen.sh/v1/runs/$RUN_ID/stop" | jq .

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

INVALID_RUN_STATE means the action does not apply to the Run’s observed status, usually because another transition already occurred. Read the Run and choose a valid action rather than repeating the request. Resuming does not re-evaluate target approval, so confirm the scope still applies first. A local connection failure does not prove the action was rejected.

Errors

Error responses carry contractVersion and an error object with a stable code, a message, and an optional requestId.

{
  "contractVersion": "v1",
  "error": {
    "code": "TARGET_NOT_APPROVED",
    "message": "One or more targets are not approved for this organization",
    "requestId": "req_01J8Z3M6K7",
    "details": { "targets": ["staging.example.com"] }
  }
}

Code	Meaning
`INVALID_REQUEST`	The body or query failed validation.
`UNAUTHENTICATED`	The credential is missing, malformed, or expired.
`FORBIDDEN`	The credential is valid but lacks permission or scope for this request.
`TARGET_NOT_APPROVED`	A submitted target is not approved. `details.targets` lists the rejected values.
`RUN_NOT_FOUND`	No Run with that ID is visible to the caller.
`INVALID_RUN_STATE`	The lifecycle action does not apply to the Run’s current status.
`EXECUTION_UNAVAILABLE`	Execution capacity was unavailable for the Run.
`INTERNAL`	An unexpected service failure.

Retain requestId with the saved Run ID whenever one is present. It lets support identify the failing request without exposing credentials. After an ambiguous create, lifecycle, or observation request, do not infer the remote result from a local failure. Preserve the Run ID and your event checkpoint, read the Run, resume events after that checkpoint, and read findings for durable remediation work. Related concepts: Get started, TypeScript SDK, Guides, and Reliability and security.

Start

Build an assessment

Developer tools

Operate safely

Conventions

Discovery and creation

List approved targets

Create a Run

List and read Runs

List Runs

Read a Run

Events and findings

Stream Run events

Read Run findings

Guidance and lifecycle

Send guidance

Lifecycle actions

Errors

​Conventions

​Discovery and creation

​List approved targets

​Create a Run

​List and read Runs

​List Runs

​Read a Run

​Events and findings

​Stream Run events

​Read Run findings

​Guidance and lifecycle

​Send guidance

​Lifecycle actions

​Errors

Conventions

Discovery and creation

List approved targets

Create a Run

List and read Runs

List Runs

Read a Run

Events and findings

Stream Run events

Read Run findings

Guidance and lifecycle

Send guidance

Lifecycle actions

Errors