Terminal Use Tasks API

openapi: 3.1.0
info:
  title: Sb0 Agent APIKeys Tasks API
  version: 0.1.0
tags:
- name: Tasks
paths:
  /tasks:
    get:
      description: List all tasks.
      operationId: tasks_list
      parameters:
      - description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
        in: query
        name: agent_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
          title: Agent Id
      - in: query
        name: namespace_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Namespace Id
      - in: query
        name: agent_name
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
      - in: query
        name: branch_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Branch Id
      - in: query
        name: status
        required: false
        schema:
          items:
            $ref: '#/components/schemas/TaskStatus'
          title: Status
          type: array
      - in: query
        name: created_after
        required: false
        schema:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Created After
      - in: query
        name: created_before
        required: false
        schema:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          title: Created Before
      - in: query
        name: include_total
        required: false
        schema:
          default: false
          title: Include Total
          type: boolean
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          title: Limit
          type: integer
      - in: query
        name: page_number
        required: false
        schema:
          default: 1
          title: Page Number
          type: integer
      - in: query
        name: order_by
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Order By
      - in: query
        name: order_direction
        required: false
        schema:
          default: desc
          title: Order Direction
          type: string
      - in: query
        name: relationships
        required: false
        schema:
          items:
            $ref: '#/components/schemas/TaskRelationships'
          title: Relationships
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/TaskResponse'
                title: Response Tasks List
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Tasks
      tags:
      - Tasks
    post:
      description: Create a new task for an agent.
      operationId: tasks_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Create Task
      tags:
      - Tasks
  /tasks/migrate:
    post:
      description: 'Migrate tasks between versions within the same branch. Supports two modes: bulk migration by source version (from_version_id), or migration of specific tasks (task_ids). Target can be explicit (to_version_id) or latest active version (to_latest).'
      operationId: tasks_migrate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MigrateTasksRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MigrateTasksResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Migrate Tasks Between Versions
      tags:
      - Tasks
  /tasks/name/{task_name}:
    delete:
      description: Delete a task by its unique name.
      operationId: tasks_delete_by_name
      parameters:
      - in: path
        name: task_name
        required: true
        schema:
          title: Task Name
          type: string
      - description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
        in: query
        name: agent_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
          title: Agent Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete Task by Name
      tags:
      - Tasks
    get:
      description: Get a task by its unique name.
      operationId: tasks_retrieve_by_name
      parameters:
      - in: path
        name: task_name
        required: true
        schema:
          title: Task Name
          type: string
      - in: query
        name: relationships
        required: false
        schema:
          items:
            $ref: '#/components/schemas/TaskRelationships'
          title: Relationships
          type: array
      - description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
        in: query
        name: agent_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
          title: Agent Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Task by Name
      tags:
      - Tasks
    put:
      description: Update mutable fields for a task by its unique Name.
      operationId: tasks_update_by_name
      parameters:
      - in: path
        name: task_name
        required: true
        schema:
          title: Task Name
          type: string
      - description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
        in: query
        name: agent_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
          title: Agent Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update Task by Name
      tags:
      - Tasks
  /tasks/name/{task_name}/stream:
    get:
      description: "Stream events for a task by its unique name using Server-Sent Events (SSE).\n\n    Supports automatic reconnection with Last-Event-ID header. When the client\n    reconnects, it sends the Last-Event-ID header with the last received event ID,\n    and the server resumes from that point.\n\n    Returns TextStreamPart events (Vercel AI SDK compatible format)."
      operationId: tasks_stream_by_name
      parameters:
      - in: path
        name: task_name
        required: true
        schema:
          title: Task Name
          type: string
      - description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
        in: query
        name: agent_id
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional agent filter. When provided, we authorize it via direct OpenFGA Check and avoid ListObjects(agent) to prevent false 403s from transient/partial list results.
          title: Agent Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextStreamPartWrapper'
          description: SSE stream of TextStreamPart events
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Stream Task Events by Name
      tags:
      - Tasks
      x-fern-streaming:
        format: sse
  /tasks/{task_id}:
    delete:
      description: Delete a task by its unique ID.
      operationId: tasks_delete
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete Task by ID
      tags:
      - Tasks
    get:
      description: Get a task by its unique ID.
      operationId: tasks_retrieve
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      - in: query
        name: relationships
        required: false
        schema:
          items:
            $ref: '#/components/schemas/TaskRelationships'
          title: Relationships
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get Task by ID
      tags:
      - Tasks
    put:
      description: Update mutable fields for a task by its unique ID.
      operationId: tasks_update
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTaskRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Update Task by ID
      tags:
      - Tasks
  /tasks/{task_id}/cancel:
    post:
      description: Cancel a running task.
      operationId: tasks_cancel
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Cancel Task
      tags:
      - Tasks
  /tasks/{task_id}/events:
    post:
      description: Send an event to a running task.
      operationId: tasks_send_event
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskEventRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Send Event to Task
      tags:
      - Tasks
      x-fern-retries:
        disabled: true
  /tasks/{task_id}/handler-end:
    post:
      description: Signal that an ACP handler has finished processing an event.
      operationId: tasks_handler_end
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HandlerEndRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandlerEndResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Handler End
      tags:
      - Tasks
  /tasks/{task_id}/stream:
    get:
      description: "Stream events for a task by its unique ID using Server-Sent Events (SSE).\n\n    Supports automatic reconnection with Last-Event-ID header. When the client\n    reconnects, it sends the Last-Event-ID header with the last received event ID,\n    and the server resumes from that point.\n\n    Returns TextStreamPart events (Vercel AI SDK compatible format)."
      operationId: tasks_stream
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextStreamPartWrapper'
          description: SSE stream of TextStreamPart events
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Stream Task Events by ID
      tags:
      - Tasks
      x-fern-streaming:
        format: sse
  /tasks/{task_id}/system-folder-types:
    get:
      description: Get all registered system folder types with their configurations for a task.
      operationId: tasks_list_system_folder_types
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SystemFolderTypeResponse'
                title: Response Tasks List System Folder Types
                type: array
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List System Folder Types
      tags:
      - Tasks
  /tasks/{task_id}/system-folders/{folder_type}:
    get:
      description: Get a task's system folder record by type.
      operationId: tasks_get_system_folder
      parameters:
      - in: path
        name: folder_type
        required: true
        schema:
          $ref: '#/components/schemas/SystemFolderType'
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/SystemFolderResponse'
                - type: 'null'
                title: Response Tasks Get System Folder
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get System Folder
      tags:
      - Tasks
  /tasks/{task_id}/system-folders/{folder_type}/download-url:
    post:
      description: Get a presigned URL for direct download of a system folder archive from GCS.
      operationId: tasks_get_system_folder_download_url
      parameters:
      - in: path
        name: folder_type
        required: true
        schema:
          $ref: '#/components/schemas/SystemFolderType'
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/PresignedUrlRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/PresignedUrlResponse'
                - type: 'null'
                title: Response Tasks Get System Folder Download Url
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get System Folder Download URL
      tags:
      - Tasks
  /tasks/{task_id}/system-folders/{folder_type}/sync-complete:
    post:
      description: Complete a system folder sync operation and update metadata.
      operationId: tasks_system_folder_sync_complete
      parameters:
      - in: path
        name: folder_type
        required: true
        schema:
          $ref: '#/components/schemas/SystemFolderType'
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SystemFolderSyncCompleteRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemFolderSyncCompleteResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Complete System Folder Sync
      tags:
      - Tasks
  /tasks/{task_id}/system-folders/{folder_type}/upload-url:
    post:
      description: Get a presigned URL for direct upload of a system folder archive to GCS.
      operationId: tasks_get_system_folder_upload_url
      parameters:
      - in: path
        name: folder_type
        required: true
        schema:
          $ref: '#/components/schemas/SystemFolderType'
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/PresignedUrlRequest'
              - type: 'null'
              title: Request
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresignedUrlResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Get System Folder Upload URL
      tags:
      - Tasks
components:
  schemas:
    ToolInputEndPart:
      description: Marks the end of tool input streaming.
      properties:
        id:
          description: Tool call ID
          title: Id
          type: string
        metadata:
          anyOf:
          - $ref: '#/components/schemas/StreamMetadata'
          - type: 'null'
          description: Metadata including parentToolUseId for subagents
        type:
          const: tool-input-end
          default: tool-input-end
          title: Type
          type: string
      required:
      - id
      title: ToolInputEndPart
      type: object
    HandlerEndResponse:
      properties:
        handler_status:
          title: Handler Status
          type: string
        task_status:
          title: Task Status
          type: string
      required:
      - handler_status
      - task_status
      title: HandlerEndResponse
      type: object
    StreamUsage:
      description: Token usage for streaming events.
      properties:
        inputTokens:
          description: Input tokens used
          title: Inputtokens
          type: integer
        outputTokens:
          description: Output tokens used
          title: Outputtokens
          type: integer
        totalTokens:
          anyOf:
          - type: integer
          - type: 'null'
          description: Total tokens
          title: Totaltokens
      required:
      - inputTokens
      - outputTokens
      title: StreamUsage
      type: object
    VersionResponse:
      description: Full version details.
      properties:
        acp_type:
          $ref: '#/components/schemas/ACPType'
          description: Type of ACP server (sync or async)
        author_email:
          description: Commit author email
          title: Author Email
          type: string
        author_name:
          description: Commit author name
          title: Author Name
          type: string
        branch_id:
          description: Parent branch ID
          title: Branch Id
          type: string
        created_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: Creation timestamp
          title: Created At
        deployed_at:
          description: When this version was deployed
          format: date-time
          title: Deployed At
          type: string
        failure_diagnostics:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          description: User-facing failure diagnostics with 'title', 'description', and 'action' fields
          title: Failure Diagnostics
        failure_reason:
          anyOf:
          - type: string
          - type: 'null'
          description: Classified failure reason when status is FAILED (e.g., 'image_pull_failed', 'crash_loop', 'scheduling_failed')
          title: Failure Reason
        git_branch:
          description: Git branch name
          title: Git Branch
          type: string
        git_hash:
          description: Git commit hash
          title: Git Hash
          type: string
        git_message:
          default: ''
          description: Git commit message
          title: Git Message
          type: string
        id:
          description: Version ID
          title: Id
          type: string
        image_expires_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When image expires (for rollback window)
          title: Image Expires At
        image_url:
          description: Container image URL
          title: Image Url
          type: string
        is_dirty:
          default: false
          description: Whether the commit had uncommitted changes
          title: Is Dirty
          type: boolean
        last_rollback_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: Timestamp when this version was last rolled back TO
          title: Last Rollback At
        replicas:
          default: 0
          description: Current pod count for this version
          title: Replicas
          type: integer
        retired_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When version was retired
          title: Retired At
        rollback_count:
          default: 0
          description: Number of rollbacks to this version
          title: Rollback Count
          type: integer
        rolled_back_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: Timestamp when this version was rolled back FROM
          title: Rolled Back At
        sdk_type:
          $ref: '#/components/schemas/SDKType'
          description: SDK type for agent runtime
        source_filesystem_id:
          anyOf:
          - type: string
          - type: 'null'
          description: Filesystem snapshot that can reopen this version in Agent Builder
          title: Source Filesystem Id
        status:
          $ref: '#/components/schemas/VersionStatus'
          description: Version lifecycle status
        updated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: Last update timestamp
          title: Updated At
      required:
      - id
      - branch_id
      - git_hash
      - git_branch
      - author_name
      - author_email
      - image_url
      - status
      - deployed_at
      - sdk_type
      - acp_type
      title: VersionResponse
      type: object
    ACPType:
      description: Type of ACP server.
      enum:
      - sync
      - async
      title: ACPType
      type: string
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    TextPart:
      description: Text content part.
      properties:
        text:
          description: The text content
          title: Text
          type: string
        type:
          const: text
          default: text
          description: Part type discriminator
          title: Type
          type: string
      required:
      - text
      title: TextPart
      type: object
    DeleteResponse:
      properties:
        id:
          title: Id
          type: string
        message:
          title: Message
          type: string
      required:
      - id
      - message
      title: DeleteResponse
      type: object
    ToolResultPart:
      description: Tool execution result.
      properties:
        metadata:
          anyOf:
          - $ref: '#/components/schemas/StreamMetadata'
          - type: 'null'
          description: Metadata including parentToolUseId for subagents
        output:
          description: Tool output
          title: Output
        toolCallId:
          description: Tool call ID
          title: Toolcallid
          type: string
        toolName:
          description: Name of the tool
          title: Toolname
          type: string
        type:
          const: tool-result
          default: tool-result
          title: Type
          type: string
      required:
      - toolCallId
      - toolName
      - output
      title: ToolResultPart
      type: object
    PresignedUrlResponse:
      description: Response model for presigned URL operations.
      properties:
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          description: Content-Type header to use (required for PUT uploads).
          title: Content Type
        expires_at:
          description: When the presigned URL expires.
          format: date-time
          title: Expires At
          type: string
        instructions:
          description: Instructions for using the presigned URL.
          title: Instructions
          type: string
        method:
          description: 'HTTP method to use: ''PUT'' for upload, ''GET'' for download.'
          title: Method
          type: string
        url:
          description: The presigned URL for direct GCS upload/download.
          title: Url
          type: string
      required:
      - url
      - expires_at
      - method
      - instructions
      title: PresignedUrlResponse
      type: object
    PresignedUrlRequest:
      description: Request model for presigned URL generation.
      properties:
        expiration_seconds:
          default: 3600
          description: URL expiration time in seconds (default 1 hour, max 7 days).
          maximum: 604800
          minimum: 60
          title: Expiration Seconds
          type: integer
      title: PresignedUrlRequest
      type: object
    CreateTaskEventRequest:
      description: 'Request for POST /tasks/{task_id}/events


        Content accepts TextPart or DataPart only. Other message types (tool calls,

        reasoning, etc.) are agent-generated and sent via the /raw-events endpoint.'
      properties:
        content:
          anyOf:
          - $ref: '#/components/schemas/TextPart'
          - $ref: '#/components/schemas/DataPart'
          - type: 'null'
          description: Event content
          title: Content
        idempotency_key:
          anyOf:
          - maxLength: 256
            minLength: 1
            type: string
          - type: 'null'
          description: Optional idempotency key for retry-safe event delivery.
          title: Idempotency Key
        persist_message:
          de

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/terminal-use/refs/heads/main/openapi/terminal-use-tasks-api-openapi.yml