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

# Create a human task

> Creates an open request assigned to a person. Connected messaging tools deliver a direct message; connected issue trackers create an assigned issue. Both refer to the same task when both are configured.

An optional completion condition lets the GitHub integration confirm a pull request merge. Otherwise the assigned person confirms the work through a connected tool. See [Human tasks](/sdk/human-tasks).



## OpenAPI

````yaml /reference/openapi.yaml post /human-tasks
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:
  /human-tasks:
    post:
      tags:
        - Human tasks
      summary: Create a human task
      description: >-
        Creates an open request assigned to a person. Connected messaging tools
        deliver a direct message; connected issue trackers create an assigned
        issue. Both refer to the same task when both are configured.


        An optional completion condition lets the GitHub integration confirm a
        pull request merge. Otherwise the assigned person confirms the work
        through a connected tool. See [Human tasks](/sdk/human-tasks).
      operationId: createHumanTask
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHumanTask'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanTask'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
components:
  schemas:
    CreateHumanTask:
      type: object
      properties:
        vulnerabilityId:
          type: string
          description: Vulnerability this request relates to.
          minLength: 1
        assignee:
          type: string
          description: Email of the responsible person in your organization.
          format: email
        title:
          type: string
          description: Action the person needs to take.
          minLength: 1
        description:
          type: string
          description: What is needed, why, and how to confirm completion.
          minLength: 1
        completion:
          oneOf:
            - $ref: '#/components/schemas/TaskCompletion'
            - type: 'null'
          description: Optional condition confirmed through a connected integration.
      required:
        - vulnerabilityId
        - assignee
        - title
        - description
      additionalProperties: false
      example:
        vulnerabilityId: vuln_123
        assignee: alex@example.com
        title: Review and merge the invoice fix
        description: Review the ownership check and merge the pull request once approved.
        completion:
          type: pull_request_merged
          url: https://github.com/acme/payments/pull/42
    HumanTask:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        vulnerabilityId:
          type: string
          description: Vulnerability this request relates to.
          minLength: 1
        assignee:
          type: string
          description: Email of the responsible person in your organization.
          format: email
        title:
          type: string
          description: Action the person needs to take.
          minLength: 1
        description:
          type: string
          description: What is needed, why, and how to confirm completion.
          minLength: 1
        completion:
          oneOf:
            - $ref: '#/components/schemas/TaskCompletion'
            - type: 'null'
          description: Optional condition confirmed through a connected integration.
        status:
          type: string
          enum:
            - open
            - completed
            - cancelled
        response:
          type:
            - string
            - 'null'
          description: >-
            Person’s response, when supplied. Automatic completion may have no
            written response.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - vulnerabilityId
        - assignee
        - title
        - description
        - completion
        - status
        - response
        - createdAt
        - updatedAt
      additionalProperties: false
      example:
        id: task_123
        vulnerabilityId: vuln_123
        assignee: alex@example.com
        title: Review and merge the invoice fix
        description: Review the ownership check and merge the pull request once approved.
        completion:
          type: pull_request_merged
          url: https://github.com/acme/payments/pull/42
        status: open
        response: null
        createdAt: '2026-09-13T10:00:00.000Z'
        updatedAt: '2026-09-13T10:00:00.000Z'
    TaskCompletion:
      type: object
      properties:
        type:
          type: string
          const: pull_request_merged
        url:
          type: string
          description: GitHub pull request whose merge completes the task.
          format: uri
      required:
        - type
        - url
      additionalProperties: false
    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.

````