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

# 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](/docs/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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/sdk/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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/reference/webhooks) for payloads and delivery verification.

## Errors

Errors use the same JSON shape across endpoints:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.