openapi: 3.0.3
info:
  title: Robocorp Control Room API
  description: >-
    The Robocorp Control Room API provides programmatic access to the
    orchestration platform for RPA automations. It supports workspace
    management, worker lifecycle, worker group organization, process definition
    and execution, process run monitoring, step run output retrieval, work item
    management, asset storage, vault secrets, webhook configuration, and task
    package deployment. Authentication uses API keys with the RC-WSKEY prefix
    passed in the Authorization header.
  version: v1
  contact:
    name: Robocorp Support
    url: https://robocorp.com/docs
  termsOfService: https://robocorp.com/terms-of-service
  license:
    name: Proprietary
servers:
  - url: https://cloud.robocorp.com/api/v1
    description: Robocorp Control Room API (non-SSO)
  - url: https://your-sso-subdomain.robocorp.com/api/v1
    description: Robocorp Control Room API (SSO)

tags:
  - name: Workspace
    description: Workspace information
  - name: Workers
    description: Worker agent management
  - name: Worker Groups
    description: Worker group organization
  - name: Processes
    description: Process definition and management
  - name: Process Runs
    description: Process execution and monitoring
  - name: Step Runs
    description: Individual step execution details
  - name: Work Items
    description: Work item queue management
  - name: Task Packages
    description: Task package deployment
  - name: Assets
    description: Asset storage management
  - name: Vault
    description: Secret management
  - name: Webhooks
    description: Webhook configuration
  - name: Assistants
    description: AI assistant management

paths:
  /workspaces/{workspace_id}:
    get:
      operationId: getWorkspace
      summary: Get Workspace
      description: Retrieve workspace details by workspace ID.
      tags:
        - Workspace
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: Workspace details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/workers:
    get:
      operationId: listWorkers
      summary: List Workers
      description: List all workers in a workspace.
      tags:
        - Workers
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of workers to return
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor
      responses:
        '200':
          description: List of workers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerList'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/workers/link-tokens:
    post:
      operationId: createLinkToken
      summary: Create Worker Link Token
      description: Generate a link token to connect a new worker to the workspace.
      tags:
        - Workers
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLinkTokenRequest'
      responses:
        '200':
          description: Link token created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkToken'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/workers/{worker_id}:
    get:
      operationId: getWorker
      summary: Get Worker
      description: Retrieve a specific worker by ID.
      tags:
        - Workers
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/WorkerId'
      responses:
        '200':
          description: Worker details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Worker'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    post:
      operationId: updateWorker
      summary: Update Worker
      description: Modify worker details such as name and group assignment.
      tags:
        - Workers
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/WorkerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkerRequest'
      responses:
        '200':
          description: Worker updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Worker'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteWorker
      summary: Delete Worker
      description: Remove a worker from the workspace.
      tags:
        - Workers
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/WorkerId'
      responses:
        '204':
          description: Worker deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/worker-groups:
    get:
      operationId: listWorkerGroups
      summary: List Worker Groups
      description: List all worker groups in a workspace.
      tags:
        - Worker Groups
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: List of worker groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerGroupList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createWorkerGroup
      summary: Create Worker Group
      description: Create a new worker group for organizing workers.
      tags:
        - Worker Groups
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkerGroupRequest'
      responses:
        '201':
          description: Worker group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/worker-groups/{worker_group_id}:
    get:
      operationId: getWorkerGroup
      summary: Get Worker Group
      description: Retrieve a specific worker group by ID.
      tags:
        - Worker Groups
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/WorkerGroupId'
      responses:
        '200':
          description: Worker group details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    post:
      operationId: updateWorkerGroup
      summary: Update Worker Group
      description: Modify worker group details.
      tags:
        - Worker Groups
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/WorkerGroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkerGroupRequest'
      responses:
        '200':
          description: Worker group updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerGroup'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteWorkerGroup
      summary: Delete Worker Group
      description: Delete a worker group from the workspace.
      tags:
        - Worker Groups
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/WorkerGroupId'
      responses:
        '204':
          description: Worker group deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/processes:
    get:
      operationId: listProcesses
      summary: List Processes
      description: List all processes defined in a workspace.
      tags:
        - Processes
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: limit
          in: query
          schema:
            type: integer
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of processes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createProcess
      summary: Create Process
      description: Create a new process with steps, schedules, triggers, and notifications.
      tags:
        - Processes
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProcessRequest'
      responses:
        '201':
          description: Process created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/processes/{process_id}:
    get:
      operationId: getProcess
      summary: Get Process
      description: Retrieve a specific process by ID.
      tags:
        - Processes
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ProcessId'
      responses:
        '200':
          description: Process details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/processes/{process_id}/runs:
    get:
      operationId: listProcessRuns
      summary: List Process Runs
      description: List all runs for a specific process.
      tags:
        - Process Runs
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ProcessId'
        - name: limit
          in: query
          schema:
            type: integer
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: List of process runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessRunList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: startProcessRun
      summary: Start Process Run
      description: Start a new execution run for a process.
      tags:
        - Process Runs
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ProcessId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartProcessRunRequest'
      responses:
        '201':
          description: Process run started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessRun'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/processes/{process_id}/runs/{run_id}:
    get:
      operationId: getProcessRun
      summary: Get Process Run
      description: Retrieve details for a specific process run.
      tags:
        - Process Runs
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ProcessId'
        - $ref: '#/components/parameters/RunId'
      responses:
        '200':
          description: Process run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessRun'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteProcessRun
      summary: Delete Process Run
      description: Delete a process run record.
      tags:
        - Process Runs
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ProcessId'
        - $ref: '#/components/parameters/RunId'
      responses:
        '204':
          description: Process run deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/processes/{process_id}/runs/{run_id}/stop:
    post:
      operationId: stopProcessRun
      summary: Stop Process Run
      description: Stop an active process run execution.
      tags:
        - Process Runs
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ProcessId'
        - $ref: '#/components/parameters/RunId'
      responses:
        '200':
          description: Process run stopped
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/processes/{process_id}/runs/{run_id}/step-runs:
    get:
      operationId: listStepRuns
      summary: List Step Runs
      description: List all step runs within a process run.
      tags:
        - Step Runs
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ProcessId'
        - $ref: '#/components/parameters/RunId'
      responses:
        '200':
          description: List of step runs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepRunList'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/processes/{process_id}/runs/{run_id}/step-runs/{step_run_id}:
    get:
      operationId: getStepRun
      summary: Get Step Run
      description: Retrieve details for a specific step run.
      tags:
        - Step Runs
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ProcessId'
        - $ref: '#/components/parameters/RunId'
        - name: step_run_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Step run details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepRun'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/work-items:
    get:
      operationId: listWorkItems
      summary: List Work Items
      description: List all work items in a workspace.
      tags:
        - Work Items
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: process_id
          in: query
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
            enum:
              - PENDING
              - INPROGRESS
              - COMPLETED
              - FAILED
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: List of work items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItemList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createWorkItem
      summary: Create Work Item
      description: Create a new work item in the queue.
      tags:
        - Work Items
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkItemRequest'
      responses:
        '201':
          description: Work item created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItem'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/work-items/{work_item_id}:
    get:
      operationId: getWorkItem
      summary: Get Work Item
      description: Retrieve a specific work item by ID.
      tags:
        - Work Items
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/WorkItemId'
      responses:
        '200':
          description: Work item details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/assets:
    get:
      operationId: listAssets
      summary: List Assets
      description: List all assets in a workspace.
      tags:
        - Assets
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: List of assets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createAsset
      summary: Create Asset
      description: Create a new asset in storage.
      tags:
        - Assets
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssetRequest'
      responses:
        '201':
          description: Asset created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/assets/{asset_id}:
    get:
      operationId: getAsset
      summary: Get Asset
      description: Retrieve a specific asset by ID.
      tags:
        - Assets
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/AssetId'
      responses:
        '200':
          description: Asset details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteAsset
      summary: Delete Asset
      description: Remove an asset from storage.
      tags:
        - Assets
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/AssetId'
      responses:
        '204':
          description: Asset deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/vault/secrets:
    get:
      operationId: listSecrets
      summary: List Secrets
      description: List all secrets in the workspace vault.
      tags:
        - Vault
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: List of secrets (names only, not values)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createSecret
      summary: Create Secret
      description: Create a new secret in the workspace vault.
      tags:
        - Vault
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '201':
          description: Secret created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/vault/secrets/{secret_id}:
    post:
      operationId: updateSecret
      summary: Update Secret
      description: Update an existing secret value in the vault.
      tags:
        - Vault
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: secret_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSecretRequest'
      responses:
        '200':
          description: Secret updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Secret'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteSecret
      summary: Delete Secret
      description: Remove a secret from the vault.
      tags:
        - Vault
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: secret_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Secret deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/webhooks:
    get:
      operationId: listWebhooks
      summary: List Webhooks
      description: List all webhooks configured in a workspace.
      tags:
        - Webhooks
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createWebhook
      summary: Create Process Webhook
      description: Create a new webhook for process event notifications.
      tags:
        - Webhooks
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/webhooks/{webhook_id}:
    get:
      operationId: getWebhook
      summary: Get Webhook
      description: Retrieve a specific webhook by ID.
      tags:
        - Webhooks
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: webhook_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Webhook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteWebhook
      summary: Delete Webhook
      description: Remove a webhook configuration.
      tags:
        - Webhooks
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: webhook_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Webhook deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/task-packages:
    get:
      operationId: listTaskPackages
      summary: List Task Packages
      description: List all task packages in a workspace.
      tags:
        - Task Packages
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: List of task packages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskPackageList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createTaskPackage
      summary: Create Task Package
      description: >-
        Create a new task package from a zip file, GitHub, or GitLab source.
      tags:
        - Task Packages
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskPackageRequest'
      responses:
        '201':
          description: Task package created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskPackage'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/task-packages/{package_id}:
    get:
      operationId: getTaskPackage
      summary: Get Task Package
      description: Retrieve a specific task package by ID.
      tags:
        - Task Packages
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: package_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Task package details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskPackage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    post:
      operationId: updateTaskPackage
      summary: Update Task Package
      description: Update a task package source configuration.
      tags:
        - Task Packages
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: package_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskPackageRequest'
      responses:
        '200':
          description: Task package updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskPackage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      operationId: deleteTaskPackage
      summary: Delete Task Package
      description: Remove a task package from the workspace.
      tags:
        - Task Packages
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: package_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Task package deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /workspaces/{workspace_id}/assistants:
    get:
      operationId: listAssistants
      summary: List Assistants
      description: List all AI assistants in a workspace.
      tags:
        - Assistants
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      responses:
        '200':
          description: List of assistants
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createAssistant
      summary: Create Assistant
      description: Create a new AI assistant.
      tags:
        - Assistants
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssistantRequest'
      responses:
        '201':
          description: Assistant created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /workspaces/{workspace_id}/assistants/{assistant_id}:
    get:
      operationId: getAssistant
      summary: Get Assistant
      description: Retrieve a specific AI assistant by ID.
      tags:
        - Assistants
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - name: assistant_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Assistant details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key with RC-WSKEY prefix (e.g., "RC-WSKEY your-api-key")

  parameters:
    WorkspaceId:
      name: workspace_id
      in: path
      required: true
      schema:
        type: string
      description: The workspace identifier
    WorkerId:
      name: worker_id
      in: path
      required: true
      schema:
        type: string
      description: The worker identifier
    WorkerGroupId:
      name: worker_group_id
      in: path
      required: true
      schema:
        type: string
      description: The worker group identifier
    ProcessId:
      name: process_id
      in: path
      required: true
      schema:
        type: string
      description: The process identifier
    RunId:
      name: run_id
      in: path
      required: true
      schema:
        type: string
      description: The process run identifier
    WorkItemId:
      name: work_item_id
      in: path
      required: true
      schema:
        type: string
      description: The work item identifier
    AssetId:
      name: asset_id
      in: path
      required: true
      schema:
        type: string
      description: The asset identifier

  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer

    PaginatedResponse:
      type: object
      properties:
        data:
          type: array
          items: {}
        next:
          type: string
          description: Cursor for next page
        has_more:
          type: boolean

    Workspace:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time

    Worker:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
            - ONLINE
            - OFFLINE
            - BUSY
        worker_group_id:
          type: string
        last_seen:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time

    WorkerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Worker'
        has_more:
          type: boolean
        next:
          type: string

    CreateLinkTokenRequest:
      type: object
      properties:
        worker_group_id:
          type: string
        expires_in:
          type: integer
          description: Token expiry in seconds

    LinkToken:
      type: object
      properties:
        token:
          type: string
        expires_at:
          type: string
          format: date-time

    UpdateWorkerRequest:
      type: object
      properties:
        name:
          type: string
        worker_group_id:
          type: string

    WorkerGroup:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        worker_count:
          type: integer
        created_at:
          type: string
          format: date-time

    WorkerGroupList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WorkerGroup'
        has_more:
          type: boolean

    CreateWorkerGroupRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string

    Process:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        state:
          type: string
        steps:
          type: array
          items:
            type: object
        schedules:
          type: array
          items:
            type: object
        created_at:
          type: string
          format: date-time

    ProcessList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Process'
        has_more:
          type: boolean

    CreateProcessRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        steps:
          type: array
          items:
            type: object
        schedules:
          type: array
          items:
            type: object
        triggers:
          type: array
          items:
            type: object
        notifications:
          type: object

    ProcessRun:
      type: object
      properties:
        id:
          type: string
        process_id:
          type: string
        state:
          type: string
          enum:
            - PENDING
            - RUNNING
            - COMPLETED
            - FAILED
            - STOPPED
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time

    ProcessRunList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProcessRun'
        has_more:
          type: boolean

    StartProcessRunRequest:
      type: object
      properties:
        variables:
          type: object
          additionalProperties: true
        work_item_ids:
          type: array
          items:
            type: string

    StepRun:
      type: object
      properties:
        id:
          type: string
        process_run_id:
          type: string
        step_name:
          type: string
        state:
          type: string
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        artifacts:
          type: array
          items:
            type: object

    StepRunList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/StepRun'

    WorkItem:
      type: object
      properties:
        id:
          type: string
        process_id:
          type: string
        state:
          type: string
          enum:
            - PENDING
            - INPROGRESS
            - COMPLETED
            - FAILED
        payload:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time

    WorkItemList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WorkItem'
        has_more:
          type: boolean

    CreateWorkItemRequest:
      type: object
      properties:
        process_id:
          type: string
          description: Process to assign the work item to
        payload:
          type: object
          additionalProperties: true

    Asset:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        content_type:
          type: string
        size:
          type: integer
        created_at:
          type: string
          format: date-time

    AssetList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Asset'

    CreateAssetRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        content_type:
          type: string

    Secret:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time

    SecretList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Secret'

    CreateSecretRequest:
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
        value:
          type: string
          description: The secret value (write-only)

    Webhook:
      type: object
      properties:
        id:
          type: string
        process_id:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time

    WebhookList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'

    CreateWebhookRequest:
      type: object
      required:
        - process_id
        - url
      properties:
        process_id:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string

    TaskPackage:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        source_type:
          type: string
          enum:
            - zip
            - github
            - gitlab
        created_at:
          type: string
          format: date-time

    TaskPackageList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TaskPackage'

    CreateTaskPackageRequest:
      type: object
      required:
        - name
        - source_type
      properties:
        name:
          type: string
        source_type:
          type: string
          enum:
            - zip
            - github
            - gitlab
        source_url:
          type: string
          format: uri
        branch:
          type: string

    Assistant:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        created_at:
          type: string
          format: date-time

    AssistantList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Assistant'

    CreateAssistantRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string