openapi: 3.2.0
info:
  description: The One API. Universal API integration platform for AI agents and applications.
  license:
    name: ''
  title: One AI Runners API
  version: 5.35.0
tags:
- description: Manage AI agent runner pods
  name: AI Runners
paths:
  /v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}:
    delete:
      operationId: destroy_project_ai_runner
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Project ID
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: AI runner destroyed
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Destroy project ai runner
      x-summary-source: derived
    get:
      operationId: get_project_ai_runner_status
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Project ID
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiRunnerView'
          description: AI runner status
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Get project ai runner status
      x-summary-source: derived
    post:
      operationId: ensure_project_ai_runner
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Project ID
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiRunnerView'
          description: AI runner ensured
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Ensure project ai runner
      x-summary-source: derived
  /v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}/dashboard-password:
    get:
      operationId: reveal_project_ai_runner_dashboard_password
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Project ID
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardPasswordView'
          description: Current dashboard password, decrypted for display (no restart)
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Reveal project ai runner dashboard password
      x-summary-source: derived
  /v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}/dashboard-password/regenerate:
    post:
      operationId: regenerate_project_ai_runner_dashboard_password
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Project ID
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardPasswordView'
          description: Dashboard password rotated in the pod
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Regenerate project ai runner dashboard password
      x-summary-source: derived
  /v1/ai-runners/organizations/{org_id}/projects/{project_id}/{agent_id}/proxy/{path}:
    post:
      operationId: proxy_project_ai_runner
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Project ID
        in: path
        name: project_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Proxy path
        in: path
        name: path
        required: true
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
        description: Payload forwarded to the agent pod
        required: true
      responses:
        '200':
          description: Proxied response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Proxy project ai runner
      x-summary-source: derived
  /v1/ai-runners/organizations/{org_id}/{agent_id}:
    delete:
      operationId: destroy_org_ai_runner
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: AI runner destroyed
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Destroy org ai runner
      x-summary-source: derived
    get:
      operationId: get_org_ai_runner_status
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiRunnerView'
          description: AI runner status
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Get org ai runner status
      x-summary-source: derived
    post:
      operationId: ensure_org_ai_runner
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiRunnerView'
          description: AI runner ensured
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Ensure org ai runner
      x-summary-source: derived
  /v1/ai-runners/organizations/{org_id}/{agent_id}/dashboard-password:
    get:
      operationId: reveal_org_ai_runner_dashboard_password
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardPasswordView'
          description: Current dashboard password, decrypted for display (no restart)
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Reveal org ai runner dashboard password
      x-summary-source: derived
  /v1/ai-runners/organizations/{org_id}/{agent_id}/dashboard-password/regenerate:
    post:
      operationId: regenerate_org_ai_runner_dashboard_password
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardPasswordView'
          description: Dashboard password rotated in the pod
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Regenerate org ai runner dashboard password
      x-summary-source: derived
  /v1/ai-runners/organizations/{org_id}/{agent_id}/proxy/{path}:
    post:
      operationId: proxy_org_ai_runner
      parameters:
      - description: Organization ID
        in: path
        name: org_id
        required: true
        schema:
          format: uuid
          type: string
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Proxy path
        in: path
        name: path
        required: true
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
        description: Payload forwarded to the agent pod
        required: true
      responses:
        '200':
          description: Proxied response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Proxy org ai runner
      x-summary-source: derived
  /v1/ai-runners/{agent_id}:
    delete:
      operationId: destroy_ai_runner
      parameters:
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: AI runner destroyed
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Destroy ai runner
      x-summary-source: derived
    get:
      operationId: get_ai_runner_status
      parameters:
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiRunnerView'
          description: AI runner status
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Get ai runner status
      x-summary-source: derived
    post:
      operationId: ensure_ai_runner
      parameters:
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiRunnerView'
          description: AI runner ensured
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Ensure ai runner
      x-summary-source: derived
  /v1/ai-runners/{agent_id}/dashboard-password:
    get:
      operationId: reveal_ai_runner_dashboard_password
      parameters:
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardPasswordView'
          description: Current dashboard password, decrypted for display (no restart)
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Reveal ai runner dashboard password
      x-summary-source: derived
  /v1/ai-runners/{agent_id}/dashboard-password/regenerate:
    post:
      operationId: regenerate_ai_runner_dashboard_password
      parameters:
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardPasswordView'
          description: Dashboard password rotated in the pod
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Regenerate ai runner dashboard password
      x-summary-source: derived
  /v1/ai-runners/{agent_id}/proxy/{path}:
    post:
      operationId: proxy_ai_runner
      parameters:
      - description: AI agent ID
        in: path
        name: agent_id
        required: true
        schema:
          format: uuid
          type: string
      - description: Proxy path
        in: path
        name: path
        required: true
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
        description: Payload forwarded to the agent pod
        required: true
      responses:
        '200':
          description: Proxied response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Quota exceeded — upgrade plan
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Insufficient permissions
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Upstream service unavailable
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Service unavailable
      security:
      - X-Pica-Secret: []
      tags:
      - AI Runners
      summary: Proxy ai runner
      x-summary-source: derived
components:
  schemas:
    AiRunnerView:
      properties:
        agentId:
          format: uuid
          type: string
        dashboardPassword:
          description: 'Always `None` on this status/lifecycle view. The dashboard password is

            never returned alongside pod status — surfacing it here would ride every

            poll. It is returned only by the dedicated reveal / regenerate routes,

            which respond with a [`DashboardPasswordView`].'
          type:
          - string
          - 'null'
        dashboardUsername:
          description: 'Framework (Hermes) dashboard basic-auth username — the fixed `one`

            account. Populated (decrypted) only on the owner-authed status route

            for framework pods; `None` for Claude and on the ensure/resume

            construction sites. `skip_serializing_if` keeps the Claude status

            response byte-identical (the key is absent, not `null`).'
          type:
          - string
          - 'null'
        link:
          $ref: '#/components/schemas/AgentPodView'
        pod:
          $ref: '#/components/schemas/PodView'
      required:
      - agentId
      - pod
      - link
      type: object
    PodStatusType:
      enum:
      - pending
      - running
      - succeeded
      - failed
      - terminated
      type: string
    DashboardPasswordView:
      description: 'Response body for the dashboard-password reveal/regenerate routes: the

        pod-owned credential the console displays. Both fields always present

        (framework-only routes).'
      properties:
        dashboardPassword:
          type: string
        dashboardUsername:
          type: string
      required:
      - dashboardUsername
      - dashboardPassword
      type: object
    AgentPodView:
      properties:
        active:
          type: boolean
        agentId:
          format: uuid
          type: string
        createdAt:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        podId:
          format: uuid
          type: string
        tags:
          items:
            type: string
          type: array
        updatedAt:
          format: date-time
          type: string
        version:
          type: string
      required:
      - id
      - agentId
      - podId
      - createdAt
      - updatedAt
      - version
      - tags
      - active
      type: object
    ErrorResponse:
      properties:
        correlationId:
          example: 550e8400-e29b-41d4-a716-446655440000
          type: string
        key:
          example: http_error
          type: string
        message:
          example: Authentication required
          type: string
        status:
          example: 401
          format: int32
          minimum: 0
          type: integer
        type:
          example: http_error
          type: string
      required:
      - correlationId
      - key
      - message
      - type
      - status
      type: object
    AiRuntimeType:
      enum:
      - claude
      - hermes
      - openclaw
      - clockwork
      type: string
    PodStopReasonType:
      description: 'Why a pod was stopped. The same operation reached two ways, and the

        difference matters after the fact: a user pausing their runner and billing

        culling it for a lapsed seat leave an identical `terminated` row, and mean

        completely different things to whoever is asking why an agent went quiet -

        one is "I did that", the other is "resume will not help until you pay".


        Null on a pod that has not been stopped, and on rows written before this was

        recorded.


        Deliberately has no `Default`. "Why did this stop" has no sensible fallback:

        the column is nullable precisely because *unknown* is the honest answer for

        a pod stopped before it existed, and any default would answer that question

        with a guess. `user_requested` in particular is the one value that makes a

        console offer a restart.'
      enum:
      - user_requested
      - seat_lapsed
      type: string
    PodView:
      properties:
        active:
          type: boolean
        args:
          items:
            type: string
          type:
          - array
          - 'null'
        command:
          items:
            type: string
          type:
          - array
          - 'null'
        createdAt:
          format: date-time
          type: string
        description:
          type:
          - string
          - 'null'
        envVars: {}
        finishedAt:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        idleTimeoutMs:
          format: int64
          type: integer
        image:
          type: string
        k8sNamespace:
          type: string
        k8sPodIp:
          type:
          - string
          - 'null'
        k8sPodName:
          type: string
        k8sPort:
          format: int32
          type: integer
        k8sSubdomain:
          type: string
        labels: {}
        lastActivityAt:
          format: date-time
          type: string
        maxLifetimeMs:
          format: int64
          type: integer
        name:
          type: string
        organizationId:
          format: uuid
          type:
          - string
          - 'null'
        projectId:
          format: uuid
          type:
          - string
          - 'null'
        resources: {}
        runtime:
          $ref: '#/components/schemas/AiRuntimeType'
        secretRefs:
          items:
            format: uuid
            type: string
          type: array
        startedAt:
          format: date-time
          type: string
        status:
          $ref: '#/components/schemas/PodStatusType'
        stopReason:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/PodStopReasonType'
            description: 'What stopped this pod, when it is stopped. A cause, not a prediction:

              see `AiAgentView::runner_stop_reason`, which surfaces the same value on

              an agent read.'
        tags:
          items:
            type: string
          type: array
        updatedAt:
          format: date-time
          type: string
        userId:
          format: uuid
          type: string
        version:
          type: string
        volumeMountPath:
          type: string
        volumeSize:
          type: string
      required:
      - id
      - userId
      - name
      - image
      - status
      - k8sNamespace
      - k8sPodName
      - k8sSubdomain
      - k8sPort
      - runtime
      - resources
      - envVars
      - secretRefs
      - volumeMountPath
      - volumeSize
      - labels
      - lastActivityAt
      - idleTimeoutMs
      - maxLifetimeMs
      - startedAt
      - finishedAt
      - createdAt
      - updatedAt
      - version
      - tags
      - active
      type: object
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://api.withone.ai/oauth/authorize
          scopes:
            org:ai_skills:read: Read organization AI skills
            org:ai_skills:write: Create, update, and delete organization AI skills
            org:authkit:read: Read organization AuthKit resources
            org:authkit:write: Create, update, and delete organization AuthKit resources
            org:connections:read: Read organization connections
            org:connections:write: Create, update, and delete organization connections
            org:projects:read: Read organization projects
            org:projects:write: Create, update, and delete organization projects
            org:secrets:read: Read organization secrets
            org:secrets:write: Create, update, and delete organization secrets
            org:workflows:executions:read: Read organization workflow executions
            org:workflows:executions:write: Create, update, and delete organization workflow executions
            org:workflows:read: Read organization workflows
            org:workflows:write: Create, update, and delete organization workflows
            project:ai_skills:read: Read project AI skills
            project:ai_skills:write: Create, update, and delete project AI skills
            project:authkit:read: Read project AuthKit resources
            project:authkit:write: Create, update, and delete project AuthKit resources
            project:connections:read: Read project connections
            project:connections:write: Create, update, and delete project connections
            project:secrets:read: Read project secrets
            project:secrets:write: Create, update, and delete project secrets
            project:workflows:executions:read: Read project workflow executions
            project:workflows:executions:write: Create, update, and delete project workflow executions
            project:workflows:read: Read project workflows
            project:workflows:write: Create, update, and delete project workflows
            user:ai_skills:read: Read your personal AI skills
            user:ai_skills:write: Create, update, and delete your personal AI skills
            user:authkit:read: Read your personal AuthKit resources
            user:authkit:write: Create, update, and delete your personal AuthKit resources
            user:connections:read: Read your personal connections
            user:connections:write: Create, update, and delete your personal connections
            user:secrets:read: Read your personal secrets
            user:secrets:write: Create, update, and delete your personal secrets
            user:workflows:executions:read: Read your personal workflow executions
            user:workflows:executions:write: Create, update, and delete your personal workflow executions
            user:workflows:read: Read your personal workflows
            user:workflows:write: Create, update, and delete your personal workflows
          tokenUrl: https://api.withone.ai/oauth/token
      type: oauth2
    Session:
      in: cookie
      name: withone
      type: apiKey
    X-One-Connection-Key:
      in: header
      name: X-One-Connection-Key
      type: apiKey
    X-One-Secret:
      in: header
      name: X-One-Secret
      type: apiKey
    X-Pica-Connection-Key:
      in: header
      name: X-One-Connection-Key
      type: apiKey
    X-Pica-Secret:
      in: header
      name: X-One-Secret
      type: apiKey