Posit Tasks API

openapi: 3.2.0
info:
  contact:
    email: support@posit.co
    name: Posit Connect Support
    url: https://support.posit.co/hc/en-us
  description: '## Overview


    The Posit Connect Server API can be used to perform certain

    user actions remotely.'
  license:
    name: Commercial. Copyright 2015-2026 Posit Software, PBC. All Rights Reserved.
    url: https://posit.co/about/eula/
  termsOfService: https://posit.co/about/eula/
  title: Posit Connect API Reference Tasks API
  version: 1.0.1
servers:
- url: /__api__
security:
- apiKey: []
tags:
- name: Tasks
paths:
  /v1/tasks/{id}:
    get:
      description: 'Returns the current state of a task and any output lines past the

        requested initial position (`first`).


        When `wait` is non-zero, will wait up to that number of seconds for

        the task to complete before responding. The current state of the task

        is returned once the task completes or `wait` seconds elapse.


        Incrementally receive task output by using the `last` response field

        value as the `first` value in a subsequent query.


        Use `wait` and `first` together to incrementally fetch generated

        output.


        Here is a URL that allows up to 5 seconds before returning all

        available output:


        ```

        /v1/tasks/CmsfmnfDDyRUrsAc?wait=5&first=0

        ```


        Let''s assume that request has a JSON response with the `last` field

        having a value of `23`. Here is a URL that requests output past that

        point, again allowing up to 5 seconds:


        ```

        /v1/tasks/CmsfmnfDDyRUrsAc?wait=5&first=23

        ```


        Continue with this pattern until the `finished`

        field in the JSON response is `true`.


        **Note:** In high-availability clustered deployments of Connect, the task

        request must be serviced by the node that is executing the task. This

        is done by ensuring that the cookies returned from the deployment operation are

        included in subsequent requests, so that the load balancer can appropriately

        direct the request. In a single-node configuration, the cookie can be omitted.'
      operationId: getTask
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: query
        name: first
        schema:
          default: 0
          format: int32
          type: integer
      - in: query
        name: wait
        schema:
          default: 0
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
          description: Successful response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: The requested operation is invalid.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: The requested operation requires authentication.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: You do not have permission to perform this operation.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: The requested object does not exist.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: A server error occurred.
      summary: Get task details
      tags:
      - Tasks
components:
  schemas:
    APIError:
      additionalProperties: false
      description: The error object returned by the API on failure.
      properties:
        code:
          description: The specific code for the type of error returned. See the [API error codes reference](#api-error-codes) for the full set of values.
          type: integer
        error:
          description: A description of the problem that was encountered.
          type: string
        payload:
          description: Additional error details, if any. The structure varies by error type.
          type:
          - object
          - 'null'
      required:
      - code
      - error
      type: object
    Task:
      additionalProperties: false
      description: 'The task tracks the output and status of some operation being performed

        by Posit Connect. It is most commonly used to contain details about

        the progress of a deployment operation.'
      properties:
        id:
          description: The identifier for this task.
          example: jXhOhdm5OOSkGhJw
          type: string
        output:
          description: 'An array containing lines of output produced by the task. The

            initial line of output is dictated by the `first` input parameter.

            The offset of the last output line is indicated by the `last`

            response field.'
          items:
            type: string
          type: array
        result:
          description: 'A value representing the result of the operation, if any.

            For deployment tasks, this value is `null`.'
          example: null
          type:
          - object
          - 'null'
        finished:
          description: Indicates that a task has completed.
          example: true
          type: boolean
        code:
          description: 'Numeric indication as to the cause of an error. Non-zero when an

            error has occurred.'
          example: 1
          format: int32
          type: integer
        error:
          description: 'Description of the error. An empty string when no error has

            occurred.'
          example: 'Unable to render: Rendering exited abnormally: exit status 1'
          type: string
        last:
          description: 'The total number of output lines produced so far. Use as the value

            to `first` in the next request to only fetch output lines beyond

            what you have already received.'
          example: 2
          format: int32
          type: integer
      type: object
  securitySchemes:
    apiKey:
      description: 'Prefix your API key with `Key `, e.g. `Key ABC123`.

        '
      in: header
      name: Authorization
      type: apiKey