Runs

Start a run

Starts an agent on a task and returns the run while it initializes. Each successful request creates a separate run. The agent continues independently of your HTTP connection.

Supply an agent configuration and instructions with targets, vulnerabilityIds, or both. A base such as tcell uses that pre-built agent’s defaults; supplied configuration fields replace the corresponding exposed defaults. Vulnerability IDs are resolved within your organization. Target scope is checked before execution.

The SDK serializes the Agent object into agent and converts task vulnerabilities into vulnerabilityIds. The run retains the resolved configuration even if the registered agent changes later.

POST

/

runs

curl --request POST \
  --url https://api.antigen.sh/v1/runs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agent": {
    "base": "tcell"
  },
  "task": {
    "instructions": "Test the production API for authorization vulnerabilities.",
    "targets": [
      "api.example.com"
    ]
  }
}
'

{
  "id": "run_123",
  "status": "creating",
  "agent": {
    "base": "tcell",
    "model": "claude-opus-5-cyber",
    "skills": [
      "Check authorization when one account requests another account’s resources."
    ],
    "guardrails": "Do not attempt denial of service.",
    "tools": [
      "asset_map",
      "human_tasks"
    ]
  },
  "task": {
    "instructions": "Test the production API for authorization vulnerabilities.",
    "targets": [
      "api.example.com"
    ]
  },
  "createdAt": "2026-09-13T10:00:00.000Z",
  "updatedAt": "2026-09-13T10:00:00.000Z",
  "error": null
}

{
  "error": {
    "code": "invalid_request",
    "message": "Check the request fields and values."
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Supply a valid API key."
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The API key does not permit this operation or requested scope."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Retry after the interval in Retry-After."
  }
}

Authorizations

x-api-key

string

header

required

API key from your organization. Supply the value directly, without a Bearer prefix.

Body

application/json

agent

object

required

An agent configuration. Supply a pre-built base, a model, or both. Omitted fields use the base configuration, or empty skills and guardrails with asset_map and human_tasks tools when no base is supplied. Supplied fields replace the corresponding values. A retrieved Agent can be passed directly; name and builtIn are response metadata and do not change execution.

Option 1
Option 2

Show child attributes

Example:

{ "base": "tcell" }

task

object

required

Option 1
Option 2

Show child attributes

Example:

{
  "instructions": "Test the production API for authorization vulnerabilities.",
  "targets": ["api.example.com"]
}

Response

Created.

id

string

required

Minimum string length: 1

status

enum<string>

required

Available options:

creating,

running,

stopped,

completed,

failed

agent

object

required

Show child attributes

Example:

{
  "base": "tcell",
  "model": "claude-opus-5-cyber",
  "skills": [
    "Check authorization when one account requests another account’s resources."
  ],
  "guardrails": "Do not attempt denial of service.",
  "tools": ["asset_map", "human_tasks"]
}

task

object

required

Option 1
Option 2

Show child attributes

Example:

{
  "instructions": "Test the production API for authorization vulnerabilities.",
  "targets": ["api.example.com"]
}

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

error

string | null

required

Failure description when status is failed; otherwise null.

curl --request POST \
  --url https://api.antigen.sh/v1/runs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agent": {
    "base": "tcell"
  },
  "task": {
    "instructions": "Test the production API for authorization vulnerabilities.",
    "targets": [
      "api.example.com"
    ]
  }
}
'

{
  "id": "run_123",
  "status": "creating",
  "agent": {
    "base": "tcell",
    "model": "claude-opus-5-cyber",
    "skills": [
      "Check authorization when one account requests another account’s resources."
    ],
    "guardrails": "Do not attempt denial of service.",
    "tools": [
      "asset_map",
      "human_tasks"
    ]
  },
  "task": {
    "instructions": "Test the production API for authorization vulnerabilities.",
    "targets": [
      "api.example.com"
    ]
  },
  "createdAt": "2026-09-13T10:00:00.000Z",
  "updatedAt": "2026-09-13T10:00:00.000Z",
  "error": null
}

{
  "error": {
    "code": "invalid_request",
    "message": "Check the request fields and values."
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Supply a valid API key."
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "The API key does not permit this operation or requested scope."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Retry after the interval in Retry-After."
  }
}