openapi: 3.0.3
info:
  description: Coderd is the service created by running coder server. It is a thin API that connects workspaces, provisioners and users. coderd stores its state in Postgres and is the only service that communicates with Postgres.
  title: Coder Agents Tasks API
  termsOfService: https://coder.com/legal/terms-of-service
  contact:
    name: API Support
    url: https://coder.com
    email: support@coder.com
  license:
    name: AGPL-3.0
    url: https://github.com/coder/coder/blob/main/LICENSE
  version: '2.0'
servers:
- url: https://{coderHost}/api/v2
  description: Coder instance
  variables:
    coderHost:
      default: coder.example.com
      description: Your Coder deployment hostname
security:
- CoderSessionToken: []
tags:
- name: Tasks
paths:
  /api/v2/tasks:
    get:
      operationId: list-ai-tasks
      summary: List AI tasks
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: q
        in: query
        required: false
        description: 'Search query for filtering tasks. Supports: owner:<username/uuid/me>, organization:<org-name/uuid>, status:<status>'
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.TasksListResponse'
  /api/v2/tasks/{user}:
    post:
      operationId: create-a-new-ai-task
      summary: Create a new AI task
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: user
        in: path
        required: true
        description: Username, user ID, or 'me' for the authenticated user
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.CreateTaskRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Task'
  /api/v2/tasks/{user}/{task}:
    get:
      operationId: get-ai-task-by-id-or-name
      summary: Get AI task by ID or name
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: user
        in: path
        required: true
        description: Username, user ID, or 'me' for the authenticated user
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task ID, or task name
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.Task'
    delete:
      operationId: delete-ai-task
      summary: Delete AI task
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: user
        in: path
        required: true
        description: Username, user ID, or 'me' for the authenticated user
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task ID, or task name
        schema:
          type: string
      responses:
        '202':
          description: Accepted
  /api/v2/tasks/{user}/{task}/input:
    patch:
      operationId: update-ai-task-input
      summary: Update AI task input
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: user
        in: path
        required: true
        description: Username, user ID, or 'me' for the authenticated user
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task ID, or task name
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.UpdateTaskInputRequest'
      responses:
        '204':
          description: No Content
  /api/v2/tasks/{user}/{task}/logs:
    get:
      operationId: get-ai-task-logs
      summary: Get AI task logs
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: user
        in: path
        required: true
        description: Username, user ID, or 'me' for the authenticated user
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task ID, or task name
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.TaskLogsResponse'
  /api/v2/tasks/{user}/{task}/pause:
    post:
      operationId: pause-task
      summary: Pause task
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: user
        in: path
        required: true
        description: Username, user ID, or 'me' for the authenticated user
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task ID
        schema:
          type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.PauseTaskResponse'
  /api/v2/tasks/{user}/{task}/resume:
    post:
      operationId: resume-task
      summary: Resume task
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: user
        in: path
        required: true
        description: Username, user ID, or 'me' for the authenticated user
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task ID
        schema:
          type: string
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/codersdk.ResumeTaskResponse'
  /api/v2/tasks/{user}/{task}/send:
    post:
      operationId: send-input-to-ai-task
      summary: Send input to AI task
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: user
        in: path
        required: true
        description: Username, user ID, or 'me' for the authenticated user
        schema:
          type: string
      - name: task
        in: path
        required: true
        description: Task ID, or task name
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/codersdk.TaskSendRequest'
      responses:
        '204':
          description: No Content
  /api/v2/workspaceagents/me/tasks/{task}/log-snapshot:
    post:
      operationId: upload-task-log-snapshot
      summary: Upload task log snapshot
      tags:
      - Tasks
      security:
      - CoderSessionToken: []
      parameters:
      - name: task
        in: path
        required: true
        description: Task ID
        schema:
          type: string
      - name: format
        in: query
        required: true
        description: Snapshot format
        schema:
          type: string
          enum:
          - agentapi
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '204':
          description: No Content
components:
  schemas:
    codersdk.BuildReason:
      type: string
      enum:
      - initiator
      - autostart
      - autostop
      - dormancy
      - dashboard
      - cli
      - ssh_connection
      - vscode_connection
      - jetbrains_connection
      - task_auto_pause
      - task_manual_pause
      - task_resume
    codersdk.AgentSubsystem:
      type: string
      enum:
      - envbox
      - envbuilder
      - exectrace
    codersdk.TaskState:
      type: string
      enum:
      - working
      - idle
      - complete
      - failed
    codersdk.DisplayApp:
      type: string
      enum:
      - vscode
      - vscode_insiders
      - web_terminal
      - port_forwarding_helper
      - ssh_helper
    codersdk.WorkspaceAgentHealth:
      type: object
      properties:
        healthy:
          type: boolean
          description: Healthy is true if the agent is healthy.
          example: false
        reason:
          type: string
          description: Reason is a human-readable explanation of the agent's health. It is empty if Healthy is true.
          example: agent has lost connection
    codersdk.WorkspaceBuild:
      type: object
      properties:
        build_number:
          type: integer
        created_at:
          type: string
          format: date-time
        daily_cost:
          type: integer
        deadline:
          type: string
          format: date-time
        has_ai_task:
          type: boolean
          description: 'Deprecated: This field has been deprecated in favor of Task WorkspaceID.'
        has_external_agent:
          type: boolean
        id:
          type: string
          format: uuid
        initiator_id:
          type: string
          format: uuid
        initiator_name:
          type: string
        job:
          $ref: '#/components/schemas/codersdk.ProvisionerJob'
        matched_provisioners:
          $ref: '#/components/schemas/codersdk.MatchedProvisioners'
        max_deadline:
          type: string
          format: date-time
        reason:
          enum:
          - initiator
          - autostart
          - autostop
          allOf:
          - $ref: '#/components/schemas/codersdk.BuildReason'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.WorkspaceResource'
        status:
          enum:
          - pending
          - starting
          - running
          - stopping
          - stopped
          - failed
          - canceling
          - canceled
          - deleting
          - deleted
          allOf:
          - $ref: '#/components/schemas/codersdk.WorkspaceStatus'
        template_version_id:
          type: string
          format: uuid
        template_version_name:
          type: string
        template_version_preset_id:
          type: string
          format: uuid
        transition:
          enum:
          - start
          - stop
          - delete
          allOf:
          - $ref: '#/components/schemas/codersdk.WorkspaceTransition'
        updated_at:
          type: string
          format: date-time
        workspace_id:
          type: string
          format: uuid
        workspace_name:
          type: string
        workspace_owner_avatar_url:
          type: string
        workspace_owner_id:
          type: string
          format: uuid
        workspace_owner_name:
          type: string
          description: WorkspaceOwnerName is the username of the owner of the workspace.
    codersdk.PauseTaskResponse:
      type: object
      properties:
        workspace_build:
          $ref: '#/components/schemas/codersdk.WorkspaceBuild'
    uuid.NullUUID:
      type: object
      properties:
        uuid:
          type: string
        valid:
          type: boolean
          description: Valid is true if UUID is not NULL
    codersdk.UpdateTaskInputRequest:
      type: object
      properties:
        input:
          type: string
    codersdk.ProvisionerJobStatus:
      type: string
      enum:
      - pending
      - running
      - succeeded
      - canceling
      - canceled
      - failed
      - unknown
    codersdk.DERPRegion:
      type: object
      properties:
        latency_ms:
          type: number
        preferred:
          type: boolean
    codersdk.TaskLogsResponse:
      type: object
      properties:
        logs:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.TaskLogEntry'
        snapshot:
          type: boolean
        snapshot_at:
          type: string
    codersdk.ResumeTaskResponse:
      type: object
      properties:
        workspace_build:
          $ref: '#/components/schemas/codersdk.WorkspaceBuild'
    codersdk.WorkspaceAgentScriptStatus:
      type: string
      enum:
      - ok
      - exit_failure
      - timed_out
      - pipes_left_open
    codersdk.ProvisionerJobType:
      type: string
      enum:
      - template_version_import
      - workspace_build
      - template_version_dry_run
    codersdk.WorkspaceAgentStartupScriptBehavior:
      type: string
      enum:
      - blocking
      - non-blocking
    codersdk.WorkspaceApp:
      type: object
      properties:
        command:
          type: string
        display_name:
          type: string
          description: DisplayName is a friendly name for the app.
        external:
          type: boolean
          description: 'External specifies whether the URL should be opened externally on

            the client or not.'
        group:
          type: string
        health:
          $ref: '#/components/schemas/codersdk.WorkspaceAppHealth'
        healthcheck:
          description: Healthcheck specifies the configuration for checking app health.
          allOf:
          - $ref: '#/components/schemas/codersdk.Healthcheck'
        hidden:
          type: boolean
        icon:
          type: string
          description: 'Icon is a relative path or external URL that specifies

            an icon to be displayed in the dashboard.'
        id:
          type: string
          format: uuid
        open_in:
          $ref: '#/components/schemas/codersdk.WorkspaceAppOpenIn'
        sharing_level:
          enum:
          - owner
          - authenticated
          - organization
          - public
          allOf:
          - $ref: '#/components/schemas/codersdk.WorkspaceAppSharingLevel'
        slug:
          type: string
          description: Slug is a unique identifier within the agent.
        statuses:
          type: array
          description: Statuses is a list of statuses for the app.
          items:
            $ref: '#/components/schemas/codersdk.WorkspaceAppStatus'
        subdomain:
          type: boolean
          description: 'Subdomain denotes whether the app should be accessed via a path on the

            `coder server` or via a hostname-based dev URL. If this is set to true

            and there is no app wildcard configured on the server, the app will not

            be accessible in the UI.'
        subdomain_name:
          type: string
          description: SubdomainName is the application domain exposed on the `coder server`.
        tooltip:
          type: string
          description: 'Tooltip is an optional markdown supported field that is displayed

            when hovering over workspace apps in the UI.'
        url:
          type: string
          description: 'URL is the address being proxied to inside the workspace.

            If external is specified, this will be opened on the client.'
    codersdk.WorkspaceAgentLifecycle:
      type: string
      enum:
      - created
      - starting
      - start_timeout
      - start_error
      - ready
      - shutting_down
      - shutdown_timeout
      - shutdown_error
      - 'off'
    codersdk.WorkspaceAppStatusState:
      type: string
      enum:
      - working
      - idle
      - complete
      - failure
    codersdk.WorkspaceAppStatus:
      type: object
      properties:
        agent_id:
          type: string
          format: uuid
        app_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        icon:
          type: string
          description: 'Deprecated: This field is unused and will be removed in a future version.

            Icon is an external URL to an icon that will be rendered in the UI.'
        id:
          type: string
          format: uuid
        message:
          type: string
        needs_user_attention:
          type: boolean
          description: 'Deprecated: This field is unused and will be removed in a future version.

            NeedsUserAttention specifies whether the status needs user attention.'
        state:
          $ref: '#/components/schemas/codersdk.WorkspaceAppStatusState'
        uri:
          type: string
          description: 'URI is the URI of the resource that the status is for.

            e.g. https://github.com/org/repo/pull/123

            e.g. file:///path/to/file'
        workspace_id:
          type: string
          format: uuid
    codersdk.WorkspaceResource:
      type: object
      properties:
        agents:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.WorkspaceAgent'
        created_at:
          type: string
          format: date-time
        daily_cost:
          type: integer
        hide:
          type: boolean
        icon:
          type: string
        id:
          type: string
          format: uuid
        job_id:
          type: string
          format: uuid
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.WorkspaceResourceMetadata'
        name:
          type: string
        type:
          type: string
        workspace_transition:
          enum:
          - start
          - stop
          - delete
          allOf:
          - $ref: '#/components/schemas/codersdk.WorkspaceTransition'
    codersdk.WorkspaceStatus:
      type: string
      enum:
      - pending
      - starting
      - running
      - stopping
      - stopped
      - failed
      - canceling
      - canceled
      - deleting
      - deleted
    codersdk.TaskSendRequest:
      type: object
      properties:
        input:
          type: string
    codersdk.WorkspaceAgent:
      type: object
      properties:
        api_version:
          type: string
        apps:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.WorkspaceApp'
        architecture:
          type: string
        connection_timeout_seconds:
          type: integer
        created_at:
          type: string
          format: date-time
        directory:
          type: string
        disconnected_at:
          type: string
          format: date-time
        display_apps:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.DisplayApp'
        environment_variables:
          type: object
          additionalProperties:
            type: string
        expanded_directory:
          type: string
        first_connected_at:
          type: string
          format: date-time
        health:
          description: Health reports the health of the agent.
          allOf:
          - $ref: '#/components/schemas/codersdk.WorkspaceAgentHealth'
        id:
          type: string
          format: uuid
        instance_id:
          type: string
        last_connected_at:
          type: string
          format: date-time
        latency:
          type: object
          description: DERPLatency is mapped by region name (e.g. "New York City", "Seattle").
          additionalProperties:
            $ref: '#/components/schemas/codersdk.DERPRegion'
        lifecycle_state:
          $ref: '#/components/schemas/codersdk.WorkspaceAgentLifecycle'
        log_sources:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.WorkspaceAgentLogSource'
        logs_length:
          type: integer
        logs_overflowed:
          type: boolean
        name:
          type: string
        operating_system:
          type: string
        parent_id:
          format: uuid
          allOf:
          - $ref: '#/components/schemas/uuid.NullUUID'
        ready_at:
          type: string
          format: date-time
        resource_id:
          type: string
          format: uuid
        scripts:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.WorkspaceAgentScript'
        started_at:
          type: string
          format: date-time
        startup_script_behavior:
          description: 'StartupScriptBehavior is a legacy field that is deprecated in favor

            of the `coder_script` resource. It''s only referenced by old clients.

            Deprecated: Remove in the future!'
          allOf:
          - $ref: '#/components/schemas/codersdk.WorkspaceAgentStartupScriptBehavior'
        status:
          $ref: '#/components/schemas/codersdk.WorkspaceAgentStatus'
        subsystems:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.AgentSubsystem'
        troubleshooting_url:
          type: string
        updated_at:
          type: string
          format: date-time
        version:
          type: string
    codersdk.WorkspaceAppHealth:
      type: string
      enum:
      - disabled
      - initializing
      - healthy
      - unhealthy
    codersdk.ProvisionerJob:
      type: object
      properties:
        available_workers:
          type: array
          items:
            type: string
            format: uuid
        canceled_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        error:
          type: string
        error_code:
          enum:
          - REQUIRED_TEMPLATE_VARIABLES
          - INSUFFICIENT_QUOTA
          allOf:
          - $ref: '#/components/schemas/codersdk.JobErrorCode'
        file_id:
          type: string
          format: uuid
        id:
          type: string
          format: uuid
        initiator_id:
          type: string
          format: uuid
        input:
          $ref: '#/components/schemas/codersdk.ProvisionerJobInput'
        logs_overflowed:
          type: boolean
        metadata:
          $ref: '#/components/schemas/codersdk.ProvisionerJobMetadata'
        organization_id:
          type: string
          format: uuid
        queue_position:
          type: integer
        queue_size:
          type: integer
        started_at:
          type: string
          format: date-time
        status:
          enum:
          - pending
          - running
          - succeeded
          - canceling
          - canceled
          - failed
          allOf:
          - $ref: '#/components/schemas/codersdk.ProvisionerJobStatus'
        tags:
          type: object
          additionalProperties:
            type: string
        type:
          $ref: '#/components/schemas/codersdk.ProvisionerJobType'
        worker_id:
          type: string
          format: uuid
        worker_name:
          type: string
    codersdk.JobErrorCode:
      type: string
      enum:
      - REQUIRED_TEMPLATE_VARIABLES
      - INSUFFICIENT_QUOTA
    codersdk.WorkspaceAgentScript:
      type: object
      properties:
        cron:
          type: string
        display_name:
          type: string
        exit_code:
          type: integer
        id:
          type: string
          format: uuid
        log_path:
          type: string
        log_source_id:
          type: string
          format: uuid
        run_on_start:
          type: boolean
        run_on_stop:
          type: boolean
        script:
          type: string
        start_blocks_login:
          type: boolean
        status:
          $ref: '#/components/schemas/codersdk.WorkspaceAgentScriptStatus'
        timeout:
          type: integer
    codersdk.WorkspaceResourceMetadata:
      type: object
      properties:
        key:
          type: string
        sensitive:
          type: boolean
        value:
          type: string
    codersdk.ProvisionerJobInput:
      type: object
      properties:
        error:
          type: string
        template_version_id:
          type: string
          format: uuid
        workspace_build_id:
          type: string
          format: uuid
    codersdk.WorkspaceAgentStatus:
      type: string
      enum:
      - connecting
      - connected
      - disconnected
      - timeout
    codersdk.WorkspaceAppSharingLevel:
      type: string
      enum:
      - owner
      - authenticated
      - organization
      - public
    codersdk.TaskLogEntry:
      type: object
      properties:
        content:
          type: string
        id:
          type: integer
        time:
          type: string
          format: date-time
        type:
          $ref: '#/components/schemas/codersdk.TaskLogType'
    codersdk.WorkspaceAppOpenIn:
      type: string
      enum:
      - slim-window
      - tab
    codersdk.ProvisionerJobMetadata:
      type: object
      properties:
        template_display_name:
          type: string
        template_icon:
          type: string
        template_id:
          type: string
          format: uuid
        template_name:
          type: string
        template_version_name:
          type: string
        workspace_build_transition:
          $ref: '#/components/schemas/codersdk.WorkspaceTransition'
        workspace_id:
          type: string
          format: uuid
        workspace_name:
          type: string
    codersdk.WorkspaceAgentLogSource:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        display_name:
          type: string
        icon:
          type: string
        id:
          type: string
          format: uuid
        workspace_agent_id:
          type: string
          format: uuid
    codersdk.MatchedProvisioners:
      type: object
      properties:
        available:
          type: integer
          description: 'Available is the number of provisioner daemons that are available to

            take jobs. This may be less than the count if some provisioners are

            busy or have been stopped.'
        count:
          type: integer
          description: 'Count is the number of provisioner daemons that matched the given

            tags. If the count is 0, it means no provisioner daemons matched the

            requested tags.'
        most_recently_seen:
          type: string
          format: date-time
          description: 'MostRecentlySeen is the most recently seen time of the set of matched

            provisioners. If no provisioners matched, this field will be null.'
    codersdk.TaskLogType:
      type: string
      enum:
      - input
      - output
    codersdk.Healthcheck:
      type: object
      properties:
        interval:
          type: integer
          description: Interval specifies the seconds between each health check.
        threshold:
          type: integer
          description: Threshold specifies the number of consecutive failed health checks before returning "unhealthy".
        url:
          type: string
          description: URL specifies the endpoint to check for the app health.
    codersdk.TasksListResponse:
      type: object
      properties:
        count:
          type: integer
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/codersdk.Task'
    codersdk.TaskStateEntry:
      type: object
      properties:
        message:
          type: string
        state:
          $ref: '#/components/schemas/codersdk.TaskState'
        timestamp:
          type: string
          format: date-time
        uri:
          type: string
    codersdk.Task:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        current_state:
          $ref: '#/components/schemas/codersdk.TaskStateEntry'
        display_name:
          type: string
        id:
          type: string
          format: uuid
        initial_prompt:
          type: string
        name:
          type: string
        organization_id:
          type: string
          format: uuid
        owner_avatar_url:
          type: string
        owner_id:
          type: string
          format: uuid
        owner_name:
          type: string
        status:
          enum:
          - pending
          - initializing
          - active
          - paused
          - unknown
          - error
          allOf:
          - $ref: '#/components/schemas/codersdk.TaskStatus'
        template_display_name:
          type: string
        template_icon:
          type: string
        template_id:
          type: string
          format: uuid
        template_name:
          type: string
        template_version_id:
          type: string
          format: uuid
        updated_at:
          type: string
          format: date-time
        workspace_agent_health:
          $ref: '#/components/schemas/codersdk.WorkspaceAgentHealth'
        workspace_agent_id:
          format: uuid
          allOf:
          - $ref: '#/components/schemas/uuid.NullUUID'
        workspace_agent_lifecycle:
          $ref: '#/components/schemas/codersdk.WorkspaceAgentLifecycle'
        workspace_app_id:
          format: uuid
          allOf:
          - $ref: '#/components/schemas/uuid.NullUUID'
        workspace_build_number:
          type: integer
        workspace_id:
          format: uuid
          allOf:
          - $ref: '#/components/schemas/uuid.NullUUID'
        workspace_name:
          type: string
        workspace_status:
          enum:
          - pending
          - starting
          - running
          - stopping
          - stopped
          - failed
          - canceling
          - canceled
          - deleting
          - deleted
          allOf:
          - $ref: '#/components/schemas/codersdk.WorkspaceStatus'
    codersdk.WorkspaceTransition:
      type: string
      enum:
      - start
      - stop
      - delete
    codersdk.TaskStatus:
      type: string
      enum:
      - pending
      - initializing
      - active
      - paused
      - unknown
      - error
    codersdk.CreateTaskRequest:
      type: object
      properties:
        display_name:
          type: string
        input:
          type: string
        name:
          type: string
        template_version_id:
          type: string
          format: uuid
        template_version_preset_id:
          type: string
          format: uuid
  securitySchemes:
    CoderSessionToken:
      type: apiKey
      in: header
      name: Coder-Session-Token
externalDocs: {}