Understudy Labs Downloads API

openapi: 3.1.0
info:
  title: Understudy Desktop Agent Capabilities Downloads API
  version: 2.2.0
  description: Authenticated loopback API for agents operating a running Understudy Desktop app. The desktop capability file supplies the ephemeral base URL and bearer token. Prompts, images, traces, and model outputs remain local unless a caller explicitly selects a remote route.
servers:
- url: http://127.0.0.1:{port}
  description: Discovered from the private desktop capability file
  variables:
    port:
      default: '17790'
security:
- desktopBearer: []
tags:
- name: Downloads
paths:
  /v1/downloads:
    get:
      operationId: desktopDownloads
      summary: List active and recent model downloads
      responses:
        '200':
          description: Download registry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadList'
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Downloads
    post:
      operationId: desktopDownloadStart
      summary: Start downloading one certified model snapshot
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DownloadStartRequest'
      responses:
        '200':
          description: Download started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadStartResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
      tags:
      - Downloads
  /v1/downloads/{download_id}:
    get:
      operationId: desktopDownloadStatus
      summary: Inspect one exact model download
      parameters:
      - $ref: '#/components/parameters/DownloadId'
      responses:
        '200':
          description: Download progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadProgress'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Downloads
  /v1/downloads/{download_id}/cancel:
    post:
      operationId: desktopDownloadCancel
      summary: Cancel one exact model download
      parameters:
      - $ref: '#/components/parameters/DownloadId'
      responses:
        '200':
          description: Cancelled download state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadProgress'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      tags:
      - Downloads
components:
  schemas:
    DownloadProgress:
      type: object
      required:
      - id
      - model_id
      - status
      - started_at
      - planned_files
      - files
      - downloaded_bytes
      - resumed_bytes
      - total_bytes
      - dest
      - error
      - resumable
      - logs
      properties:
        id:
          type: string
          minLength: 1
        model_id:
          type: string
          minLength: 1
        status:
          type: string
          enum:
          - running
          - done
          - error
          - cancelled
        started_at:
          type: string
          format: date-time
        planned_files:
          type: integer
          minimum: 0
        files:
          type: object
          additionalProperties:
            type: object
            required:
            - downloaded
            - total
            properties:
              downloaded:
                type: integer
                minimum: 0
              total:
                type:
                - integer
                - 'null'
                minimum: 0
            additionalProperties: false
        downloaded_bytes:
          type: integer
          minimum: 0
        resumed_bytes:
          type: integer
          minimum: 0
        total_bytes:
          type:
          - integer
          - 'null'
          minimum: 0
        dest:
          type:
          - string
          - 'null'
        error:
          type:
          - string
          - 'null'
        resumable:
          type: boolean
        logs:
          type: array
          items:
            type: string
      additionalProperties: false
    DownloadStartResponse:
      type: object
      required:
      - ok
      - download_id
      - model_id
      properties:
        ok:
          const: true
        download_id:
          type: string
          minLength: 1
        model_id:
          type: string
          minLength: 1
      additionalProperties: false
    ErrorResponse:
      type: string
      description: A bounded plain-text error. Clients must not treat it as model output.
    DownloadStartRequest:
      type: object
      required:
      - model_id
      properties:
        model_id:
          type: string
          minLength: 1
      additionalProperties: false
    DownloadList:
      type: object
      required:
      - downloads
      properties:
        downloads:
          type: array
          items:
            $ref: '#/components/schemas/DownloadProgress'
      additionalProperties: false
  parameters:
    DownloadId:
      name: download_id
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 200
  responses:
    Unauthorized:
      description: Missing or invalid desktop bearer token
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested run or trace was not found
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: The run or session identity is already active
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    desktopBearer:
      type: http
      scheme: bearer
      description: Ephemeral token read from the owner-only desktop capability file. Agents should use the Understudy CLI or MCP adapter instead of printing this token.
x-understudy-discovery:
  capability_file: ~/.understudy/desktop-api.json
  capability_schema: understudy.desktop_api.v2
  required_file_mode: '0600'
  recommended_adapter: understudy desktop
x-understudy-extension-surfaces:
  available_via_versioned_rest_mcp_and_cli:
  - runtime status
  - model inventory and certified catalog
  - model download lifecycle
  - residency slot lifecycle
  - local correction-pair export and supervision metrics
  not_yet_versioned_in_v2_rest:
  - conversation inspect, branch, compact, and resume
  - runtime and CLI diagnostics with repair actions
  - general capture export outside desktop supervision
  - resumable desktop-wide event subscription