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

# Update a human task

> Updates supplied fields and reflects the change in connected tools. Reassign a task by email, revise its instructions, or update status. Supply response when confirming work through your service. Set cancelled when the request is no longer needed.

External agents use the task’s status and response to decide when to continue. A completed access request tells the agent to retry the operation that required access.



## OpenAPI

````yaml /reference/openapi.yaml patch /human-tasks/{id}
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/{id}:
    patch:
      tags:
        - Human tasks
      summary: Update a human task
      description: >-
        Updates supplied fields and reflects the change in connected tools.
        Reassign a task by email, revise its instructions, or update status.
        Supply response when confirming work through your service. Set cancelled
        when the request is no longer needed.


        External agents use the task’s status and response to decide when to
        continue. A completed access request tells the agent to retry the
        operation that required access.
      operationId: updateHumanTask
      parameters:
        - name: id
          in: path
          required: true
          description: Opaque resource identifier.
          schema:
            type: string
            minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateHumanTask'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HumanTask'
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '409':
          $ref: '#/components/responses/Error409'
        '429':
          $ref: '#/components/responses/Error429'
components:
  schemas:
    UpdateHumanTask:
      type: object
      properties:
        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: Response or confirmation to retain with the task.
      required: []
      additionalProperties: false
      minProperties: 1
      example:
        status: completed
        response: The repository is connected with access to the source code.
    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.
    Error404:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: The resource does not exist in this organization.
    Error409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: conflict
              message: The resource’s current state does not allow this operation.
    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.

````