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

# Control fleet work or adopt reviewed goal criteria

> Requires FleetWrite and the current strong If-Match tag. Native version and generation checks run while holding the task lock. Controls preserve the accepted goal, cumulative usage and deadline. Ready resumes paused or blocked work within its remaining allowance; cancellation does not claim rollback of issued effects.



## OpenAPI

````yaml https://raw.githubusercontent.com/agentsfleet/agentsfleet/main/public/openapi.json patch /v1/workspaces/{workspace_id}/fleets/{fleet_id}/tasks/{task_id}
openapi: 3.1.0
info:
  title: agentsfleet API
  description: API for managing workspaces, fleets, triggers, and runs.
  contact:
    name: agentsfleet
    url: https://agentsfleet.net
  license:
    name: MIT
    identifier: MIT
  version: 1.0.0
servers:
  - url: https://api.agentsfleet.net
    description: Production
security: []
paths:
  /v1/workspaces/{workspace_id}/fleets/{fleet_id}/tasks/{task_id}:
    patch:
      tags:
        - Fleets
      summary: Control fleet work or adopt reviewed goal criteria
      description: >-
        Requires FleetWrite and the current strong If-Match tag. Native version
        and generation checks run while holding the task lock. Controls preserve
        the accepted goal, cumulative usage and deadline. Ready resumes paused
        or blocked work within its remaining allowance; cancellation does not
        claim rollback of issued effects.
      operationId: patch_fleet_task
      parameters:
        - name: workspace_id
          in: path
          description: >-
            Workspace identifier (version 7 universally unique identifier, or
            UUID).
          required: true
          schema:
            type: string
        - name: fleet_id
          in: path
          description: Fleet identifier (version 7 universally unique identifier, or UUID).
          required: true
          schema:
            type: string
        - name: task_id
          in: path
          description: Task UUIDv7.
          required: true
          schema:
            type: string
        - name: If-Match
          in: header
          description: Required current strong resource tag.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchTaskRequest'
        required: true
      responses:
        '200':
          description: Current task
          headers:
            ETag:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          description: Invalid task control
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '404':
          description: Task unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '409':
          description: Generation or lifecycle refuses mutation
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '412':
          description: Stale resource tag; problem body carries the current etag
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '413':
          description: Body too large
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '428':
          description: Missing tag
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '429':
          description: Task allowance or request limit reached
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '500':
          description: Internal failure
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
        '503':
          description: Dependency unavailable
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemBody'
      security:
        - BearerAuth: []
components:
  schemas:
    PatchTaskRequest:
      oneOf:
        - type: object
          description: Pause, resume or cancel without changing the accepted objective.
          required:
            - state
            - expected_generation
          properties:
            expected_generation:
              type: integer
              format: int64
              description: Generation from the task's current native context.
              minimum: 0
            state:
              $ref: '#/components/schemas/TaskControlState'
              description: Requested native lifecycle state.
        - type: object
          description: >-
            Adopt the completion criteria from an explicitly reviewed fleet
            revision.
          required:
            - goal_revision_id
            - expected_generation
            - operation_id
          properties:
            expected_generation:
              type: integer
              format: int64
              description: Generation read before requesting adoption.
              minimum: 0
            goal_revision_id:
              type: string
              description: Existing immutable setup revision belonging to this fleet.
            operation_id:
              type: string
              description: Stable retry identity for the same adoption.
      description: >-
        A conditional lifecycle control or explicit adoption of reviewed goal
        wording.
    TaskResponse:
      type: object
      description: Task detail with immutable success criteria and cumulative progress.
      required:
        - etag
        - title
        - resource_version
        - setup_revision
        - context
      properties:
        context:
          $ref: '#/components/schemas/TaskContext'
          description: Accepted objective, questions, cursors and remaining limits.
        dependency:
          oneOf:
            - $ref: '#/components/schemas/TaskDependency'
              description: >-
                Current native dependency and saved check results; no remote
                refresh is implied.
            - type: 'null'
        etag:
          type: string
          description: >-
            Strong version shared with the response header and conditional
            writes.
        publication:
          oneOf:
            - $ref: '#/components/schemas/TaskEffect'
              description: >-
                Latest publication receipt; only a confirmed receipt establishes
                a published head.
            - type: 'null'
        resource_version:
          type: integer
          format: int64
          description: Version used by the strong resource tag.
          minimum: 0
        setup_revision:
          type: integer
          format: int64
          description: Human-readable number of the immutable setup accepted by this task.
          minimum: 0
        title:
          type: string
          description: User-facing title.
    ProblemBody:
      type: object
      description: The body every refusal carries, under `application/problem+json`.
      required:
        - docs_uri
        - title
        - detail
        - error_code
        - request_id
      properties:
        action_id:
          type:
            - string
            - 'null'
          description: 'On that 409 only: the action the gate held.'
        current_state:
          type:
            - string
            - 'null'
          description: 'On a 409 only: the state that forbade the transition.'
        detail:
          type: string
          description: One sentence on what was refused and why.
        docs_uri:
          type: string
          description: Where the error code is documented.
        error_code:
          type: string
          description: The registry code, stable across releases.
        etag:
          type:
            - string
            - 'null'
          description: >-
            On a 412 only: the resource's current entity tag, to refetch and
            retry.
        gate_id:
          type:
            - string
            - 'null'
          description: 'On an answered approval gate''s 409 only: the gate that was answered.'
        outcome:
          type:
            - string
            - 'null'
          description: 'On that 409 only: the answer that stands.'
        request_id:
          type: string
          description: The request this refusal answers, for support.
        resolved_at:
          type:
            - string
            - 'null'
          format: date-time
          description: 'On that 409 only: when the standing answer was given.'
        resolved_by:
          type:
            - string
            - 'null'
          description: 'On that 409 only: who gave it.'
        title:
          type: string
          description: A short name for the refusal, safe to show a person.
        user_message:
          type:
            - string
            - 'null'
          description: A curated sentence for end users, where the code has one.
    TaskControlState:
      type: string
      description: Explicit human lifecycle control; completion requires native goal proof.
      enum:
        - paused
        - ready
        - cancelled
    TaskContext:
      type: object
      description: Context for a task-bound lease; ordinary leases omit this owner.
      required:
        - task_id
        - originating_item_id
        - target
        - generation
        - stop_generation
        - accepted_revision_id
        - objective
        - goal_digest
        - questions
        - state
        - covered_input_sequence
        - input_sequence
        - effect_cursor
        - confirmed_effect_watermark
        - expires_at
        - limits
        - usage
      properties:
        accepted_revision_id:
          type: string
          description: Fleet revision whose reviewed goal was accepted.
        checkpoint_generation:
          type:
            - integer
            - 'null'
          format: int64
          description: >-
            Last complete saved generation, distinct from allocated failed
            plans.
          minimum: 0
        checkpoint_id:
          type:
            - string
            - 'null'
          description: Compatible complete checkpoint, if one has been published.
        confirmed_effect_watermark:
          type: integer
          format: int64
          description: Last confirmed effect covered by the saved state.
          minimum: 0
        covered_input_sequence:
          type: integer
          format: int64
          description: Inputs whose meaning is included in the supplied state.
          minimum: 0
        effect_cursor:
          type: integer
          format: int64
          description: Native ordinal offered for the next immutable publication identity.
          minimum: 0
        expires_at:
          type: string
          format: date-time
          description: Existing wall deadline; waking does not extend it.
        generation:
          type: integer
          format: int64
          description: Generation the next semantic transition must assess.
          minimum: 0
        goal_digest:
          type: string
          description: Digest of the frozen objective and completion questions.
        input_sequence:
          type: integer
          format: int64
          description: >-
            Last accepted input; recovery must incorporate any gap before new
            effects.
          minimum: 0
        limits:
          $ref: '#/components/schemas/TaskLimits'
          description: Cumulative bounds, clamped by existing fleet/credit ceilings.
        objective:
          type: string
          description: Accepted objective, distinct from standing fleet instructions.
        originating_item_id:
          type: string
          description: Immutable source item required for attributable task effects.
        questions:
          type: array
          items:
            $ref: '#/components/schemas/NamedQuestion'
          description: >-
            Accepted questions with stable identities and complete reviewed
            criteria.
        state:
          $ref: '#/components/schemas/TaskState'
          description: Current durable state.
        stop_generation:
          type: integer
          format: int64
          description: Committed cutoff for new effects.
          minimum: 0
        target:
          $ref: '#/components/schemas/TaskTarget'
          description: >-
            Exact target selected by native admission, never changed by
            recovered notes.
        task_id:
          type: string
          description: Native task identity; never selected by a tool result.
        usage:
          $ref: '#/components/schemas/TaskUsage'
          description: Already consumed and reserved work.
    TaskDependency:
      type: object
      description: Current native dependency; reading it launches no remote checks.
      required:
        - active
        - head
        - checks
        - updated_at
      properties:
        active:
          type: boolean
          description: Whether this observation still owns an unconsumed, uncancelled wait.
        checks:
          type: array
          items:
            $ref: '#/components/schemas/TaskCheck'
          description: Saved observations of the reviewed workflows.
        head:
          type: string
          description: Exact branch head this wait observes.
        updated_at:
          type: string
          format: date-time
          description: >-
            Time the native wait was updated; not a fresh provider observation
            time.
    TaskEffect:
      type: object
      description: No token or arbitrary remote response is exposed in this receipt.
      required:
        - effect_id
        - ordinal
        - state
        - expected_head
        - tested_tree
        - pull_request_url
      properties:
        commit:
          type:
            - string
            - 'null'
          description: Confirmed commit only after native readback.
        effect_id:
          type: string
          description: >-
            Native effect `UUIDv7` discoverable after replacement-worker
            recovery.
        expected_head:
          type: string
          description: Recorded expected branch head.
        ordinal:
          type: integer
          format: int64
          description: Task-local publication order, independent of response delivery.
          minimum: 0
        pull_request_url:
          type: string
          description: Exact accepted PR URL.
        state:
          $ref: '#/components/schemas/TaskEffectState'
          description: Native state.
        tested_tree:
          type: string
          description: Verified candidate tree.
    TaskLimits:
      type: object
      description: Approved initial limits; a smaller existing fleet or credit limit wins.
      required:
        - model_nanos
        - wall_seconds
        - running_seconds
        - leases
        - publications
        - decision_calls
        - fallback_reads
      properties:
        decision_calls:
          type: integer
          format: int32
          description: Maximum physical decision calls, including retries.
          minimum: 0
        fallback_reads:
          type: integer
          format: int32
          description: Maximum fallback dependency reads; signed events remain separate.
          minimum: 0
        leases:
          type: integer
          format: int32
          description: Maximum distinct issued leases.
          minimum: 0
        model_nanos:
          $ref: '#/components/schemas/Nanos'
          description: Total paid-model allowance, in whole nanodollars.
        publications:
          type: integer
          format: int32
          description: Maximum physical repair publication attempts.
          minimum: 0
        running_seconds:
          type: integer
          format: int32
          description: Cumulative running time across all attempts.
          minimum: 0
        wall_seconds:
          type: integer
          format: int32
          description: Wall-clock lifetime including paused and waiting time.
          minimum: 0
      additionalProperties: false
    NamedQuestion:
      type: object
      description: Names are stable question identities, not model-generated output keys.
      required:
        - name
        - question
      properties:
        name:
          type: string
          description: Native question identity echoed by every adapter.
        question:
          $ref: '#/components/schemas/DecisionQuestion'
          description: Reviewed question representation.
      additionalProperties: false
    TaskState:
      type: string
      description: The durable objective's state, independent of its current admission.
      enum:
        - ready
        - running
        - waiting
        - blocked
        - paused
        - done
        - cancelled
        - exhausted
    TaskTarget:
      oneOf:
        - type: object
          description: >-
            Repository-free work cannot acquire a coding checkout by
            implication.
          required:
            - kind
          properties:
            kind:
              type: string
              enum:
                - api_only
        - type: object
          description: Explicitly accepted existing same-repository pull request.
          required:
            - repository
            - repository_id
            - number
            - branch
            - base
            - head
            - tree
            - url
            - workflows
            - kind
          properties:
            base:
              type: string
              description: Accepted base branch.
            branch:
              type: string
              description: Writable non-protected branch selected by native admission.
            head:
              type: string
              description: Latest native confirmed branch head.
            kind:
              type: string
              enum:
                - existing_pr
            number:
              type: integer
              format: int32
              description: Accepted pull request number.
              minimum: 0
            repository:
              type: string
              description: Canonical owner/name from GitHub, never a guessed repository.
            repository_id:
              type: integer
              format: int64
              description: Immutable native repository identity.
              minimum: 0
            tree:
              type: string
              description: Tree at that head.
            url:
              type: string
              description: Confirmed pull request link.
            workflows:
              type: array
              items:
                $ref: '#/components/schemas/TaskWorkflow'
              description: >-
                Owner-reviewed validation identities, never arbitrary workflow
                names.
      description: No repository is required for a repair performed only through APIs.
    TaskUsage:
      type: object
      description: Measured usage retained on the objective, including stopped attempts.
      required:
        - model_nanos
        - reserved_model_nanos
        - running_nanos
        - leases
        - publications
        - decision_calls
        - fallback_reads
      properties:
        decision_calls:
          type: integer
          format: int32
          description: Physical decision calls, including retries.
          minimum: 0
        fallback_reads:
          type: integer
          format: int32
          description: Fallback dependency reads already consumed.
          minimum: 0
        leases:
          type: integer
          format: int32
          description: Distinct issued leases.
          minimum: 0
        model_nanos:
          $ref: '#/components/schemas/Nanos'
          description: Measured paid-model cost, including coding and decision calls.
        publications:
          type: integer
          format: int32
          description: Physical publication attempts.
          minimum: 0
        reserved_model_nanos:
          $ref: '#/components/schemas/Nanos'
          description: Outstanding native model-call reservations.
        running_nanos:
          type: integer
          format: int64
          description: Cumulative measured running time, in nanoseconds.
          minimum: 0
      additionalProperties: false
    TaskCheck:
      type: object
      description: One reviewed workflow's last recorded exact-head observation.
      required:
        - workflow_id
        - status
      properties:
        conclusion:
          type:
            - string
            - 'null'
          description: Recorded provider conclusion; absent until known.
        run_attempt:
          type:
            - integer
            - 'null'
          format: int32
          description: Observed attempt within the run.
          minimum: 0
        run_id:
          type:
            - integer
            - 'null'
          format: int64
          description: Observed workflow run, absent when none exists.
          minimum: 0
        run_number:
          type:
            - integer
            - 'null'
          format: int64
          description: Observed workflow run number.
          minimum: 0
        status:
          type: string
          description: Recorded provider status; absence of a run is pending.
        workflow_id:
          type: integer
          format: int64
          description: Reviewed GitHub workflow identity.
          minimum: 0
    TaskEffectState:
      type: string
      description: Native publication state, retained independently of a runner response.
      enum:
        - prepared
        - issued
        - confirmed
        - unknown
        - refused
    Nanos:
      type: string
      description: A whole number of nanos (10⁻⁹ US dollars) as a decimal string.
      pattern: ^(0|[1-9][0-9]*)$
    DecisionQuestion:
      oneOf:
        - type: object
          description: True/false assessment with explicit criteria.
          required:
            - instructions
            - criteria
            - type
          properties:
            criteria:
              $ref: '#/components/schemas/NoulCriteria'
              description: Reviewed criteria for both answers.
            instructions:
              type: string
              description: The question to evaluate.
            type:
              type: string
              enum:
                - noul
        - type: object
          description: Choice among a complete fixed option set.
          required:
            - instructions
            - options
            - type
          properties:
            instructions:
              type: string
              description: The question to evaluate.
            options:
              type: array
              items:
                $ref: '#/components/schemas/ChoiceOption'
              description: >-
                Sixteen eligible tasks plus new-work and unclear fit without
                truncation.
            type:
              type: string
              enum:
                - choice
        - type: object
          description: Probability-weighted rating over an ordered rubric.
          required:
            - instructions
            - levels
            - type
          properties:
            instructions:
              type: string
              description: The question to evaluate.
            levels:
              type: array
              items:
                type: string
              description: Rubric from lowest to highest, with zero-based numeric levels.
            type:
              type: string
              enum:
                - score
      description: The typed question forms used for intent and goal evaluation.
    TaskWorkflow:
      type: object
      description: Frozen owner-reviewed validation identity.
      required:
        - id
        - path
        - digest
      properties:
        digest:
          type: string
          description: Owner-reviewed exact bytes.
        id:
          type: integer
          format: int64
          description: Native GitHub workflow identity.
          minimum: 0
        path:
          type: string
          description: Owner-reviewed path.
    NoulCriteria:
      type: object
      description: Accepted meanings of a true and false assessment.
      required:
        - 'true'
        - 'false'
      properties:
        'false':
          type: string
          description: Evidence supporting no.
        'true':
          type: string
          description: Evidence supporting yes.
      additionalProperties: false
    ChoiceOption:
      type: object
      description: One mutually exclusive choice with its reviewed meaning.
      required:
        - value
        - description
      properties:
        description:
          type: string
          description: Reviewed semantic meaning, never an authority grant.
        value:
          type: string
          description: >-
            Stable option identity, including native task identities when
            associating.
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Send a dashboard session token, an account API key (`agt_t`), or a
        command-line credential (`afc_`) as a Bearer token. Each endpoint lists
        accepted credential types.

````

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