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

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



## OpenAPI

````yaml /reference/openapi.yaml post /runs
openapi: 3.1.0
info:
  title: Antigen API
  version: v1
  description: >-
    Work with the same agents, runs, and resources your team uses in Antigen.
    Requests and responses use camelCase fields. List endpoints return arrays.
    See the [overview](/reference) for authentication, updates, and errors.
servers:
  - url: https://api.antigen.sh/v1
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
    description: Retrieve, compose, and register agent configurations.
  - name: Models
    description: Models available to agents in your organization.
  - name: Targets
    description: Submit testing scope for human approval.
  - name: Runs
    description: Execute agents and control their work.
  - name: Vulnerabilities
    description: Track weaknesses, remediation, status, and assignment.
  - name: Evidence
    description: Read supporting file metadata and retrieve file contents.
  - name: Reports
    description: Read and export captured engagement results.
  - name: Human tasks
    description: Ask people for help and follow their responses.
  - name: Hooks
    description: Connect status and assignment changes to your own service.
  - name: Asset Map
    description: Read your organization’s infrastructure graph.
  - name: Integrations
    description: Inspect and disconnect provider connections.
  - name: API keys
    description: Create and revoke credentials for automation.
paths:
  /runs:
    post:
      tags:
        - Runs
      summary: Start a run
      description: >-
        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.
      operationId: createRun
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRun'
            examples:
              pentest:
                value:
                  agent:
                    base: tcell
                  task:
                    instructions: Test the production API for authorization vulnerabilities.
                    targets:
                      - api.example.com
              custom:
                value:
                  agent:
                    model: claude-opus-5-cyber
                    skills:
                      - Check authorization across accounts.
                    guardrails: Do not attempt denial of service.
                    tools:
                      - asset_map
                  task:
                    instructions: Test the production API for authorization vulnerabilities.
                    targets:
                      - api.example.com
              remediation:
                value:
                  agent:
                    base: remediation-agent
                  task:
                    instructions: Prepare a fix for the team to review.
                    vulnerabilityIds:
                      - vuln_123
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Run'
              example:
                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
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
components:
  schemas:
    CreateRun:
      type: object
      properties:
        agent:
          $ref: '#/components/schemas/AgentInput'
        task:
          $ref: '#/components/schemas/Task'
      required:
        - agent
        - task
      additionalProperties: false
      example:
        agent:
          base: tcell
        task:
          instructions: Test the production API for authorization vulnerabilities.
          targets:
            - api.example.com
    Run:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        status:
          type: string
          enum:
            - creating
            - running
            - stopped
            - completed
            - failed
        agent:
          $ref: '#/components/schemas/AgentConfiguration'
        task:
          $ref: '#/components/schemas/Task'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        error:
          type:
            - string
            - 'null'
          description: Failure description when status is failed; otherwise null.
      required:
        - id
        - status
        - agent
        - task
        - createdAt
        - updatedAt
        - error
      additionalProperties: false
      example:
        id: run_123
        status: running
        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
    AgentInput:
      type: object
      properties:
        name:
          type: string
          description: >-
            Response metadata. Accepted when reusing a retrieved agent; ignored
            during execution.
          minLength: 1
          readOnly: true
        builtIn:
          type: boolean
          readOnly: true
          description: Response metadata; ignored during execution.
        base:
          type:
            - string
            - 'null'
          enum:
            - tcell
            - triage-agent
            - remediation-agent
            - null
          description: >-
            Underlying pre-built agent. Its private instructions remain managed
            by Antigen. Use null to assemble an agent without a pre-built base.
        model:
          type: string
          description: Model ID from GET /models.
          minLength: 1
        skills:
          type: array
          items:
            type: string
          description: Instruction strings. Send file contents, not file paths.
        guardrails:
          type: string
          description: Natural-language constraints on agent behavior.
        tools:
          type: array
          items:
            type: string
          description: >-
            Names of tools available to the agent, such as asset_map and
            human_tasks.
      required: []
      additionalProperties: false
      anyOf:
        - required:
            - base
          properties:
            base:
              type: string
              enum:
                - tcell
                - triage-agent
                - remediation-agent
        - required:
            - model
      description: >-
        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.
      example:
        base: tcell
    Task:
      type: object
      properties:
        instructions:
          type: string
          description: Work the agent should perform during this run.
          minLength: 1
        targets:
          type: array
          items:
            type: string
          description: Target values within your organization’s approved scope.
        vulnerabilityIds:
          type: array
          items:
            type: string
            minLength: 1
          description: >-
            Existing vulnerabilities in your organization. The API retrieves
            their current context.
      required:
        - instructions
      additionalProperties: false
      anyOf:
        - required:
            - targets
          properties:
            targets:
              minItems: 1
        - required:
            - vulnerabilityIds
          properties:
            vulnerabilityIds:
              minItems: 1
      example:
        instructions: Test the production API for authorization vulnerabilities.
        targets:
          - api.example.com
    AgentConfiguration:
      type: object
      properties:
        base:
          type:
            - string
            - 'null'
          enum:
            - tcell
            - triage-agent
            - remediation-agent
            - null
          description: >-
            Underlying pre-built agent. Its private instructions remain managed
            by Antigen. Use null to assemble an agent without a pre-built base.
        model:
          type: string
          description: Model ID from GET /models.
          minLength: 1
        skills:
          type: array
          items:
            type: string
          description: Instruction strings. Send file contents, not file paths.
        guardrails:
          type: string
          description: Natural-language constraints on agent behavior.
        tools:
          type: array
          items:
            type: string
          description: >-
            Names of tools available to the agent, such as asset_map and
            human_tasks.
      required:
        - base
        - model
        - skills
        - guardrails
        - tools
      additionalProperties: false
      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
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Stable error code.
            message:
              type: string
              description: Description of the problem.
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      example:
        error:
          code: invalid_request
          message: The target value is required.
  responses:
    Error400:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_request
              message: Check the request fields and values.
    Error401:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Supply a valid API key.
    Error403:
      description: Permission denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: The API key does not permit this operation or requested scope.
    Error429:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Retry after the interval in Retry-After.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key from your organization. Supply the value directly, without a
        Bearer prefix.

````