Overview

Use the Antigen API from your own service, an external agent, or any language that can make HTTP requests. It works with the same resources as the platform and the Antigen SDK. The base URL is https://api.antigen.sh/v1.

Make a request

Create an API key in the platform and send it in the x-api-key header:

curl 'https://api.antigen.sh/v1/targets?status=approved' \
  -H "x-api-key: $ANTIGEN_API_KEY"

The key determines your organization and permissions. Keep it in your backend or secret store. See Authentication for creating and replacing keys.

Start a run

Send an agent configuration and a task to POST /runs. This example uses tCell’s configuration and an approved target:

curl https://api.antigen.sh/v1/runs \
  -H "x-api-key: $ANTIGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "base": "tcell"
    },
    "task": {
      "instructions": "Test the production API for authorization vulnerabilities.",
      "targets": ["api.example.com"]
    }
  }'

Replace the hostname with a target approved for your organization. The response contains the run’s ID and status. Work continues in the background; retrieve GET /runs/{id} to check progress or connect to GET /runs/{id}/events to stream activity. You can supply configuration fields alongside base to customize the agent, or supply a model and configuration without a pre-built base. To work on existing vulnerabilities, include vulnerabilityIds in the task.

Resources

Resource	What you can do
Agents	Retrieve configurations, register your own, and update saved fields.
Models	List models available to your organization.
Targets	Submit testing scope and check its approval.
Runs	Launch agents, stream events, steer, stop, and resume.
Vulnerabilities	Read vulnerabilities and manage status, assignment, and risk acceptance.
Evidence	List evidence, read its metadata, and download files.
Reports	Read captured engagement results and download PDFs.
Human tasks	Assign requests to people and follow their responses.
Hooks	Register webhooks and enable or disable lifecycle automation.
Asset Map	Retrieve nodes and edges or execute read-only Cypher queries.
Integrations	Inspect connected providers and disconnect them.
API keys	Create and revoke credentials.

Skills, guardrails, and tools are fields on an agent configuration. Steering, stopping, and resuming operate on a run. Status and assignment are fields on a vulnerability. Authorized agent runs create vulnerabilities and evidence through their tools. The public API lets your applications read those results and coordinate the work that follows.

Requests and responses

JSON fields use camelCase, including vulnerabilityId and createdAt. IDs are opaque strings. Timestamps use ISO 8601 in UTC. List endpoints return an array containing all matching resources. An empty result is []. Filters apply together. There are no pagination parameters or result envelopes. PATCH changes only the fields you supply. Arrays replace their previous values. To append to an array, retrieve the resource, combine the values in your code, and send the resulting array. Fields accept null only where the reference allows it. Creation returns 201. Reads and completed updates return 200. Steering returns 202 when the message is accepted. Deletion returns 204 with no response body. Starting a run returns before the agent finishes its work. Status and assignment changes trigger the same hooks as changes made in the platform. See Webhook events for payloads and delivery verification.

Errors

Errors use the same JSON shape across endpoints:

{
  "error": {
    "code": "not_found",
    "message": "The resource does not exist in this organization."
  }
}

Status	Meaning
`400`	A request field or parameter is invalid.
`401`	The API key is missing, invalid, or revoked.
`403`	The key lacks permission, or the requested work is outside approved scope.
`404`	The resource does not exist in your organization.
`409`	The request conflicts with an existing name or the resource’s current state.
`429`	Too many requests. Wait for the number of seconds in `Retry-After`.

Each endpoint documents its request, response, and applicable errors.

Getting started

Endpoints

Make a request

Start a run

Resources

Requests and responses

Errors

​Make a request

​Start a run

​Resources

​Requests and responses

​Errors

Make a request

Start a run

Resources

Requests and responses

Errors