openapi: 3.1.0
info:
  title: marimohub API
  version: 1.0.0
  description: API for managing Marimo notebooks, projects, and sandboxes
tags:
  - name: Auth
    description: Authentication
  - name: Projects
    description: Project management
  - name: Alerts
    description: Project alert destinations
  - name: Conversations
    description: Private project chat with tool consent
  - name: Notebooks
    description: Notebook CRUD and versioning
  - name: Sessions
    description: Notebook session lifecycle
  - name: Jobs
    description: Scheduled and on-demand headless notebook runs
  - name: Integrations
    description: Project and organization integrations
  - name: Secrets
    description: Project secret management
  - name: Users
    description: User identity resolution
  - name: Audit
    description: Deployment and project audit events
  - name: System
    description: Deployment metadata
security:
  - cookieAuth: []
  - bearerAuth: []
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: mh_session
      description: Session cookie minted by the OIDC login flow; browsers attach it
        automatically.
    bearerAuth:
      type: http
      scheme: bearer
      description: Hub personal access token (`mhub_pat_…`), configured
        service-account token (`mhub_sa_…`), or a trusted external OIDC access
        token when enabled. Bearer credentials cannot manage personal tokens.
  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - BAD_REQUEST
                - PRECONDITION_FAILED
                - NOT_FOUND
                - CONFLICT
                - APP_ASSIGNMENT_EXPIRED
                - PREVIEW_NOT_READY
                - PROPOSAL_RETRY_REQUIRED
                - IMPORT_RESTART_REQUIRED
                - EDIT_SESSION_OWNED
                - EDIT_SESSION_RETIRING
                - EDIT_SESSION_CHANGED
                - TAKEOVER_IN_PROGRESS
                - MOVE_IN_PROGRESS
                - FORBIDDEN
                - VALIDATION_ERROR
                - SYNC_NOT_CONFIGURED
                - NOT_INITIALIZED
                - SERVICE_UNAVAILABLE
                - PYTHON_ENV_SETUP_FAILED
                - RESOURCE_EXHAUSTED
                - SURFACE_NOT_ENABLED
                - SURFACE_UNAVAILABLE
                - SURFACE_FORBIDDEN
                - SURFACE_PRIMARY
                - SURFACE_UNSUPPORTED_PROVIDER
                - SURFACE_OPEN_INVALID
                - UNAUTHORIZED
                - USER_SUSPENDED
                - GONE
                - PAYLOAD_TOO_LARGE
                - NO_HTML_SNAPSHOT
                - NO_RUN_OUTPUT
                - INTERNAL_ERROR
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
                required:
                  - field
                  - message
              description: Field-level validation failures.
            request_id:
              type: string
          required:
            - code
            - message
      required:
        - success
        - error
    Me:
      type: object
      properties:
        groups:
          type: array
          items:
            type: string
        id:
          type: string
        email:
          type: string
        name:
          type:
            - string
            - 'null'
        picture_url:
          type:
            - string
            - 'null'
          format: uri
        logout_url:
          type:
            - string
            - 'null'
        is_super_admin:
          type: boolean
        can_create_projects:
          type: boolean
        app_only:
          type: boolean
      required:
        - groups
        - id
        - email
        - logout_url
        - is_super_admin
        - can_create_projects
    DeploymentInfo:
      type: object
      properties:
        version:
          type: string
      required:
        - version
    Capabilities:
      type: object
      properties:
        support:
          type: object
          properties:
            reports:
              type: boolean
              description: Users can send problem reports to the deployment notifier.
          required:
            - reports
        project_notebook_target:
          type: string
          enum:
            - notebook
            - app
          description: Destination for project notebook links. Users without app
            permission open the notebook page.
        workspace_limits:
          type: object
          properties:
            single_put_max_bytes:
              type: integer
              exclusiveMinimum: 0
            max_file_bytes:
              type: integer
              exclusiveMinimum: 0
            max_total_bytes:
              type: integer
              exclusiveMinimum: 0
            max_files:
              type: integer
              exclusiveMinimum: 0
          required:
            - single_put_max_bytes
            - max_file_bytes
            - max_total_bytes
            - max_files
        project_groups:
          type: object
          properties:
            available:
              type: boolean
          required:
            - available
        federation:
          type: object
          properties:
            available:
              type: boolean
            default_enabled:
              type: boolean
          required:
            - available
            - default_enabled
        integrations:
          type: object
          properties:
            available:
              type: boolean
          required:
            - available
        source_control:
          type: object
          properties:
            working_branch_providers:
              type: array
              items:
                type: string
            preview_providers:
              type: array
              items:
                type: string
              description: Provider ids configured to publish notebook previews through a
                GitHub App.
              example:
                - github
            change_request_providers:
              type: array
              items:
                type: string
              description: Provider ids configured to publish pull requests, merge requests,
                or equivalents from notebook sessions.
              example:
                - github
            sync_providers:
              type: array
              items:
                type: string
              description: Provider ids configured for server-initiated pull sync (drift
                lookup and "Sync now").
              example:
                - github
            pull_source_providers:
              type: array
              items:
                type: string
              description: Provider ids configured to create pull-mode sources with
                server-materialized Git metadata.
              example:
                - github
          required:
            - preview_providers
            - change_request_providers
            - sync_providers
            - pull_source_providers
        project_alerts:
          type: object
          properties:
            available:
              type: boolean
            destination_types:
              type: array
              items:
                type: string
                enum:
                  - slack
                  - webhook
                  - unknown
                description: 'Known values: slack, webhook. Unrecognized values normalize to
                  unknown.'
                example: slack
            selectable_kinds:
              type: array
              items:
                type: string
                enum:
                  - member.invited
                  - member.added
                  - member.group_added
                  - member.role_changed
                  - member.removed
                  - session.takeover
                  - notebook.deleted
                  - project.deleted
                  - project.default_access_changed
                  - app.start_failed
                  - app.unavailable
                  - sync.failed
                  - job.run.failed
                  - job.run.succeeded
                  - unknown
                description: 'Known values: member.invited, member.added, member.group_added,
                  member.role_changed, member.removed, session.takeover,
                  notebook.deleted, project.deleted,
                  project.default_access_changed, app.start_failed,
                  app.unavailable, sync.failed, job.run.failed,
                  job.run.succeeded. Unrecognized values normalize to unknown.'
                example: member.invited
            max_destinations:
              type: integer
              exclusiveMinimum: 0
          required:
            - available
            - destination_types
            - selectable_kinds
            - max_destinations
        jobs:
          type: object
          properties:
            available:
              type: boolean
            max_per_notebook:
              type:
                - integer
                - 'null'
            max_queued_runs_per_job:
              type:
                - integer
                - 'null'
              exclusiveMinimum: 0
            default_timeout_seconds:
              type:
                - integer
                - 'null'
            max_timeout_seconds:
              type:
                - integer
                - 'null'
            run_retention_days:
              type:
                - number
                - 'null'
          required:
            - available
            - max_per_notebook
            - max_queued_runs_per_job
            - default_timeout_seconds
            - max_timeout_seconds
            - run_retention_days
        mcp:
          type: object
          properties:
            available:
              type: boolean
            manual_tokens:
              type: boolean
            url:
              type:
                - string
                - 'null'
          required:
            - available
            - manual_tokens
            - url
        search:
          type: object
          properties:
            available:
              type: boolean
            semantic:
              type: boolean
            kinds:
              type: array
              items:
                type: string
                enum:
                  - notebook
                  - code
                  - output
                  - datasource
                  - namespace
                  - table
                  - column
                  - unknown
                description: 'Known values: notebook, code, output, datasource, namespace,
                  table, column. Unrecognized values normalize to unknown.'
                example: notebook
          required:
            - available
            - semantic
            - kinds
        chat:
          type: object
          properties:
            available:
              type: boolean
          required:
            - available
        data_browser:
          type: object
          properties:
            available:
              type: boolean
            preview:
              type: boolean
            query:
              type: boolean
            ai_query:
              type: boolean
          required:
            - available
            - preview
            - query
            - ai_query
        viewer_mode:
          type: string
          enum:
            - static
            - applications
            - ephemeral-sandbox
        viewer_session_modes:
          type: array
          items:
            type: string
            enum:
              - edit
              - app
        app_pool:
          type: object
          properties:
            heartbeat_interval_seconds:
              type: number
              exclusiveMinimum: 0
          required:
            - heartbeat_interval_seconds
        editor_sandbox_sharing:
          type: string
          enum:
            - shared
            - exclusive
        default_role:
          type:
            - string
            - 'null'
          enum:
            - manager
            - editor
            - viewer
            - app-user
            - null
        limits:
          type: object
          properties:
            max_concurrent_sessions_per_user:
              type:
                - number
                - 'null'
            max_apps_per_project:
              type:
                - number
                - 'null'
            max_request_bytes:
              type: number
            max_versions_per_notebook:
              type: number
            default_page_size:
              type: number
            max_page_size:
              type: number
          required:
            - max_concurrent_sessions_per_user
            - max_apps_per_project
            - max_request_bytes
            - max_versions_per_notebook
            - default_page_size
            - max_page_size
        sandbox_images:
          type: array
          items:
            type: string
        marimo_asset_url:
          type: string
          description: Public HTTPS marimo asset base or version template, when configured.
        sandbox_startup_timeout_seconds:
          type: number
        compute_profiles:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/ComputeResources'
              - type: object
                properties:
                  name:
                    type: string
                required:
                  - name
        compute_profile_override:
          type: string
          enum:
            - none
            - editors
        app_compute_profiles:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/ComputeResources'
              - type: object
                properties:
                  name:
                    type: string
                required:
                  - name
          description: Absent when apps share compute_profiles and inherit the notebook's
            editing selection.
        surfaces:
          type: array
          items:
            oneOf:
              - type: object
                properties:
                  id:
                    type: string
                    enum:
                      - vscode
                  flavor:
                    type: string
                    enum:
                      - code-server
                      - openvscode
                  start:
                    type: string
                    enum:
                      - on-demand
                      - eager
                  embed:
                    type: string
                    enum:
                      - tab
                      - iframe
                required:
                  - id
                  - flavor
                  - start
                  - embed
              - type: object
                properties:
                  id:
                    type: string
                    enum:
                      - opencode
                  start:
                    type: string
                    enum:
                      - on-demand
                      - eager
                  embed:
                    type: string
                    enum:
                      - tab
                      - iframe
                  managed_ai:
                    type: boolean
                required:
                  - id
                  - start
                  - embed
                  - managed_ai
      required:
        - support
        - project_notebook_target
        - workspace_limits
        - project_groups
        - federation
        - integrations
        - source_control
        - project_alerts
        - jobs
        - mcp
        - search
        - chat
        - data_browser
        - viewer_mode
        - viewer_session_modes
        - editor_sandbox_sharing
        - default_role
        - limits
        - sandbox_images
        - sandbox_startup_timeout_seconds
        - compute_profiles
        - compute_profile_override
        - surfaces
    ComputeResources:
      type: object
      properties:
        cpu:
          type: number
        memory_bytes:
          type: number
        gpu:
          type: string
    ProjectPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SnapshotProjectEntry'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    SnapshotProjectEntry:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        owner:
          type: string
        status:
          type: string
          enum:
            - active
            - deleted
        created_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        updated_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        notebook_count:
          type: number
        tags:
          type: array
          items:
            type: string
          example:
            - research/vision
      required:
        - id
        - name
        - description
        - owner
        - status
        - created_at
        - updated_at
        - notebook_count
        - tags
    Project:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        owner:
          type: string
        members:
          type: array
          items:
            $ref: '#/components/schemas/ProjectMember'
        default_role:
          type: string
          enum:
            - inherit
            - none
            - manager
            - editor
            - viewer
            - app-user
        status:
          type: string
          enum:
            - active
            - deleted
        created_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        updated_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        tags:
          type: array
          items:
            type: string
        federation:
          $ref: '#/components/schemas/ProjectFederation'
        federation_effective:
          $ref: '#/components/schemas/ProjectFederationEffective'
        security_labels:
          $ref: '#/components/schemas/SecurityLabels'
        your_role:
          type:
            - string
            - 'null'
          enum:
            - admin
            - manager
            - editor
            - viewer
            - app-user
            - null
      required:
        - id
        - name
        - description
        - owner
        - members
        - default_role
        - status
        - created_at
        - updated_at
        - tags
        - federation_effective
        - your_role
    ProjectMember:
      oneOf:
        - type: object
          properties:
            user_id:
              type: string
            email:
              type: string
              enum: &a1 []
            group:
              type: string
              enum: *a1
            role:
              type: string
              enum:
                - admin
                - manager
                - editor
                - viewer
                - app-user
          required:
            - user_id
            - role
          additionalProperties: false
        - type: object
          properties:
            user_id:
              type: string
              enum: *a1
            email:
              type: string
            group:
              type: string
              enum: *a1
            role:
              type: string
              enum:
                - admin
                - manager
                - editor
                - viewer
                - app-user
          required:
            - email
            - role
          additionalProperties: false
        - type: object
          properties:
            user_id:
              type: string
              enum: *a1
            email:
              type: string
              enum: *a1
            group:
              type: string
            role:
              type: string
              enum:
                - manager
                - editor
                - viewer
                - app-user
          required:
            - group
            - role
          additionalProperties: false
    ProjectFederation:
      type: object
      properties:
        enabled:
          type: boolean
        target:
          type: string
      required:
        - enabled
    ProjectFederationEffective:
      type: object
      properties:
        enabled:
          type: boolean
        source:
          type: string
          enum:
            - project
            - deployment
            - unavailable
          description: '`project` when a stored override applies, `deployment` when the
            deployment default applies, `unavailable` when the deployment has no
            workload identity federation.'
      required:
        - enabled
        - source
    SecurityLabels:
      type: object
      properties:
        classification:
          type: string
        compartments:
          type: array
          items:
            type: string
      required:
        - classification
        - compartments
    ProjectFederationInput:
      type: object
      properties:
        enabled:
          type: boolean
          example: true
        target:
          type: string
          example: default
      required:
        - enabled
    SecurityLabelsInput:
      type: object
      properties:
        classification:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$
        compartments:
          type: array
          items:
            type: string
            pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$
          maxItems: 64
      required:
        - classification
        - compartments
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
      required:
        - success
    AssignableRole:
      type: string
      enum:
        - manager
        - editor
        - viewer
        - app-user
      example: editor
    ProjectAlertDestinationPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ProjectAlertDestination'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    ProjectAlertDestination:
      oneOf:
        - type: object
          properties:
            id:
              type: string
              pattern: ^alert-[0-9a-z]{16}$
            name:
              type: string
            kinds:
              type: array
              items:
                type: string
                enum: &a2
                  - member.invited
                  - member.added
                  - member.group_added
                  - member.role_changed
                  - member.removed
                  - session.takeover
                  - notebook.deleted
                  - project.deleted
                  - project.default_access_changed
                  - app.start_failed
                  - app.unavailable
                  - sync.failed
                  - job.run.failed
                  - job.run.succeeded
                  - unknown
                description: 'Known values: member.invited, member.added, member.group_added,
                  member.role_changed, member.removed, session.takeover,
                  notebook.deleted, project.deleted,
                  project.default_access_changed, app.start_failed,
                  app.unavailable, sync.failed, job.run.failed,
                  job.run.succeeded. Unrecognized values normalize to unknown.'
                example: member.invited
            enabled:
              type: boolean
            verified_at:
              type:
                - string
                - 'null'
              format: date-time
            endpoint_host:
              type: string
            created_by:
              type: string
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            type:
              type: string
              enum:
                - slack
            webhook_url_set:
              type: boolean
              enum:
                - true
          required:
            - id
            - name
            - kinds
            - enabled
            - verified_at
            - endpoint_host
            - created_by
            - created_at
            - updated_at
            - type
            - webhook_url_set
        - type: object
          properties:
            id:
              type: string
              pattern: ^alert-[0-9a-z]{16}$
            name:
              type: string
            kinds:
              type: array
              items:
                type: string
                enum: *a2
                description: 'Known values: member.invited, member.added, member.group_added,
                  member.role_changed, member.removed, session.takeover,
                  notebook.deleted, project.deleted,
                  project.default_access_changed, app.start_failed,
                  app.unavailable, sync.failed, job.run.failed,
                  job.run.succeeded. Unrecognized values normalize to unknown.'
                example: member.invited
            enabled:
              type: boolean
            verified_at:
              type:
                - string
                - 'null'
              format: date-time
            endpoint_host:
              type: string
            created_by:
              type: string
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
            type:
              type: string
              enum:
                - webhook
            url_set:
              type: boolean
              enum:
                - true
            signing_secret_set:
              type: boolean
              enum:
                - true
          required:
            - id
            - name
            - kinds
            - enabled
            - verified_at
            - endpoint_host
            - created_by
            - created_at
            - updated_at
            - type
            - url_set
            - signing_secret_set
    AuditLogPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AuditLogEntry'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    AuditLogEntry:
      type: object
      properties:
        id:
          type: string
        schema_version:
          type: integer
          exclusiveMinimum: 0
        ts:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        event:
          type: string
          example: project.update
        actor:
          type: string
        metadata:
          type: object
          additionalProperties: {}
      required:
        - id
        - schema_version
        - ts
        - event
        - actor
        - metadata
    AuditEvent:
      type: object
      properties:
        ts:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        event:
          type: string
          example: project.update
        actor:
          type: string
      required:
        - ts
        - event
        - actor
      additionalProperties: {}
    RuntimeDashboard:
      type: object
      properties:
        observed_at:
          type: string
          format: date-time
        apps:
          type: array
          items:
            type: object
            properties:
              origin:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - preview
                  notebook_id:
                    type: string
                  preview_id:
                    type: string
                  revision_id:
                    type: string
                  commit:
                    type: string
                    pattern: ^[a-fA-F0-9]{40}$
                required:
                  - type
                  - notebook_id
                  - preview_id
                  - revision_id
                  - commit
              resource_path:
                type: string
              project_id:
                type: string
              project_name:
                type: string
              notebook_id:
                type: string
              notebook_title:
                type: string
              current_version_id:
                type:
                  - string
                  - 'null'
              current_version_members:
                type:
                  - integer
                  - 'null'
                minimum: 0
              sandboxes:
                type: array
                items:
                  type: object
                  properties:
                    origin:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - preview
                        notebook_id:
                          type: string
                        preview_id:
                          type: string
                        revision_id:
                          type: string
                        commit:
                          type: string
                          pattern: ^[a-fA-F0-9]{40}$
                      required:
                        - type
                        - notebook_id
                        - preview_id
                        - revision_id
                        - commit
                    session_id:
                      type: string
                    sandbox_id:
                      type:
                        - string
                        - 'null'
                    user_id:
                      type: string
                    status:
                      type:
                        - string
                        - 'null'
                      enum:
                        - starting
                        - running
                        - terminating
                        - terminated
                        - failed
                        - expired
                        - null
                    started_at:
                      type: string
                      format: date-time
                    last_heartbeat:
                      type:
                        - string
                        - 'null'
                      format: date-time
                    source_version_id:
                      type:
                        - string
                        - 'null'
                    compute_profile:
                      type:
                        - string
                        - 'null'
                    active_connections:
                      type:
                        - integer
                        - 'null'
                      minimum: 0
                    connections_checked_at:
                      type:
                        - string
                        - 'null'
                      format: date-time
                    pool_state:
                      type:
                        - string
                        - 'null'
                      enum:
                        - starting
                        - ready
                        - draining
                        - retiring
                        - null
                    version_status:
                      type: string
                      enum:
                        - current
                        - old
                        - unknown
                    legacy:
                      type: boolean
                    users:
                      type:
                        - integer
                        - 'null'
                      minimum: 0
                      description: Occupied browser-session slots, including reconnect grace.
                    idle_since:
                      type:
                        - string
                        - 'null'
                      format: date-time
                    assignments:
                      type: array
                      items:
                        type: object
                        properties:
                          user_id:
                            type: string
                          visits:
                            type: integer
                            minimum: 0
                          state:
                            type: string
                            enum:
                              - active
                              - grace
                          expires_at:
                            type: string
                            format: date-time
                        required:
                          - user_id
                          - visits
                          - state
                          - expires_at
                    incomplete:
                      type: boolean
                  required:
                    - session_id
                    - sandbox_id
                    - user_id
                    - status
                    - started_at
                    - last_heartbeat
                    - source_version_id
                    - compute_profile
                    - active_connections
                    - connections_checked_at
                    - pool_state
                    - version_status
                    - legacy
                    - users
                    - idle_since
                    - assignments
                    - incomplete
              incomplete:
                type: boolean
            required:
              - project_id
              - project_name
              - notebook_id
              - notebook_title
              - current_version_id
              - current_version_members
              - sandboxes
              - incomplete
        editors:
          type: array
          items:
            type: object
            properties:
              origin:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - preview
                  notebook_id:
                    type: string
                  preview_id:
                    type: string
                  revision_id:
                    type: string
                  commit:
                    type: string
                    pattern: ^[a-fA-F0-9]{40}$
                required:
                  - type
                  - notebook_id
                  - preview_id
                  - revision_id
                  - commit
              resource_path:
                type: string
              project_id:
                type: string
              project_name:
                type: string
              notebook_id:
                type: string
              notebook_title:
                type: string
              session_id:
                type: string
              sandbox_id:
                type:
                  - string
                  - 'null'
              user_id:
                type: string
              status:
                type:
                  - string
                  - 'null'
                enum:
                  - starting
                  - running
                  - terminating
                  - terminated
                  - failed
                  - expired
                  - null
              started_at:
                type: string
                format: date-time
              last_heartbeat:
                type:
                  - string
                  - 'null'
                format: date-time
              source_version_id:
                type:
                  - string
                  - 'null'
              compute_profile:
                type:
                  - string
                  - 'null'
              active_connections:
                type:
                  - integer
                  - 'null'
                minimum: 0
              connections_checked_at:
                type:
                  - string
                  - 'null'
                format: date-time
              expires_at:
                type:
                  - string
                  - 'null'
                format: date-time
              claim_holder_id:
                type:
                  - string
                  - 'null'
              claim_holder_status:
                type:
                  - string
                  - 'null'
                enum:
                  - starting
                  - running
                  - terminating
                  - terminated
                  - failed
                  - expired
                  - null
              claim_available:
                type: boolean
              reclaimable:
                type: boolean
              reclaim_blocked_reason:
                type:
                  - string
                  - 'null'
                enum:
                  - not_terminal
                  - teardown_grace
                  - provision_grace
                  - attachment_unsupported
                  - attachment_failed
                  - kernel_active
                  - kernel_unreachable
                  - destroy_failed
                  - timeout
                  - null
                description: Why an admin reclaim would be refused now, from recorded state
                  only; null when reclaimable. Kernel activity and provider
                  failures are only known when reclaim runs.
            required:
              - project_id
              - project_name
              - notebook_id
              - notebook_title
              - session_id
              - sandbox_id
              - user_id
              - status
              - started_at
              - last_heartbeat
              - source_version_id
              - compute_profile
              - active_connections
              - connections_checked_at
              - expires_at
              - claim_holder_id
              - claim_holder_status
              - claim_available
              - reclaimable
              - reclaim_blocked_reason
        incomplete:
          type: boolean
        limits:
          type: object
          properties:
            max_users_per_session:
              type:
                - integer
                - 'null'
              exclusiveMinimum: 0
              description: Maximum browser-session slots per sandbox.
            max_sessions_per_version:
              type:
                - integer
                - 'null'
              exclusiveMinimum: 0
          required:
            - max_users_per_session
            - max_sessions_per_version
      required:
        - observed_at
        - apps
        - editors
        - incomplete
        - limits
    AdminUserPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AdminUser'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    AdminUser:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        updated_at:
          type: string
          format: date-time
        suspended_at:
          type:
            - string
            - 'null'
          format: date-time
        is_super_admin:
          type: boolean
      required:
        - id
        - email
        - name
        - updated_at
        - suspended_at
        - is_super_admin
    SandboxStartupReport:
      type: object
      properties:
        ok:
          type: boolean
        sandbox_id:
          type: string
        image:
          type:
            - string
            - 'null'
        compute_profile:
          type:
            - string
            - 'null'
        compute_resources:
          $ref: '#/components/schemas/ComputeResources'
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        total_ms:
          type: number
          minimum: 0
        handle:
          $ref: '#/components/schemas/SandboxStartupPhase'
        readiness:
          $ref: '#/components/schemas/SandboxStartupCommand'
        exec:
          $ref: '#/components/schemas/SandboxStartupCommand'
        cleanup:
          $ref: '#/components/schemas/SandboxStartupPhase'
        startup_timings_ms:
          type: object
          additionalProperties:
            type: number
            minimum: 0
        counters:
          type: object
          additionalProperties:
            type: number
        environment_setup_benchmark:
          $ref: '#/components/schemas/SandboxEnvironmentSetupBenchmark'
      required:
        - ok
        - sandbox_id
        - image
        - compute_profile
        - compute_resources
        - started_at
        - finished_at
        - total_ms
        - handle
        - readiness
        - exec
        - cleanup
        - startup_timings_ms
        - counters
        - environment_setup_benchmark
    SandboxStartupPhase:
      type: object
      properties:
        status:
          type: string
          enum:
            - ok
            - failed
            - skipped
            - unknown
          description: 'Known values: ok, failed, skipped. Unrecognized values normalize
            to unknown.'
          example: ok
        duration_ms:
          type:
            - number
            - 'null'
          minimum: 0
        error:
          type: object
          additionalProperties: {}
      required:
        - status
        - duration_ms
    SandboxStartupCommand:
      allOf:
        - $ref: '#/components/schemas/SandboxStartupPhase'
        - type: object
          properties:
            command:
              type: string
              example: echo "Hello"
            stdout:
              type: string
            stderr:
              type: string
            failure_code:
              type: string
              enum:
                - COMMAND_FAILED
                - SPAWN_FAILED
                - BACKEND_ERROR
                - unknown
              description: 'Known values: COMMAND_FAILED, SPAWN_FAILED, BACKEND_ERROR.
                Unrecognized values normalize to unknown.'
              example: COMMAND_FAILED
          required:
            - command
            - stdout
            - stderr
    SandboxEnvironmentSetupBenchmark:
      type:
        - object
        - 'null'
      properties:
        tool:
          type: string
          minLength: 1
          example: uv
        runtime_probe:
          $ref: '#/components/schemas/SandboxStartupCommand'
        artifact_download:
          $ref: '#/components/schemas/SandboxStartupCommand'
        prepare:
          $ref: '#/components/schemas/SandboxStartupCommand'
        install:
          $ref: '#/components/schemas/SandboxStartupCommand'
      required:
        - tool
        - runtime_probe
        - artifact_download
        - prepare
        - install
      description: The optional fixed-package benchmark, or null when it was not requested
    SandboxStartupRequest:
      type: object
      properties:
        image:
          type: string
          minLength: 1
        compute_profile:
          type: string
          minLength: 1
        environment_setup_benchmark:
          type: boolean
          description: Run the fixed-package uv, wheel-download, runtime, and
            CPU-throttling benchmark
      additionalProperties: false
    DeploymentConfig:
      type: object
      properties:
        deployment:
          $ref: '#/components/schemas/AdminDeployment'
        groups:
          type: array
          items:
            $ref: '#/components/schemas/ConfigGroup'
        policy:
          $ref: '#/components/schemas/AdminPolicy'
      required:
        - deployment
        - groups
        - policy
    AdminDeployment:
      type:
        - object
        - 'null'
      properties:
        version:
          type: string
        image:
          type:
            - string
            - 'null'
        sandbox_image:
          type:
            - string
            - 'null'
        started_at:
          type:
            - string
            - 'null'
        replica:
          type:
            - string
            - 'null'
        node:
          type:
            - string
            - 'null'
        backends:
          type:
            - object
            - 'null'
          properties:
            storage:
              type: string
            compute:
              type: string
            auth:
              type: string
          required:
            - storage
            - compute
            - auth
      required:
        - version
        - image
        - sandbox_image
        - started_at
        - replica
        - node
        - backends
    ConfigGroup:
      type: object
      properties:
        name:
          type: string
        backend:
          type:
            - string
            - 'null'
        settings:
          type: array
          items:
            $ref: '#/components/schemas/ConfigSetting'
      required:
        - name
        - backend
        - settings
    ConfigSetting:
      type: object
      properties:
        key:
          type: string
        name:
          type: string
        value:
          type:
            - string
            - 'null'
        secret:
          type: boolean
        set:
          type: boolean
      required:
        - key
        - name
        - value
        - secret
        - set
    AdminPolicy:
      type: object
      properties:
        default_role:
          type:
            - string
            - 'null'
          enum:
            - manager
            - editor
            - viewer
            - app-user
            - null
        super_admins:
          type: array
          items:
            type: string
      required:
        - default_role
        - super_admins
    PolicyAnalyzerMetadata:
      type: object
      properties:
        schema_version:
          type: number
          enum:
            - 1
        max_cases:
          type: integer
          exclusiveMinimum: 0
        max_groups:
          type: integer
          exclusiveMinimum: 0
        capabilities:
          type: object
          properties:
            login_policy:
              type: boolean
            resource_security:
              type: boolean
            live_self_context:
              type: boolean
          required:
            - login_policy
            - resource_security
            - live_self_context
          additionalProperties: false
        entitlements:
          type: array
          items:
            type: string
            enum:
              - super-admin
              - project-creator
              - default-role:app-user
              - default-role:viewer
              - default-role:editor
              - default-role:manager
        classification_order:
          type: array
          items:
            type: string
        actions:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
                enum:
                  - support.request
                  - project.create
                  - admin.access
                  - org-integration.manage
                  - audit.global.read
                  - directory.search
                  - app.read
                  - project.read
                  - project.update
                  - project.delete
                  - project.members.manage
                  - project.events.read
                  - project.alerts.manage
                  - notebook.write
                  - notebook.manage
                  - deep-link.manage
                  - preview.manage
                  - integration.read
                  - integration.use
                  - integration.write
                  - integration.manage
                  - change-request.publish
                  - working-branch.write
                  - security-labels.raise
                  - security-labels.lower
                  - session.attach
                  - session.stop
                  - session.surface
                  - session.proxy
                  - session.start
              scope:
                type: string
                enum:
                  - deployment
                  - project
                  - session
                  - session-start
              minimum_role:
                type:
                  - string
                  - 'null'
                enum:
                  - admin
                  - manager
                  - editor
                  - viewer
                  - app-user
                  - null
              denied_as:
                type:
                  - string
                  - 'null'
                enum:
                  - not-found
                  - forbidden
                  - null
              requires_super_admin:
                type: boolean
            required:
              - action
              - scope
              - minimum_role
              - denied_as
              - requires_super_admin
            additionalProperties: false
      required:
        - schema_version
        - max_cases
        - max_groups
        - capabilities
        - entitlements
        - classification_order
        - actions
      additionalProperties: false
    PolicySuiteResult:
      type: object
      properties:
        valid:
          type: boolean
        summary:
          $ref: '#/components/schemas/PolicySuiteSummary'
        cases:
          type: array
          items:
            $ref: '#/components/schemas/PolicyCaseResult'
      required:
        - valid
        - summary
        - cases
      additionalProperties: false
    PolicySuiteSummary:
      type: object
      properties:
        case_count:
          type: integer
          minimum: 0
        passed:
          type: integer
          minimum: 0
        failed:
          type: integer
          minimum: 0
      required:
        - case_count
        - passed
        - failed
      additionalProperties: false
    PolicyCaseResult:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        valid:
          type: boolean
        login:
          $ref: '#/components/schemas/PolicyLoginResult'
        authorization:
          $ref: '#/components/schemas/PolicyAuthorizationResult'
        errors:
          type: array
          items:
            type: object
            properties:
              stage:
                type: string
                enum:
                  - login
                  - authorization
              code:
                type: string
            required:
              - stage
              - code
            additionalProperties: false
      required:
        - id
        - name
        - valid
        - login
        - authorization
        - errors
      additionalProperties: false
    PolicyLoginResult:
      type:
        - object
        - 'null'
      properties:
        outcome:
          type: string
          enum:
            - allow
            - deny
            - timeout
            - error
            - invalid
            - unavailable
        duration_ms:
          type: number
          minimum: 0
        entitlements:
          type: array
          items:
            type: string
            enum:
              - super-admin
              - project-creator
              - default-role:app-user
              - default-role:viewer
              - default-role:editor
              - default-role:manager
        groups:
          type: array
          items:
            type: string
        reason:
          type: string
        problem:
          type: string
        assertion:
          $ref: '#/components/schemas/PolicyAssertionResult'
      required:
        - outcome
        - duration_ms
        - entitlements
        - groups
        - assertion
      additionalProperties: false
    PolicyAssertionResult:
      type: object
      properties:
        passed:
          type: boolean
        expected:
          type: object
          additionalProperties: {}
      required:
        - passed
        - expected
      additionalProperties: false
    PolicyAuthorizationResult:
      type:
        - object
        - 'null'
      properties:
        decision:
          $ref: '#/components/schemas/PolicyAuthorizationDecision'
        presentation:
          type: string
          enum:
            - allowed
            - forbidden
            - not-found
        trace:
          type: array
          items:
            $ref: '#/components/schemas/PolicyAuthorizationTraceStep'
        assertion:
          $ref: '#/components/schemas/PolicyAssertionResult'
      required:
        - decision
        - presentation
        - trace
        - assertion
      additionalProperties: false
    PolicyAuthorizationDecision:
      type: object
      properties:
        allowed:
          type: boolean
        role:
          type:
            - string
            - 'null'
          enum:
            - admin
            - manager
            - editor
            - viewer
            - app-user
            - null
        category:
          type: string
          enum:
            - lifecycle
            - visibility
            - role
            - session
            - standing
            - constraint
            - credential-resource
            - credential-action
        constraint_reason:
          type: string
          enum:
            - missing-context
            - constraint
            - unavailable
      required:
        - allowed
        - role
      additionalProperties: false
    PolicyAuthorizationTraceStep:
      type: object
      properties:
        stage:
          type: string
          enum:
            - action
            - lifecycle
            - role
            - standing
            - session
            - constraint
            - credential
            - final
        status:
          type: string
          enum:
            - passed
            - failed
            - skipped
        code:
          type: string
        details:
          type: object
          additionalProperties: {}
      required:
        - stage
        - status
        - code
      additionalProperties: false
    PolicySuiteV1:
      type: object
      properties:
        schema_version:
          type: number
          enum:
            - 1
        name:
          type: string
          minLength: 1
          maxLength: 200
        cases:
          type: array
          items:
            $ref: '#/components/schemas/PolicyCaseV1'
          minItems: 1
          maxItems: 25
      required:
        - schema_version
        - cases
      additionalProperties: false
    PolicyCaseV1:
      anyOf:
        - type: object
          properties:
            id:
              type: string
              minLength: 1
              maxLength: 128
            name:
              type: string
              minLength: 1
              maxLength: 200
            login:
              $ref: '#/components/schemas/PolicyLoginStageV1'
            authorization:
              $ref: '#/components/schemas/PolicyAuthorizationStageV1'
          required:
            - id
            - name
            - login
          additionalProperties: false
        - type: object
          properties:
            id:
              type: string
              minLength: 1
              maxLength: 128
            name:
              type: string
              minLength: 1
              maxLength: 200
            login:
              $ref: '#/components/schemas/PolicyLoginStageV1'
            authorization:
              $ref: '#/components/schemas/PolicyAuthorizationStageV1'
          required:
            - id
            - name
            - authorization
          additionalProperties: false
    PolicyLoginStageV1:
      type: object
      properties:
        identity:
          type: object
          properties:
            id:
              type: string
              minLength: 1
            email:
              type: string
              minLength: 3
              maxLength: 320
          required:
            - id
            - email
          additionalProperties: false
        id_token_claims:
          type: object
          additionalProperties: {}
        user_info_claims:
          type: object
          additionalProperties: {}
        expected:
          $ref: '#/components/schemas/PolicyLoginExpectationV1'
      required:
        - identity
        - id_token_claims
        - expected
      additionalProperties: false
    PolicyLoginExpectationV1:
      oneOf:
        - type: object
          properties:
            outcome:
              type: string
              enum:
                - allow
            entitlements:
              type: array
              items:
                type: string
                enum:
                  - super-admin
                  - project-creator
                  - default-role:app-user
                  - default-role:viewer
                  - default-role:editor
                  - default-role:manager
            groups:
              type: array
              items:
                type: string
          required:
            - outcome
          additionalProperties: false
        - type: object
          properties:
            outcome:
              type: string
              enum:
                - deny
          required:
            - outcome
          additionalProperties: false
    PolicyAuthorizationStageV1:
      type: object
      properties:
        subject:
          type: object
          properties:
            id:
              type: string
              minLength: 1
            email:
              type: string
              minLength: 3
              maxLength: 320
            entitlement_source:
              type: string
              enum:
                - explicit
                - login
            entitlements:
              type: array
              items:
                type: string
                enum:
                  - super-admin
                  - project-creator
                  - default-role:app-user
                  - default-role:viewer
                  - default-role:editor
                  - default-role:manager
            groups:
              type: array
              items:
                type: string
            grant:
              type: object
              properties:
                actions:
                  anyOf:
                    - type: string
                      enum:
                        - '*'
                    - type: array
                      items:
                        type: string
                        enum:
                          - support.request
                          - project.create
                          - admin.access
                          - org-integration.manage
                          - audit.global.read
                          - directory.search
                          - app.read
                          - project.read
                          - project.update
                          - project.delete
                          - project.members.manage
                          - project.events.read
                          - project.alerts.manage
                          - notebook.write
                          - notebook.manage
                          - deep-link.manage
                          - preview.manage
                          - integration.read
                          - integration.use
                          - integration.write
                          - integration.manage
                          - change-request.publish
                          - working-branch.write
                          - security-labels.raise
                          - security-labels.lower
                          - session.attach
                          - session.stop
                          - session.surface
                          - session.proxy
                          - session.start
                      uniqueItems: true
                projects:
                  anyOf:
                    - type: string
                      enum:
                        - '*'
                    - type: array
                      items:
                        type: string
                        pattern: ^proj-[0-9a-z]{16}$
                      minItems: 1
                      maxItems: 100
                      uniqueItems: true
              required:
                - actions
                - projects
              additionalProperties: false
          required:
            - id
            - email
            - entitlement_source
          additionalProperties: false
        action:
          type: string
          enum:
            - support.request
            - project.create
            - admin.access
            - org-integration.manage
            - audit.global.read
            - directory.search
            - app.read
            - project.read
            - project.update
            - project.delete
            - project.members.manage
            - project.events.read
            - project.alerts.manage
            - notebook.write
            - notebook.manage
            - deep-link.manage
            - preview.manage
            - integration.read
            - integration.use
            - integration.write
            - integration.manage
            - change-request.publish
            - working-branch.write
            - security-labels.raise
            - security-labels.lower
            - session.attach
            - session.stop
            - session.surface
            - session.proxy
            - session.start
        resource:
          $ref: '#/components/schemas/PolicyAuthorizationResourceV1'
        context:
          $ref: '#/components/schemas/PolicyAuthorizationContextV1'
        expected:
          type: object
          properties:
            allowed:
              type: boolean
            denial_category:
              type: string
              enum:
                - lifecycle
                - visibility
                - role
                - session
                - standing
                - constraint
                - credential-resource
                - credential-action
          required:
            - allowed
          additionalProperties: false
      required:
        - subject
        - action
        - resource
        - context
        - expected
      additionalProperties: false
    PolicyAuthorizationResourceV1:
      type: object
      properties:
        source:
          type: string
          enum:
            - stored
            - synthetic
        kind:
          type: string
          enum:
            - deployment
            - project
            - session
            - session-start
        app_only:
          type: boolean
          description: Whether the subject has only app-user access. Valid only for
            deployment resources. When omitted, project creation requires
            project-creator or super-admin standing.
        project_id:
          type: string
        notebook_id:
          type: string
        session_id:
          type: string
        project:
          type: object
          properties:
            owner:
              type: string
              minLength: 1
            members:
              type: array
              items:
                type: object
                properties:
                  user_id:
                    type: string
                    minLength: 1
                  group:
                    type: string
                  email:
                    type: string
                    minLength: 3
                    maxLength: 320
                  role:
                    type: string
                    enum:
                      - admin
                      - manager
                      - editor
                      - viewer
                      - app-user
                required:
                  - role
                additionalProperties: false
              maxItems: 500
            status:
              type: string
              enum:
                - active
                - deleted
              default: active
            security_labels:
              type: object
              properties:
                classification:
                  type: string
                  pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$
                compartments:
                  type: array
                  items:
                    type: string
                    pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$
                  maxItems: 64
              required:
                - classification
                - compartments
              additionalProperties: false
          required:
            - owner
            - members
          additionalProperties: false
        notebook_labels:
          type: object
          properties:
            classification:
              type: string
              pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$
            compartments:
              type: array
              items:
                type: string
                pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$
              maxItems: 64
          required:
            - classification
            - compartments
          additionalProperties: false
        session:
          type: object
          properties:
            mode:
              type: string
              enum:
                - edit
                - app
            ephemeral:
              type: boolean
            restricted_viewer_credentials:
              type: boolean
            user_id:
              type: string
              minLength: 1
            editor_sandbox_sharing:
              type: string
              enum:
                - shared
                - exclusive
          required:
            - user_id
          additionalProperties: false
        mode:
          type: string
          enum:
            - edit
            - app
      required:
        - source
        - kind
      additionalProperties: false
    PolicyAuthorizationContextV1:
      oneOf:
        - type: object
          properties:
            mode:
              type: string
              enum:
                - live-self
          required:
            - mode
          additionalProperties: false
        - type: object
          properties:
            mode:
              type: string
              enum:
                - synthetic
            value:
              type:
                - object
                - 'null'
              properties:
                schemaVersion:
                  type: number
                  enum:
                    - 1
                classification:
                  type: string
                  pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$
                compartments:
                  type: array
                  items:
                    type: string
                    pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$
                  maxItems: 64
                policyVersion:
                  type: string
                  pattern: ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,63}$
                expiresAt:
                  type: string
                  format: date-time
              required:
                - schemaVersion
                - classification
                - compartments
                - policyVersion
                - expiresAt
              additionalProperties: false
          required:
            - mode
            - value
          additionalProperties: false
    WorkspaceItem:
      type: object
      properties:
        path:
          type: string
        name:
          type: string
        kind:
          type: string
          enum:
            - file
            - directory
        size:
          type: integer
          minimum: 0
        modified_at:
          type: integer
          minimum: 0
        mime_type:
          type: string
      required:
        - path
        - name
        - kind
    WorkspaceAccess:
      type: object
      properties:
        writable:
          type: boolean
        read_only_reason:
          type:
            - string
            - 'null'
          enum:
            - git_source
            - viewer
            - active_session
            - null
        protected_paths:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              denied_operations:
                type: array
                items:
                  type: string
                  enum:
                    - create
                    - write
                    - move
                    - copy
                    - delete
            required:
              - path
              - denied_operations
      required:
        - writable
        - read_only_reason
        - protected_paths
    NotebookPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SnapshotNotebookEntry'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    SnapshotNotebookEntry:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - draft
            - active
            - archived
            - deleted
        source_type:
          type: string
          enum:
            - local
            - git
        author:
          type: string
        created_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        updated_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        tags:
          type: array
          items:
            type: string
        last_run_at:
          type:
            - string
            - 'null'
          format: date-time
          example: 2025-03-05T14:00:00Z
        compute_profile:
          type: string
        app_compute_profile:
          type: string
        moving:
          type: object
          properties:
            destination_project_id:
              type: string
          required:
            - destination_project_id
      required:
        - id
        - title
        - description
        - status
        - source_type
        - author
        - created_at
        - updated_at
        - tags
        - last_run_at
    NotebookMeta:
      type: object
      properties:
        id:
          type: string
        project_id:
          type: string
        title:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
            - draft
            - active
            - archived
            - deleted
        author:
          type: string
        created_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        updated_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        last_run_at:
          type:
            - string
            - 'null'
          format: date-time
          example: 2025-03-05T14:00:00Z
        tags:
          type: array
          items:
            type: string
        runtime:
          type: object
          properties:
            python_version:
              type: string
            marimo_version:
              type: string
        base_image:
          type: string
        compute_profile:
          type: string
        app_compute_profile:
          type: string
        security_labels:
          $ref: '#/components/schemas/SecurityLabels'
      required:
        - id
        - project_id
        - title
        - description
        - status
        - author
        - created_at
        - updated_at
        - last_run_at
        - tags
    GitNotebookCreateResult:
      type: object
      properties:
        notebook:
          $ref: '#/components/schemas/NotebookMeta'
        sync_url:
          type: string
        sync_token:
          type: string
        sync_error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
          description: Initial pull failure. The draft notebook remains available and can
            be retried with Sync now.
      required:
        - notebook
    SyncToken:
      type: object
      properties:
        sync_url:
          type: string
        sync_token:
          type: string
      required:
        - sync_url
        - sync_token
    GitSourceConfig:
      type: object
      properties:
        repo:
          type: string
          description: 'Normalized repository coordinate: owner/repo or an HTTPS
            repository URL.'
          example: marimo-team/marimohub
        branch:
          type: string
          description: Synced repository branch.
          example: main
        root_path:
          type: string
          description: Repository-relative directory synced into the notebook workspace.
          example: apps
        entry_notebook:
          type: string
          description: Path to the entry notebook relative to root_path.
          example: dashboard.py
      required:
        - repo
        - branch
        - root_path
        - entry_notebook
    SourceDrift:
      type: object
      properties:
        current_commit:
          type:
            - string
            - 'null'
          description: Commit of the last successful sync; null before the first sync.
        remote_commit:
          type: string
          description: Live head of the configured branch, resolved at request time.
        in_sync:
          type: boolean
        pending_config:
          type: boolean
          description: Whether a settings edit is waiting for a matching sync.
        checked_at:
          type: string
          format: date-time
      required:
        - current_commit
        - remote_commit
        - in_sync
        - pending_config
        - checked_at
    SourceSyncResult:
      type: object
      properties:
        synced:
          type: boolean
          description: False when the notebook was already at the branch head.
        commit:
          type: string
        version_id:
          type:
            - string
            - 'null'
      required:
        - synced
        - commit
        - version_id
    NotebookDetail:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/NotebookMeta'
        readme:
          type:
            - string
            - 'null'
        source:
          $ref: '#/components/schemas/Source'
      required:
        - meta
        - readme
        - source
    Source:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - local
            entry_notebook:
              type: string
            current_version_id:
              type: string
          required:
            - type
            - current_version_id
        - type: object
          properties:
            working_branch:
              type: object
              properties:
                id:
                  type: string
                  pattern: ^[a-f0-9]{64}$
                base_branch:
                  type: string
                  minLength: 1
                fork_commit:
                  type: string
                  minLength: 1
                created_by:
                  type: string
              required:
                - id
                - base_branch
                - fork_commit
                - created_by
            type:
              type: string
              enum:
                - git
            provider:
              type:
                - string
                - 'null'
              minLength: 1
              description: Detected Git provider id, or null when the repository host is not
                recognized.
              example: github
            repo:
              type: string
              description: 'Normalized repository coordinate: owner/repo or an HTTPS
                repository URL.'
              example: marimo-team/marimohub
            branch:
              type: string
              description: Synced repository branch.
              example: main
            root_path:
              type: string
              description: Repository-relative directory synced into the notebook workspace.
              example: apps
            entry_notebook:
              type: string
              description: Path to the entry notebook relative to root_path.
              example: dashboard.py
            pending_config:
              $ref: '#/components/schemas/GitSourceConfig'
            sync_mode:
              type: string
              enum:
                - push
                - pull
            current_version_id:
              type:
                - string
                - 'null'
            commit:
              type:
                - string
                - 'null'
            last_synced_at:
              type:
                - string
                - 'null'
              format: date-time
              example: 2025-03-05T14:00:00Z
          required:
            - type
            - provider
            - repo
            - branch
            - root_path
            - entry_notebook
            - sync_mode
            - current_version_id
            - commit
            - last_synced_at
    NotebookVersionPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NotebookVersion'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    NotebookVersion:
      type: object
      properties:
        version_id:
          type: string
        notebook_id:
          type: string
        saved_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        author:
          type: string
        message:
          type: string
        parent_id:
          type:
            - string
            - 'null'
        html_snapshot:
          $ref: '#/components/schemas/SnapshotDescriptor'
        session_snapshot:
          $ref: '#/components/schemas/SnapshotDescriptor'
        commit:
          type: string
        git_source:
          $ref: '#/components/schemas/GitSourceRevision'
      required:
        - version_id
        - notebook_id
        - saved_at
        - author
        - message
        - parent_id
    SnapshotDescriptor:
      type: object
      properties:
        captured_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        size_bytes:
          type: number
      required:
        - captured_at
        - size_bytes
    GitSourceRevision:
      type: object
      properties:
        provider:
          type:
            - string
            - 'null'
          minLength: 1
          description: Detected provider id for this immutable source revision, or null
            when the repository host is unrecognized.
          example: github
        repo:
          type: string
          description: 'Normalized repository coordinate: owner/repo or an HTTPS
            repository URL.'
          example: marimo-team/marimohub
        branch:
          type: string
          description: Synced repository branch.
          example: main
        root_path:
          type: string
          description: Repository-relative directory synced into the notebook workspace.
          example: apps
        entry_notebook:
          type: string
          description: Path to the entry notebook relative to root_path.
          example: dashboard.py
        commit:
          type: string
          description: Immutable Git commit from which the saved version was synced.
          example: 9e107d9d372bb6826bd81d3542a419d6
      required:
        - provider
        - repo
        - branch
        - root_path
        - entry_notebook
        - commit
    NotebookApp:
      type: object
      properties:
        project_id:
          type: string
        project_name:
          type: string
        notebook_id:
          type: string
        title:
          type: string
        url:
          type: string
        your_role:
          type:
            - string
            - 'null'
          enum:
            - admin
            - manager
            - editor
            - viewer
            - app-user
            - null
        can:
          type: object
          properties:
            run:
              type: boolean
          required:
            - run
      required:
        - project_id
        - project_name
        - notebook_id
        - title
        - url
        - your_role
        - can
    DeepLink:
      type: object
      properties:
        schema_version:
          type: number
          enum:
            - 1
        registration_id:
          type: string
          format: ulid
        slug:
          type: string
          minLength: 1
          maxLength: 63
          pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?![\s\S])
        target:
          type: object
          properties:
            kind:
              type: string
              enum:
                - app
            project_id:
              type: string
            notebook_id:
              type: string
          required:
            - kind
            - project_id
            - notebook_id
          additionalProperties: false
        access:
          type: object
          properties:
            mode:
              type: string
              enum:
                - inherit
          required:
            - mode
          additionalProperties: false
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
      required:
        - schema_version
        - registration_id
        - slug
        - target
        - access
        - created_by
        - created_at
      additionalProperties: false
    SearchResponse:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                minLength: 1
                maxLength: 1024
              kind:
                type: string
                enum:
                  - notebook
                  - code
                  - output
                  - datasource
                  - namespace
                  - table
                  - column
                  - unknown
                description: 'Known values: notebook, code, output, datasource, namespace,
                  table, column. Unrecognized values normalize to unknown.'
                example: notebook
              resource:
                oneOf:
                  - type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - notebook
                      notebook_id:
                        type: string
                    required:
                      - type
                      - notebook_id
                  - type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - integration
                      integration_id:
                        type: string
                      version:
                        type: integer
                        exclusiveMinimum: 0
                      namespace:
                        type: array
                        items:
                          type: string
                          maxLength: 256
                        maxItems: 16
                      table:
                        type: string
                        maxLength: 256
                      column:
                        type: string
                        maxLength: 256
                    required:
                      - type
                      - integration_id
                      - version
              title:
                type: string
                maxLength: 256
              project_id:
                type: string
              project_name:
                type: string
                maxLength: 256
              href:
                type: string
                maxLength: 4096
              indexed_at:
                type: string
                format: date-time
              snippet:
                type: object
                properties:
                  text:
                    type: string
                    maxLength: 400
                  highlights:
                    type: array
                    items:
                      type: object
                      properties:
                        start:
                          type: integer
                          minimum: 0
                        end:
                          type: integer
                          minimum: 0
                      required:
                        - start
                        - end
                    maxItems: 200
                required:
                  - text
                  - highlights
            required:
              - id
              - kind
              - resource
              - title
              - project_id
              - project_name
              - href
              - indexed_at
              - snippet
          maxItems: 50
        partial:
          type: boolean
        coverage:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
                maxLength: 64
              project_id:
                type: string
              status:
                type: string
                enum:
                  - complete
                  - partial
                  - truncated
                  - unavailable
                  - timeout
                  - not_indexed
                  - stale
                  - disabled
                  - unknown
                description: 'Known values: complete, partial, truncated, unavailable, timeout,
                  not_indexed, stale, disabled. Unrecognized values normalize to
                  unknown.'
                example: complete
            required:
              - source
              - status
          maxItems: 100
      required:
        - items
        - partial
        - coverage
    NotebookPreview:
      type: object
      properties:
        id:
          type: string
          pattern: ^prev-[0-9a-z]{16}$
        name:
          type: string
        preparation:
          type: string
          enum:
            - deferred
            - pending
            - preparing
            - ready
            - failed
            - unknown
          description: 'Known values: deferred, pending, preparing, ready, failed.
            Unrecognized values normalize to unknown.'
          example: ready
        source_type:
          type: string
          enum:
            - branch
            - commit
            - unknown
          description: 'Known values: branch, commit. Unrecognized values normalize to
            unknown.'
          example: branch
        source:
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - branch
                branch:
                  type: string
                  minLength: 1
                  pattern: ^(?!@(?:$|\{))(?![-/])(?!.*(?:\.\.|\/\/|@\{|[\x00-\x20\x7f~^:?*[\\]))(?!.*(?:^|\/)\.)(?!.*\.lock(?:\/|$))[^/]+(?:\/[^/]+)*(?<![/.])$
              required:
                - type
                - branch
              additionalProperties: false
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - commit
                commit:
                  type: string
                  pattern: ^[a-fA-F0-9]{40}$
              required:
                - type
                - commit
              additionalProperties: false
        repository:
          type: string
        commit:
          type: string
        version_id:
          type: string
        error:
          type: string
        pull_request:
          type: integer
          exclusiveMinimum: 0
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        eager:
          type: boolean
        managed:
          type: boolean
        target_commit:
          type: string
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
        checked_at:
          type: string
          format: date-time
        compute_profile:
          type: string
        url:
          type: string
        can:
          type: object
          properties:
            manage:
              type: boolean
            app:
              type: boolean
            edit:
              type: boolean
          required:
            - manage
            - app
            - edit
      required:
        - id
        - name
        - preparation
        - source_type
        - expires_at
        - created_at
        - created_by
        - url
        - can
    NotebookPreviewPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NotebookPreview'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    SessionCreateResult:
      allOf:
        - $ref: '#/components/schemas/Session'
        - type: object
          properties:
            app_assignment:
              type: object
              properties:
                visit_id:
                  type: string
                  minLength: 1
                  maxLength: 128
                generation:
                  type: string
                  minLength: 1
                  maxLength: 128
              required:
                - visit_id
                - generation
            reused:
              type: boolean
            editor_session:
              type: object
              properties:
                sharing:
                  type: string
                  enum:
                    - shared
                    - exclusive
                access:
                  type: string
                  enum:
                    - shared
                    - owner
                    - temporary
              required:
                - sharing
                - access
          required:
            - reused
    Surface:
      type: object
      properties:
        status:
          type: string
          enum:
            - starting
            - ready
            - stopping
            - stopped
            - failed
            - unavailable
        port:
          type: integer
          exclusiveMinimum: 0
        url:
          type: string
        started_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        probe:
          type: object
          properties:
            available:
              type: boolean
            reason:
              type: string
            version:
              type: string
          required:
            - available
        last_error:
          type: string
      required:
        - status
    Session:
      type: object
      properties:
        origin:
          type: object
          properties:
            type:
              type: string
              enum:
                - preview
            notebook_id:
              type: string
            preview_id:
              type: string
            revision_id:
              type: string
            commit:
              type: string
              pattern: ^[a-fA-F0-9]{40}$
          required:
            - type
            - notebook_id
            - preview_id
            - revision_id
            - commit
        resource_path:
          type: string
        app_assignment:
          type: object
          properties:
            visit_id:
              type: string
            generation:
              type: string
          required:
            - visit_id
            - generation
        app_pool:
          type: object
          properties:
            state:
              type: string
              enum:
                - starting
                - ready
                - draining
                - retiring
            users:
              type: number
              description: Occupied browser-session slots, including reconnect grace.
            max_users:
              type:
                - number
                - 'null'
              description: Maximum browser-session slots per sandbox.
          required:
            - state
            - users
            - max_users
        session_id:
          type: string
        notebook_id:
          type: string
        project_id:
          type: string
        user_id:
          type: string
        status:
          type: string
          enum:
            - starting
            - running
            - terminating
            - terminated
            - failed
            - expired
        sandbox_url:
          type: string
        links:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
              href:
                type: string
            required:
              - id
              - label
              - href
        started_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        last_heartbeat:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        ephemeral:
          type: boolean
        editor_sandbox_sharing:
          type: string
          enum:
            - shared
            - exclusive
        ended_reason:
          type: string
          enum:
            - takeover
        ended_by_user_id:
          type: string
        mode:
          type: string
          enum:
            - edit
            - app
        source_version_id:
          type: string
          description: Version used to provision the session. Working-branch saves
            preserve this launch provenance.
        working_branch_version_id:
          type: string
          description: Latest source version acknowledged by a working-branch save.
            Omitted for app-only access and preview sessions.
        head_version_id:
          type:
            - string
            - 'null'
          description: Current head version of the notebook source. Sent only in heartbeat
            responses for running or starting app sessions. Omitted for app
            users, credentials without project.read, preview runtimes, and edit
            sessions. Start, get, and list responses never include it.
        edit_active:
          type: boolean
          description: True when a persistent editor holds the notebook editor claim. Sent
            and omitted under the same rules as head_version_id.
        can:
          type: object
          properties:
            attach:
              type: boolean
            stop:
              type: boolean
            surfaces:
              type: object
              properties:
                vscode:
                  type: boolean
                opencode:
                  type: boolean
              required:
                - vscode
                - opencode
          required:
            - attach
            - stop
        surfaces:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Surface'
        active_connections:
          type: number
        connections_checked_at:
          type: string
          format: date-time
          example: 2025-03-05T14:00:00Z
        compute_profile:
          type: string
        compute_resources:
          $ref: '#/components/schemas/ComputeResources'
        compute_from_snapshot:
          type: boolean
        integrations:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              kind:
                type: string
              version:
                type: integer
            required:
              - id
              - name
              - kind
              - version
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
      required:
        - session_id
        - notebook_id
        - project_id
        - status
        - started_at
        - last_heartbeat
        - mode
        - can
    NotebookAppPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NotebookApp'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    OpenNotebookChangeRequestResult:
      type: object
      properties:
        proposal_id:
          type: string
          pattern: ^prop-[0-9a-z]{16}$
          description: Identifier of the immutable proposal captured from the notebook
            session and published by this change request.
          example: prop-7h2k9qm4xz7rp3w8
        change_request:
          type: object
          properties:
            provider:
              type: string
              minLength: 1
              example: github
            number:
              type: integer
              exclusiveMinimum: 0
              example: 42
            url:
              type: string
              format: uri
              example: https://github.com/acme/analytics/pull/42
            head_branch:
              type: string
              minLength: 1
              example: marimohub/nb-7h2k9qm4xz7rp3w8/prop-7h2k9qm4xz7rp3w8
            head_commit:
              type: string
              minLength: 1
              example: 9e107d9d372bb6826bd81d3542a419d6
          required:
            - provider
            - number
            - url
            - head_branch
            - head_commit
      required:
        - proposal_id
        - change_request
    OpenNotebookChangeRequestBody:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 256
          description: Change request title. Defaults to the notebook title.
          example: Update revenue dashboard
        body:
          type: string
          maxLength: 65536
          description: Change request description. Defaults to the session and base commit.
          example: Updates the regional revenue analysis.
        target_proposal_id:
          type: string
          pattern: ^prop-[0-9a-z]{16}$
          description: Published proposal whose existing change request should receive
            this new proposal. Omit to create a new change request.
          example: prop-7h2k9qm4xz7rp3w8
    WorkingBranchSave:
      type: object
      properties:
        id:
          type: string
          pattern: ^[a-f0-9]{64}$
        project_id:
          type: string
        notebook_id:
          type: string
        session_id:
          type: string
        author:
          type: string
        message:
          type: string
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        base_version_id:
          type: string
        base_commit:
          type: string
        state:
          type: string
          enum:
            - claimed
            - captured
            - commit_prepared
            - ref_dispatched
            - remote_committed
            - hub_synced
            - complete
            - no_changes
            - conflict
            - expired
        changes:
          type: array
          items:
            oneOf:
              - type: object
                properties:
                  path:
                    type: string
                    minLength: 1
                  operation:
                    type: string
                    enum:
                      - add
                      - modify
                  size_bytes:
                    type: integer
                    minimum: 0
                  sha256:
                    type: string
                    pattern: ^[0-9a-f]{64}$
                required:
                  - path
                  - operation
                  - size_bytes
                  - sha256
              - type: object
                properties:
                  path:
                    type: string
                    minLength: 1
                  operation:
                    type: string
                    enum:
                      - delete
                required:
                  - path
                  - operation
          default: []
        commit:
          type: string
        dispatched_at:
          type: string
          format: date-time
        version_id:
          type: string
        error:
          type: string
      required:
        - id
        - project_id
        - notebook_id
        - session_id
        - author
        - message
        - created_at
        - expires_at
        - base_version_id
        - base_commit
        - state
    WorkingBranchStatus:
      type: object
      properties:
        base_branch:
          type: string
        branch:
          type: string
        commit:
          type:
            - string
            - 'null'
        remote_commit:
          type:
            - string
            - 'null'
        change_request:
          $ref: '#/components/schemas/WorkingBranchChangeRequestResponse'
        checked_at:
          type: string
        last_save:
          $ref: '#/components/schemas/WorkingBranchSave'
        active_save:
          type: string
        ended_reason:
          type: string
          enum:
            - branch_deleted
            - pr_closed
            - pr_merged
            - pr_retargeted
            - unknown
          description: 'Known values: branch_deleted, pr_closed, pr_merged, pr_retargeted.
            Unrecognized values normalize to unknown.'
          example: pr_merged
      required:
        - base_branch
        - branch
        - commit
        - remote_commit
    WorkingBranchChangeRequestResponse:
      type: object
      properties:
        number:
          type: integer
          exclusiveMinimum: 0
        url:
          type: string
          format: uri
        state:
          type: string
          enum:
            - open
            - closed
            - merged
            - unknown
          description: 'Known values: open, closed, merged. Unrecognized values normalize
            to unknown.'
          example: open
        head_branch:
          type: string
        base_branch:
          type: string
      required:
        - number
        - url
        - state
        - head_branch
        - base_branch
    SessionPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Session'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    EditorSessionState:
      type: object
      properties:
        sharing:
          type: string
          enum:
            - shared
            - exclusive
        holder:
          type:
            - object
            - 'null'
          properties:
            session_id:
              type: string
            user_id:
              type: string
            status:
              type: string
              enum:
                - starting
                - running
                - terminating
            started_at:
              type: string
            activity:
              type: object
              properties:
                state:
                  type: string
                  enum:
                    - active
                    - idle
                    - unknown
                    - starting
                active_connections:
                  type: number
                checked_at:
                  type: string
              required:
                - state
          required:
            - session_id
            - user_id
            - status
            - started_at
            - activity
        can_take_over:
          type: boolean
        transfer:
          type: object
          properties:
            status:
              type: string
              enum:
                - requested
                - draining
                - ready
          required:
            - status
      required:
        - sharing
        - holder
        - can_take_over
    EditorTakeoverBody:
      type: object
      properties:
        takeover_id:
          type: string
          minLength: 1
          maxLength: 255
        expected_holder_session_id:
          type: string
        expected_activity:
          type: string
          enum:
            - active
            - idle
            - unknown
            - starting
        acknowledge_disruption:
          type: boolean
          enum:
            - true
      required:
        - takeover_id
        - expected_holder_session_id
        - expected_activity
        - acknowledge_disruption
    SessionCreateBody:
      type: object
      properties:
        mode:
          type: string
          enum:
            - edit
            - app
        app_visit_id:
          type: string
          minLength: 1
          maxLength: 128
        replace_app_session_id:
          type: string
          description: Replace the selected app sandbox without joining it. Requires
            permission to stop that sandbox.
        compute_profile:
          type: string
          minLength: 1
        edit_intent:
          type: string
          enum:
            - temporary
        surfaces:
          type: array
          items:
            type: string
            enum:
              - vscode
              - opencode
          maxItems: 2
      additionalProperties: false
    SurfaceStartBody:
      type: object
      properties:
        open:
          type: string
          maxLength: 4096
          description: Workspace-relative file to open. Supported only by the VS Code
            surface.
    JobPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Job'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    Job:
      type: object
      properties:
        id:
          type: string
          pattern: ^job-[0-9a-z]{16}$
        notebook_id:
          type: string
        project_id:
          type: string
        name:
          type: string
        enabled:
          type: boolean
        schedule:
          $ref: '#/components/schemas/JobSchedule'
        parameters:
          $ref: '#/components/schemas/JobParameters'
        retry:
          $ref: '#/components/schemas/JobRetryPolicy'
        timeout_seconds:
          type: integer
        concurrency_policy:
          type: string
          enum:
            - forbid
            - allow
            - unknown
          description: 'Known values: forbid, allow. Unrecognized values normalize to
            unknown.'
          example: forbid
        notifications:
          $ref: '#/components/schemas/JobNotifications'
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - notebook_id
        - project_id
        - name
        - enabled
        - concurrency_policy
        - created_by
        - created_at
        - updated_at
    JobSchedule:
      type: object
      properties:
        cron:
          type: string
          minLength: 1
          maxLength: 100
          description: Five-field cron expression (minute hour day-of-month month
            day-of-week).
          example: 0 6 * * 1-5
        timezone:
          type: string
          minLength: 1
          maxLength: 64
          description: IANA time zone the cron fields are evaluated in.
          example: Europe/Berlin
      required:
        - cron
        - timezone
    JobParameters:
      type: object
      additionalProperties:
        type: string
        maxLength: 4096
      maxProperties: 32
      propertyNames: &a3
        type: string
        pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$
      description: String parameters passed to the notebook as `--key value` after
        `--`, readable via `mo.cli_args()`. Parameters are visible to every
        project member who can read the job or its run history; do not store
        secrets here.
      example:
        region: eu-west-1
    JobRetryPolicy:
      type: object
      properties:
        max_retries:
          type: integer
          minimum: 0
          maximum: 5
        backoff_seconds:
          type: integer
          minimum: 0
          maximum: 3600
          default: 60
      required:
        - max_retries
    JobNotifications:
      type: object
      properties:
        on:
          type: array
          items:
            type: string
            enum:
              - failure
              - success
          minItems: 1
          uniqueItems: true
      required:
        - on
      description: Deliver `job.run.failed` / `job.run.succeeded` project alerts for
        this job. Failures notify once retries are exhausted.
    JobCreateBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
          example: Nightly refresh
        enabled:
          type: boolean
          default: true
        schedule:
          $ref: '#/components/schemas/JobSchedule'
        parameters:
          $ref: '#/components/schemas/JobParameters'
        retry:
          $ref: '#/components/schemas/JobRetryPolicy'
        timeout_seconds:
          type: integer
          minimum: 60
          description: Run deadline in seconds; capped by
            MARIMOHUB_JOBS_MAX_TIMEOUT_SECONDS.
          example: 1800
        concurrency_policy:
          type: string
          enum:
            - forbid
            - allow
          default: forbid
        notifications:
          $ref: '#/components/schemas/JobNotifications'
      required:
        - name
      additionalProperties: false
    JobUpdateBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        enabled:
          type: boolean
        schedule:
          type:
            - object
            - 'null'
          properties:
            cron:
              type: string
              minLength: 1
              maxLength: 100
              description: Five-field cron expression (minute hour day-of-month month
                day-of-week).
              example: 0 6 * * 1-5
            timezone:
              type: string
              minLength: 1
              maxLength: 64
              description: IANA time zone the cron fields are evaluated in.
              example: Europe/Berlin
          required:
            - cron
            - timezone
        parameters:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
            maxLength: 4096
          maxProperties: 32
          propertyNames: *a3
        retry:
          type:
            - object
            - 'null'
          properties:
            max_retries:
              type: integer
              minimum: 0
              maximum: 5
            backoff_seconds:
              type: integer
              minimum: 0
              maximum: 3600
              default: 60
          required:
            - max_retries
        timeout_seconds:
          type:
            - integer
            - 'null'
          minimum: 60
          description: Run deadline in seconds; capped by
            MARIMOHUB_JOBS_MAX_TIMEOUT_SECONDS.
          example: 1800
        concurrency_policy:
          type: string
          enum:
            - forbid
            - allow
        notifications:
          type:
            - object
            - 'null'
          properties:
            on:
              type: array
              items:
                type: string
                enum:
                  - failure
                  - success
              minItems: 1
              uniqueItems: true
          required:
            - on
      additionalProperties: false
    JobRun:
      type: object
      properties:
        run_id:
          type: string
          pattern: ^run_[0-9A-HJKMNP-TV-Z]{26}$
        job_id:
          type: string
        notebook_id:
          type: string
        project_id:
          type: string
        status:
          type: string
          enum:
            - queued
            - provisioning
            - running
            - succeeded
            - failed
            - timed_out
            - cancelled
            - skipped
            - unknown
          description: queued/provisioning/running are active.
            succeeded/failed/timed_out/cancelled/skipped are terminal; terminal
            records are never rewritten.
          example: queued
        trigger:
          type: string
          enum:
            - schedule
            - manual
            - unknown
          description: 'Known values: schedule, manual. Unrecognized values normalize to
            unknown.'
          example: manual
        triggered_by:
          type: string
        scheduled_for:
          type: string
          format: date-time
        source_version_id:
          type: string
        parameters:
          $ref: '#/components/schemas/JobParameters'
        attempt:
          type: integer
          exclusiveMinimum: 0
          description: One-based attempt number. A failed or timed-out attempt can create
            a new run with attempt + 1 and retry_of set, subject to the job
            retry policy.
        retry_of:
          type: string
        image:
          type: string
        compute_profile:
          type: string
        compute_resources:
          $ref: '#/components/schemas/ComputeResources'
        timeout_seconds:
          type: integer
        queued_at:
          type: string
          format: date-time
        eligible_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          description: Present after the run enters running.
        finished_at:
          type: string
          format: date-time
          description: Present on terminal runs.
        deadline_at:
          type: string
          format: date-time
          description: Present after provisioning establishes the watchdog deadline.
        exit_code:
          type: integer
          description: Process exit code when the export command reported one.
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
          description: Sanitized failure detail, present on failed, timed-out, or skipped
            runs.
        output:
          type: object
          properties:
            html_bytes:
              type: integer
              minimum: 0
            logs_bytes:
              type: integer
              minimum: 0
          required:
            - html_bytes
          description: Captured write-once artifacts, present after execution.
        cancelled_by:
          type: string
      required:
        - run_id
        - job_id
        - notebook_id
        - project_id
        - status
        - trigger
        - attempt
        - timeout_seconds
        - queued_at
    JobRunTriggerBody:
      type: object
      properties:
        parameters:
          $ref: '#/components/schemas/JobParameters'
      additionalProperties: false
    JobRunPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/JobRun'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    IntegrationKind:
      type: object
      properties:
        kind:
          type: string
          minLength: 1
          example: postgres
        title:
          type: string
        description:
          type: string
        category:
          type: string
          enum:
            - database
            - catalog
            - engine
            - storage
            - package_registry
            - other
        brand:
          type: object
          properties:
            icon:
              type: string
              minLength: 1
              example: postgresql
            color:
              type: string
              pattern: ^#[0-9A-Fa-f]{6}$
              example: '#4169E1'
          required:
            - color
        schema_version:
          type: integer
          exclusiveMinimum: 0
        json_schema:
          type: object
          additionalProperties: {}
        ui_hints:
          type: object
          additionalProperties:
            type: object
            properties:
              widget:
                type: string
                enum:
                  - text
                  - password
                  - textarea
                  - select
                  - toggle
                  - number
                  - kv-pairs
              placeholder:
                type: string
              file_accept:
                type: array
                items:
                  type: string
              group:
                type: string
              order:
                type: number
              advanced:
                type: boolean
              docs_url:
                type: string
        supports_test:
          type: boolean
        supports_browse:
          type: boolean
        browse_surfaces:
          type: array
          items:
            type: string
            enum:
              - tables
              - objects
              - unknown
            description: 'Known values: tables, objects. Unrecognized values normalize to
              unknown.'
            example: tables
        secret_sources:
          type: object
          properties:
            inline:
              type: boolean
            references:
              type: array
              items:
                type: object
                properties:
                  backend:
                    type: string
                    minLength: 1
                    example: aws-sm
                  title:
                    type: string
                    minLength: 1
                    example: AWS Secrets Manager
                  locator_placeholder:
                    type: string
                    minLength: 1
                  locator_help:
                    type: string
                    minLength: 1
                  docs_url:
                    type: string
                    format: uri
                required:
                  - backend
                  - title
                  - locator_placeholder
                  - locator_help
          required:
            - inline
            - references
        requirements:
          type: array
          items:
            type: string
        shared_environment:
          type: object
          properties:
            group:
              type: string
              minLength: 1
              example: google
            title:
              type: string
              minLength: 1
              example: Google Cloud
            variables:
              type: string
              minLength: 1
          required:
            - group
            - title
            - variables
      required:
        - kind
        - title
        - description
        - category
        - brand
        - schema_version
        - json_schema
        - ui_hints
        - supports_test
        - supports_browse
        - browse_surfaces
        - secret_sources
        - requirements
    IntegrationPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/IntegrationEntry'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    IntegrationEntry:
      type: object
      properties:
        id:
          type: string
          pattern: ^intg-[0-9a-z]{16}$
        kind:
          type: string
          minLength: 1
        name:
          type: string
          pattern: ^[a-z][a-z0-9-]{0,31}$
        enabled:
          type: boolean
        current_version:
          type: integer
          exclusiveMinimum: 0
        created_by:
          type: string
          minLength: 1
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        scope:
          type: string
          enum:
            - project
            - org
        shadowed:
          type: boolean
        ambient_env:
          type: boolean
      required:
        - id
        - kind
        - name
        - enabled
        - current_version
        - created_by
        - created_at
        - updated_at
        - scope
    IntegrationDetail:
      allOf:
        - $ref: '#/components/schemas/IntegrationEntry'
        - type: object
          properties:
            config:
              type: object
              additionalProperties: {}
            change_note:
              type: string
          required:
            - config
    IntegrationVersionPage:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/IntegrationVersion'
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    IntegrationVersion:
      type: object
      properties:
        version:
          type: integer
          exclusiveMinimum: 0
        kind_schema_version:
          type: integer
          exclusiveMinimum: 0
        created_by:
          type: string
          minLength: 1
        created_at:
          type: string
          format: date-time
        change_note:
          type: string
      required:
        - version
        - kind_schema_version
        - created_by
        - created_at
    IntegrationCopyRequest:
      type: object
      properties:
        source_project_id:
          type: string
          pattern: ^proj-[0-9a-z]{16}$
          example: proj-7h2k9qm4xz7rp3w8
        source_integration_id:
          type: string
          pattern: ^intg-[0-9a-z]{16}$
          example: intg-7h2k9qm4xz7rp3w8
        name:
          type: string
          pattern: ^[a-z][a-z0-9-]{0,31}$
      required:
        - source_project_id
        - source_integration_id
      additionalProperties: false
    IntegrationTestResult:
      type: object
      properties:
        ok:
          type: boolean
        latency_ms:
          type: number
          minimum: 0
        details:
          type: string
      required:
        - ok
    IntegrationTestRequest:
      oneOf:
        - type: object
          properties:
            source:
              type: string
              enum:
                - draft
            kind:
              type: string
              minLength: 1
            config:
              type: object
              additionalProperties: {}
            id:
              type: string
              pattern: ^intg-[0-9a-z]{16}$
          required:
            - source
            - kind
            - config
          additionalProperties: false
        - type: object
          properties:
            source:
              type: string
              enum:
                - stored
            id:
              type: string
              pattern: ^intg-[0-9a-z]{16}$
          required:
            - source
            - id
          additionalProperties: false
    IntegrationQueryReadinessCheck:
      type: object
      properties:
        id:
          type: string
          minLength: 1
        label:
          type: string
          minLength: 1
        ready:
          type: boolean
        field:
          type: string
        reason:
          type: string
          minLength: 1
      required:
        - id
        - label
        - ready
        - field
        - reason
    IntegrationQueryReadinessRequest:
      type: object
      properties:
        kind:
          type: string
          minLength: 1
        config:
          type: object
          additionalProperties: {}
      required:
        - kind
        - config
      additionalProperties: false
    IntegrationBrowseCapability:
      type: object
      properties:
        surfaces:
          type: object
          properties:
            tables:
              type: object
              properties:
                available:
                  type: boolean
                preview:
                  type: boolean
                reason:
                  type: string
              required:
                - available
                - preview
            objects:
              type: object
              properties:
                provider:
                  type: string
                  enum:
                    - s3
                    - gcs
                    - azure_blob
                    - unknown
                  description: 'Known values: s3, gcs, azure_blob. Unrecognized values normalize
                    to unknown.'
                  example: s3
                root_kind:
                  type: string
                  enum:
                    - bucket
                    - container
                    - unknown
                  description: 'Known values: bucket, container. Unrecognized values normalize to
                    unknown.'
                  example: bucket
                uri_scheme:
                  type: string
                  enum:
                    - s3
                    - gs
                    - az
                    - unknown
                  description: 'Known values: s3, gs, az. Unrecognized values normalize to
                    unknown.'
                  example: s3
                available:
                  type: boolean
                preview:
                  type: boolean
                download:
                  type: boolean
                write:
                  type: boolean
                search:
                  type: string
                  enum:
                    - none
                    - bounded-key-name
                    - unknown
                  description: 'Known values: none, bounded-key-name. Unrecognized values
                    normalize to unknown.'
                  example: bounded-key-name
                versions:
                  type: boolean
                preview_formats:
                  type: array
                  items:
                    type: string
                reason:
                  type: string
              required:
                - provider
                - root_kind
                - uri_scheme
                - available
                - preview
                - download
                - search
                - versions
                - preview_formats
            query:
              type: object
              properties:
                available:
                  type: boolean
                dialect:
                  type: string
                  enum:
                    - duckdb
                    - postgresql
                    - unknown
                  description: 'Known values: duckdb, postgresql. Unrecognized values normalize to
                    unknown.'
                  example: duckdb
                reason:
                  type: string
              required:
                - available
                - dialect
      required:
        - surfaces
    IntegrationBrowseNamespacePage:
      type: object
      properties:
        items:
          type: array
          items:
            type: array
            items:
              type: string
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    IntegrationBrowseTablePage:
      type: object
      properties:
        items:
          type: array
          items:
            type: string
        next_cursor:
          type:
            - string
            - 'null'
      required:
        - items
        - next_cursor
    IntegrationTableSchema:
      type: object
      properties:
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
              nullable:
                type: boolean
              comment:
                type: string
            required:
              - name
              - type
              - nullable
        partitioning:
          type: array
          items:
            type: string
        snippet:
          type: string
        location:
          type: string
        format_version:
          type: integer
        current_snapshot:
          type: object
          properties:
            committed_at:
              type: string
              format: date-time
            total_records:
              type: number
            total_data_size_bytes:
              type: number
      required:
        - columns
    IntegrationTablePreview:
      type: object
      properties:
        columns:
          type: array
          items:
            type: string
        rows:
          type: array
          items:
            type: array
            items: {}
      required:
        - columns
        - rows
    IntegrationDataQueryResult:
      type: object
      properties:
        columns:
          type: array
          items:
            type: string
        rows:
          type: array
          items:
            type: array
            items: {}
        truncated:
          type: boolean
        execution_ms:
          type: integer
          minimum: 0
      required:
        - columns
        - rows
        - truncated
        - execution_ms
    IntegrationQuerySchema:
      type: object
      properties:
        tables:
          type: array
          items:
            type: object
            properties:
              namespace:
                type: array
                items:
                  type: string
              name:
                type: string
              columns:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    type:
                      type: string
                    nullable:
                      type: boolean
                  required:
                    - name
                    - type
                    - nullable
            required:
              - namespace
              - name
              - columns
        truncated:
          type: object
          properties:
            tables:
              type: boolean
            columns:
              type: boolean
            bytes:
              type: boolean
          required:
            - tables
            - columns
            - bytes
        counts:
          type: object
          properties:
            tables:
              type: integer
              minimum: 0
            discovered_tables:
              type: integer
              minimum: 0
            columns:
              type: integer
              minimum: 0
            discovery_complete:
              type: boolean
          required:
            - tables
            - discovered_tables
            - columns
            - discovery_complete
      required:
        - tables
        - truncated
        - counts
    IntegrationObjectBucket:
      type: object
      properties:
        name:
          type: string
        created_at:
          type: string
          format: date-time
        configured:
          type: boolean
      required:
        - name
        - configured
    IntegrationObjectEntry:
      type: object
      properties:
        kind:
          type: string
          enum:
            - prefix
            - object
        name:
          type: string
        key:
          type: string
        size:
          type: number
          minimum: 0
        last_modified:
          type: string
          format: date-time
        etag:
          type: string
        storage_class:
          type: string
      required:
        - kind
        - name
        - key
    IntegrationObjectDetail:
      type: object
      properties:
        bucket:
          type: string
        key:
          type: string
        version_id:
          type: string
        size:
          type: number
          minimum: 0
        last_modified:
          type: string
          format: date-time
        etag:
          type: string
        storage_class:
          type: string
        content_type:
          type: string
        content_encoding:
          type: string
        cache_control:
          type: string
        checksums:
          type: array
          items:
            type: object
            properties:
              algorithm:
                type: string
              value:
                type: string
            required:
              - algorithm
              - value
        metadata:
          type: object
          additionalProperties:
            type: string
        tags:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
            required:
              - key
              - value
        tags_available:
          type: boolean
        snippet:
          type: string
      required:
        - bucket
        - key
        - size
        - checksums
        - metadata
        - tags_available
    IntegrationObjectVersion:
      type: object
      properties:
        bucket:
          type: string
        key:
          type: string
        version_id:
          type: string
        kind:
          type: string
          enum:
            - version
            - delete-marker
        is_latest:
          type: boolean
        last_modified:
          type: string
          format: date-time
        size:
          type: number
          minimum: 0
        etag:
          type: string
        storage_class:
          type: string
        owner:
          type: object
          properties:
            id:
              type: string
            display_name:
              type: string
      required:
        - bucket
        - key
        - kind
        - is_latest
    IntegrationObjectPreview:
      oneOf:
        - type: object
          properties:
            kind:
              type: string
              enum:
                - tabular
            format:
              type: string
              enum:
                - table
                - csv
                - tsv
                - json
                - jsonl
                - parquet
                - unknown
              description: 'Known values: table, csv, tsv, json, jsonl, parquet. Unrecognized
                values normalize to unknown.'
              example: csv
            columns:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  type:
                    type: string
                required:
                  - name
            rows:
              type: array
              items:
                type: array
                items: {}
            truncated:
              type: boolean
            bytes_read:
              type: number
              minimum: 0
            total_bytes:
              type: number
              minimum: 0
            warnings:
              type: array
              items:
                type: string
          required:
            - kind
            - format
            - columns
            - rows
            - truncated
            - warnings
        - type: object
          properties:
            kind:
              type: string
              enum:
                - text
            format:
              type: string
              enum:
                - text
                - markdown
                - code
                - log
                - json
                - unknown
              description: 'Known values: text, markdown, code, log, json. Unrecognized values
                normalize to unknown.'
              example: text
            text:
              type: string
            truncated:
              type: boolean
            bytes_read:
              type: number
              minimum: 0
            total_bytes:
              type: number
              minimum: 0
            warnings:
              type: array
              items:
                type: string
          required:
            - kind
            - format
            - text
            - truncated
            - bytes_read
            - total_bytes
            - warnings
        - type: object
          properties:
            kind:
              type: string
              enum:
                - image
            format:
              type: string
              enum:
                - png
                - jpeg
                - gif
                - webp
                - unknown
              description: 'Known values: png, jpeg, gif, webp. Unrecognized values normalize
                to unknown.'
              example: png
            content_url:
              type: string
            width:
              type: integer
              exclusiveMinimum: 0
            height:
              type: integer
              exclusiveMinimum: 0
            total_bytes:
              type: number
              minimum: 0
            warnings:
              type: array
              items:
                type: string
          required:
            - kind
            - format
            - content_url
            - total_bytes
            - warnings
        - type: object
          properties:
            kind:
              type: string
              enum:
                - unsupported
            reason:
              type: string
            detected_type:
              type: string
            total_bytes:
              type: number
              minimum: 0
          required:
            - kind
            - reason
            - total_bytes
    User:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
        picture_url:
          type:
            - string
            - 'null'
          format: uri
      required:
        - id
        - email
        - name
    ApiTokenCreated:
      allOf:
        - $ref: '#/components/schemas/ApiToken'
        - type: object
          properties:
            token:
              type: string
          required:
            - token
    ApiToken:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
        grant:
          type: object
          properties:
            actions:
              anyOf:
                - type: string
                  enum:
                    - '*'
                - type: array
                  items:
                    type: string
                    enum:
                      - support.request
                      - project.create
                      - admin.access
                      - org-integration.manage
                      - audit.global.read
                      - directory.search
                      - app.read
                      - project.read
                      - project.update
                      - project.delete
                      - project.members.manage
                      - project.events.read
                      - project.alerts.manage
                      - notebook.write
                      - notebook.manage
                      - deep-link.manage
                      - preview.manage
                      - integration.read
                      - integration.use
                      - integration.write
                      - integration.manage
                      - change-request.publish
                      - working-branch.write
                      - security-labels.raise
                      - security-labels.lower
                      - session.attach
                      - session.stop
                      - session.surface
                      - session.proxy
                      - session.start
                  uniqueItems: true
            projects:
              anyOf:
                - type: string
                  enum:
                    - '*'
                - type: array
                  items:
                    type: string
                    pattern: ^proj-[0-9a-z]{16}$
                  minItems: 1
                  maxItems: 100
                  uniqueItems: true
          required:
            - actions
            - projects
          additionalProperties: false
        mcp_resource:
          type: string
          format: uri
      required:
        - id
        - name
        - created_at
  parameters: {}
paths:
  /api/v1/theme:
    get:
      operationId: theme
      tags:
        - System
      summary: Get public deployment branding
      security: []
      responses:
        '200':
          description: Deployment branding, available before sign-in
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      nav_links:
                        type: array
                        items:
                          type: object
                          properties:
                            label:
                              type: string
                              minLength: 1
                              maxLength: 40
                            href:
                              type: string
                            placement:
                              type: string
                              enum:
                                - header
                                - help
                            external:
                              type: boolean
                            roles:
                              type: array
                              items:
                                type: string
                                enum:
                                  - admin
                                  - manager
                                  - editor
                                  - viewer
                                  - app-user
                          required:
                            - label
                            - href
                        maxItems: 12
                      docs_url:
                        type: string
                      support_url:
                        type: string
                      announcement:
                        type: object
                        properties:
                          id:
                            type: string
                            minLength: 1
                            maxLength: 100
                          text:
                            type: string
                            minLength: 1
                            maxLength: 280
                          href:
                            type: string
                          level:
                            type: string
                            enum:
                              - info
                              - warning
                          dismissible:
                            type: boolean
                        required:
                          - id
                          - text
                      notebook_css:
                        type: string
                      notebook_palette:
                        type: string
                        enum:
                          - off
                          - accents
                          - full
                        default: off
                      color_mode:
                        type: string
                        enum:
                          - user
                          - light
                          - dark
                        default: user
                      name:
                        type: string
                        minLength: 1
                      favicon:
                        type:
                          - string
                          - 'null'
                      logo:
                        type:
                          - string
                          - 'null'
                      logo_dark:
                        type:
                          - string
                          - 'null'
                      primary_color:
                        type:
                          - string
                          - 'null'
                        pattern: ^#(?:[\da-fA-F]{3}|[\da-fA-F]{6})$
                      secondary_color:
                        type:
                          - string
                          - 'null'
                        pattern: ^#(?:[\da-fA-F]{3}|[\da-fA-F]{6})$
                      pwa_icon_192:
                        type:
                          - string
                          - 'null'
                        default: null
                      pwa_icon_512:
                        type:
                          - string
                          - 'null'
                        default: null
                      apple_touch_icon:
                        type:
                          - string
                          - 'null'
                        default: null
                    required:
                      - name
                      - favicon
                      - logo
                      - logo_dark
                      - primary_color
                      - secondary_color
                required:
                  - success
                  - data
  /api/cli/v1/device-authorizations:
    post:
      operationId: auth.cli.device.request
      x-cli-hidden: true
      tags:
        - Auth
      summary: Start a CLI device login
      description: Returns a high-entropy device code that is bound to the PKCE
        challenge. Also returns a short code for browser approval.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code_challenge:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{43}$
                  description: Base64url-encoded SHA-256 PKCE challenge generated by the CLI.
              required:
                - code_challenge
              additionalProperties: false
      responses:
        '200':
          description: Device and user verification codes
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      device_code:
                        type: string
                      user_code:
                        type: string
                      verification_uri:
                        type: string
                        format: uri
                      verification_uri_complete:
                        type: string
                        format: uri
                      expires_in:
                        type: integer
                      interval:
                        type: integer
                    required:
                      - device_code
                      - user_code
                      - verification_uri
                      - verification_uri_complete
                      - expires_in
                      - interval
                required:
                  - success
                  - data
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/cli/v1/device-authorizations/scoped:
    post:
      operationId: auth.cli.device.requestScoped
      x-cli-hidden: true
      tags:
        - Auth
      summary: Start a scoped CLI device login
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code_challenge:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{43}$
                  description: Base64url-encoded SHA-256 PKCE challenge generated by the CLI.
                grant:
                  type: object
                  properties:
                    actions:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            enum:
                              - support.request
                              - project.create
                              - admin.access
                              - org-integration.manage
                              - audit.global.read
                              - directory.search
                              - app.read
                              - project.read
                              - project.update
                              - project.delete
                              - project.members.manage
                              - project.events.read
                              - project.alerts.manage
                              - notebook.write
                              - notebook.manage
                              - deep-link.manage
                              - preview.manage
                              - integration.read
                              - integration.use
                              - integration.write
                              - integration.manage
                              - change-request.publish
                              - working-branch.write
                              - security-labels.raise
                              - security-labels.lower
                              - session.attach
                              - session.stop
                              - session.surface
                              - session.proxy
                              - session.start
                          uniqueItems: true
                    projects:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            pattern: ^proj-[0-9a-z]{16}$
                          minItems: 1
                          maxItems: 100
                          uniqueItems: true
                  required:
                    - actions
                    - projects
                  additionalProperties: false
              required:
                - code_challenge
                - grant
              additionalProperties: false
      responses:
        '200':
          description: Device and user verification codes
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      device_code:
                        type: string
                      user_code:
                        type: string
                      verification_uri:
                        type: string
                        format: uri
                      verification_uri_complete:
                        type: string
                        format: uri
                      expires_in:
                        type: integer
                      interval:
                        type: integer
                    required:
                      - device_code
                      - user_code
                      - verification_uri
                      - verification_uri_complete
                      - expires_in
                      - interval
                required:
                  - success
                  - data
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/cli/v1/device-token:
    post:
      operationId: auth.cli.device.poll
      x-cli-hidden: true
      tags:
        - Auth
      summary: Poll a CLI device login
      description: Returns 202 while browser approval is pending. Returns a new
        personal access token once after approval.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                device_code:
                  type: string
                  minLength: 1
                  maxLength: 100
                code_verifier:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{43,128}$
              required:
                - device_code
                - code_verifier
              additionalProperties: false
      responses:
        '200':
          description: The new personal access token
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                    required:
                      - token
                required:
                  - success
                  - data
        '202':
          description: Browser approval is still pending
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        enum:
                          - authorization_pending
                    required:
                      - status
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/cli/v1/token:
    post:
      operationId: auth.cli.exchange
      x-cli-hidden: true
      tags:
        - Auth
      summary: Exchange a CLI authorization code
      description: Public PKCE exchange for loopback login. The code is short-lived
        and single-use. Exchange also requires the verifier held by the CLI.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  minLength: 1
                  maxLength: 100
                code_verifier:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{43,128}$
              required:
                - code
                - code_verifier
              additionalProperties: false
      responses:
        '200':
          description: The new personal access token
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                    required:
                      - token
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me:
    get:
      operationId: me
      tags:
        - Auth
      summary: Get current user info
      responses:
        '200':
          description: Current user information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Me'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/version:
    get:
      operationId: version
      tags:
        - System
      summary: Get the deployment version
      description: Just the version string. The rest of the build/runtime identity
        (image, replica, backends, …) is super-admin material on `GET
        /api/v1/admin/config`.
      responses:
        '200':
          description: Deployment version information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/DeploymentInfo'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/capabilities:
    get:
      operationId: capabilities
      tags:
        - System
      summary: Get deployment capability flags
      responses:
        '200':
          description: Deployment capability flags
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Capabilities'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/support/diagnostics:
    post:
      operationId: support.diagnostics.preview
      x-cli-hidden: true
      tags:
        - System
      summary: Preview support diagnostics for the signed-in user
      requestBody:
        description: Page and optional session identifiers
        content:
          application/json:
            schema:
              type: object
              properties:
                page_url:
                  type: string
                  maxLength: 2048
                client:
                  type: object
                  properties:
                    user_agent:
                      type: string
                      maxLength: 512
                    viewport:
                      type: object
                      properties:
                        width:
                          type: integer
                          minimum: 0
                          maximum: 100000
                        height:
                          type: integer
                          minimum: 0
                          maximum: 100000
                      required:
                        - width
                        - height
                    error:
                      type: string
                      maxLength: 1000
                  required:
                    - user_agent
                    - viewport
                session:
                  type: object
                  properties:
                    project_id:
                      type: string
                    notebook_id:
                      type: string
                    id:
                      type: string
                  required:
                    - project_id
                    - notebook_id
                    - id
              required:
                - page_url
                - client
      responses:
        '200':
          description: Support diagnostics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      page_url:
                        type: string
                        maxLength: 2048
                      client:
                        type: object
                        properties:
                          user_agent:
                            type: string
                            maxLength: 512
                          viewport:
                            type: object
                            properties:
                              width:
                                type: integer
                                minimum: 0
                                maximum: 100000
                              height:
                                type: integer
                                minimum: 0
                                maximum: 100000
                            required:
                              - width
                              - height
                          error:
                            type: string
                            maxLength: 1000
                        required:
                          - user_agent
                          - viewport
                      session:
                        type: object
                        properties:
                          project_id:
                            type: string
                          notebook_id:
                            type: string
                          id:
                            type: string
                          source_version_id:
                            type: string
                          sandbox_id:
                            type: string
                          runtime:
                            type: object
                            properties:
                              python_version:
                                type: string
                              marimo_version:
                                type: string
                          compute_profile:
                            type: string
                          error:
                            type: object
                            properties:
                              code:
                                type: string
                              message:
                                type: string
                            required:
                              - code
                              - message
                        required:
                          - project_id
                          - notebook_id
                          - id
                      reporter:
                        type: object
                        properties:
                          id:
                            type: string
                          email:
                            type: string
                        required:
                          - id
                          - email
                      hub_version:
                        type: string
                      timestamp:
                        type: string
                    required:
                      - page_url
                      - client
                      - reporter
                      - hub_version
                      - timestamp
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/support/requests:
    post:
      operationId: support.requests.create
      x-cli-hidden: true
      tags:
        - System
      summary: Send a support request to the deployment notifier
      requestBody:
        description: Report and page context
        content:
          application/json:
            schema:
              type: object
              properties:
                page_url:
                  type: string
                  maxLength: 2048
                client:
                  type: object
                  properties:
                    user_agent:
                      type: string
                      maxLength: 512
                    viewport:
                      type: object
                      properties:
                        width:
                          type: integer
                          minimum: 0
                          maximum: 100000
                        height:
                          type: integer
                          minimum: 0
                          maximum: 100000
                      required:
                        - width
                        - height
                    error:
                      type: string
                      maxLength: 1000
                  required:
                    - user_agent
                    - viewport
                session:
                  type: object
                  properties:
                    project_id:
                      type: string
                    notebook_id:
                      type: string
                    id:
                      type: string
                  required:
                    - project_id
                    - notebook_id
                    - id
                message:
                  type: string
                  minLength: 1
                  maxLength: 2000
              required:
                - page_url
                - client
                - message
      responses:
        '200':
          description: Support request delivered
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      request_id:
                        type: string
                      delivery:
                        type: string
                        enum:
                          - delivered
                          - partial
                    required:
                      - request_id
                      - delivery
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects:
    get:
      operationId: projects.list
      tags:
        - Projects
      summary: List all projects
      description: When paging a filtered list, send the same filters with each cursor.
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            description: Only include projects the caller can manage notebooks in.
          required: false
          description: Only include projects the caller can manage notebooks in.
          name: managed_only
          in: query
        - schema:
            type: string
            maxLength: 256
            pattern: ^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*)*(?![\s\S])
            description: 'Path-tag namespace. Matches whole path segments: `research`
              matches `research` and `research/vision`, but not `researchx`.
              Segments are separated by `/`. Each segment must start with a
              lowercase letter or digit, followed by lowercase letters, digits,
              `.`, `_`, or `-`. An empty value applies no filter.'
            example: research/vision
          required: false
          description: 'Path-tag namespace. Matches whole path segments: `research`
            matches `research` and `research/vision`, but not `researchx`.
            Segments are separated by `/`. Each segment must start with a
            lowercase letter or digit, followed by lowercase letters, digits,
            `.`, `_`, or `-`. An empty value applies no filter.'
          name: tag_namespace
          in: query
        - schema:
            type: string
            enum:
              - active
              - deleted
            description: Project status to match. Deleted projects are excluded when
              omitted.
            example: active
          required: false
          description: Project status to match. Deleted projects are excluded when omitted.
          name: status
          in: query
        - schema:
            type: string
            description: Exact tag to match.
            example: analytics
          required: false
          description: Exact tag to match.
          name: tag
          in: query
        - schema:
            type: string
            description: Case-insensitive substring to match against the name or title and
              description.
            example: revenue
          required: false
          description: Case-insensitive substring to match against the name or title and
            description.
          name: q
          in: query
      responses:
        '200':
          description: List of projects with notebook summaries, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/ProjectPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: projects.create
      tags:
        - Projects
      summary: Create a project
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: false
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  example: Data Science
                description:
                  type: string
                  example: Exploratory analysis notebooks
                tags:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 256
                  maxItems: 50
                  example:
                    - analytics
                federation:
                  $ref: '#/components/schemas/ProjectFederationInput'
              required:
                - name
                - description
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Project'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}:
    get:
      operationId: projects.get
      tags:
        - Projects
      summary: Get a project
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      responses:
        '200':
          description: Project details
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Project'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: projects.update
      tags:
        - Projects
      summary: Update a project
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                default_role:
                  type: string
                  enum:
                    - inherit
                    - none
                    - manager
                    - editor
                    - viewer
                    - app-user
                  description: Non-member access. inherit uses deployment and OIDC defaults. none
                    grants no default access. Requires manager or higher.
                name:
                  type: string
                  minLength: 1
                  example: ML Pipeline
                description:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 256
                  maxItems: 50
                federation:
                  anyOf:
                    - $ref: '#/components/schemas/ProjectFederationInput'
                    - type: 'null'
                  description: '`null` clears the project override so the deployment default
                    applies.'
      responses:
        '200':
          description: Project updated
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Project'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: projects.delete
      tags:
        - Projects
      summary: Delete a project
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      responses:
        '200':
          description: Project deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/security-labels:
    put:
      operationId: projects.securityLabels.set
      tags:
        - Projects
      summary: Set project security labels
      description: Sets the project classification and required compartments. Requires
        super-admin standing — no project role grants label authority — and the
        deployment must have resource security configured. Labels only add
        restrictions on top of role checks.
      security: &a4
        - cookieAuth: []
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityLabelsInput'
      responses:
        '200':
          description: Security labels updated
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Project'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: projects.securityLabels.clear
      tags:
        - Projects
      summary: Remove project security labels
      security: *a4
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      responses:
        '200':
          description: Security labels removed
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Project'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/members:
    get:
      operationId: projects.members.list
      tags:
        - Projects
      summary: List project members
      description: Pending email invites are visible only to project managers (plus
        the invitee themself); other callers see user and group rows.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      responses:
        '200':
          description: Project members
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMember'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: projects.members.add
      tags:
        - Projects
      summary: Add a project member
      description: Add a member by user id or email. A known email resolves to its
        user id; an unknown email becomes a pending invite that grants access
        when that person first signs in.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  minLength: 1
                  example: user_01HXY00000000000000000000
                email:
                  type: string
                  format: email
                  example: teammate@example.com
                role:
                  $ref: '#/components/schemas/AssignableRole'
              required:
                - role
      responses:
        '201':
          description: Member added
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Project'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/group-members:
    post:
      operationId: projects.members.groups.add
      tags:
        - Projects
      summary: Add a project group member
      description: Grant an exact IdP group id a project role. Groups cannot hold
        admin. Requires a deployment whose sessions carry IdP groups (see
        `project_groups` in capabilities).
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  type: string
                  example: /teams/data-science
                role:
                  $ref: '#/components/schemas/AssignableRole'
              required:
                - group
                - role
      responses:
        '201':
          description: Group added
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Project'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: projects.members.groups.update
      tags:
        - Projects
      summary: Change a group's project role
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            example: /teams/data-science
          required: true
          name: group
          in: query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  allOf:
                    - $ref: '#/components/schemas/AssignableRole'
                    - example: manager
              required:
                - role
      responses:
        '200':
          description: Group role updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Project'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: projects.members.groups.remove
      tags:
        - Projects
      summary: Remove a project group member
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            example: /teams/data-science
          required: true
          name: group
          in: query
      responses:
        '200':
          description: Group removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/members/{uid}:
    put:
      operationId: projects.members.update
      tags:
        - Projects
      summary: Change a member's role
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            minLength: 1
            example: user_01HXY00000000000000000000
          required: true
          name: uid
          in: path
          description: The member's user id, or the (URL-encoded) email of a pending invite
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  allOf:
                    - $ref: '#/components/schemas/AssignableRole'
                    - example: manager
              required:
                - role
      responses:
        '200':
          description: Member role updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Project'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: projects.members.remove
      tags:
        - Projects
      summary: Remove a project member
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            minLength: 1
            example: user_01HXY00000000000000000000
          required: true
          name: uid
          in: path
          description: The member's user id, or the (URL-encoded) email of a pending invite
      responses:
        '200':
          description: Member removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/alert-destinations:
    get:
      operationId: alerts.destinations.list
      tags:
        - Alerts
      summary: List project alert destinations
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      responses:
        '200':
          description: Project alert destinations with secret material redacted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/ProjectAlertDestinationPage'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: alerts.destinations.create
      tags:
        - Alerts
      summary: Create a project alert destination
      description: New destinations subscribe to all 14 project alert kinds when kinds
        is omitted. They remain disabled until a successful test.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 100
                    kinds:
                      type: array
                      items:
                        type: string
                        enum:
                          - member.invited
                          - member.added
                          - member.group_added
                          - member.role_changed
                          - member.removed
                          - session.takeover
                          - notebook.deleted
                          - project.deleted
                          - project.default_access_changed
                          - app.start_failed
                          - app.unavailable
                          - sync.failed
                          - job.run.failed
                          - job.run.succeeded
                      minItems: 1
                    type:
                      type: string
                      enum:
                        - slack
                    webhook_url:
                      type: string
                      format: uri
                  required:
                    - name
                    - type
                    - webhook_url
                  additionalProperties: false
                - type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 100
                    kinds:
                      type: array
                      items:
                        type: string
                        enum:
                          - member.invited
                          - member.added
                          - member.group_added
                          - member.role_changed
                          - member.removed
                          - session.takeover
                          - notebook.deleted
                          - project.deleted
                          - project.default_access_changed
                          - app.start_failed
                          - app.unavailable
                          - sync.failed
                          - job.run.failed
                          - job.run.succeeded
                      minItems: 1
                    type:
                      type: string
                      enum:
                        - webhook
                    url:
                      type: string
                      format: uri
                    signing_secret:
                      type: string
                      minLength: 1
                  required:
                    - name
                    - type
                    - url
                    - signing_secret
                  additionalProperties: false
      responses:
        '201':
          description: Alert destination created
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/ProjectAlertDestination'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/alert-destinations/{aid}:
    patch:
      operationId: alerts.destinations.update
      tags:
        - Alerts
      summary: Update a project alert destination
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^alert-[0-9a-z]{16}$
            example: alert-7h2k9qm4xz7rp3w8
          required: true
          name: aid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 100
                    kinds:
                      type: array
                      items:
                        type: string
                        enum:
                          - member.invited
                          - member.added
                          - member.group_added
                          - member.role_changed
                          - member.removed
                          - session.takeover
                          - notebook.deleted
                          - project.deleted
                          - project.default_access_changed
                          - app.start_failed
                          - app.unavailable
                          - sync.failed
                          - job.run.failed
                          - job.run.succeeded
                      minItems: 1
                    enabled:
                      type: boolean
                    type:
                      type: string
                      enum:
                        - slack
                    webhook_url:
                      type: string
                      format: uri
                  required:
                    - type
                  additionalProperties: false
                - type: object
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 100
                    kinds:
                      type: array
                      items:
                        type: string
                        enum:
                          - member.invited
                          - member.added
                          - member.group_added
                          - member.role_changed
                          - member.removed
                          - session.takeover
                          - notebook.deleted
                          - project.deleted
                          - project.default_access_changed
                          - app.start_failed
                          - app.unavailable
                          - sync.failed
                          - job.run.failed
                          - job.run.succeeded
                      minItems: 1
                    enabled:
                      type: boolean
                    type:
                      type: string
                      enum:
                        - webhook
                    url:
                      type: string
                      format: uri
                    signing_secret:
                      type: string
                      minLength: 1
                  required:
                    - type
                  additionalProperties: false
      responses:
        '200':
          description: Alert destination updated
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/ProjectAlertDestination'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: alerts.destinations.delete
      tags:
        - Alerts
      summary: Delete a project alert destination
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^alert-[0-9a-z]{16}$
            example: alert-7h2k9qm4xz7rp3w8
          required: true
          name: aid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      responses:
        '200':
          description: Alert destination deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/alert-destinations/{aid}/test:
    post:
      operationId: alerts.destinations.test
      tags:
        - Alerts
      summary: Send a test project alert
      description: Sends a real external message. A completed Idempotency-Key replays
        its result. A concurrent, failed, or uncertain delivery returns 409 on
        reuse. A pre-delivery rejection does not consume the key. Use a new key
        to start another test.
      x-cli-destructive: true
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^alert-[0-9a-z]{16}$
            example: alert-7h2k9qm4xz7rp3w8
          required: true
          name: aid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: true
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      responses:
        '200':
          description: Test delivered and destination verified
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/ProjectAlertDestination'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/events:
    get:
      operationId: audit.list
      tags:
        - Audit
      summary: List deployment audit events
      description: Deployment-wide audit trail, newest first. Super-admin only. Date
        ranges are inclusive and limited to 30 UTC days.
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
            example: 2026-07-01
            description: UTC calendar date
          required: false
          description: UTC calendar date
          name: from
          in: query
        - schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
            example: 2026-07-01
            description: UTC calendar date
          required: false
          description: UTC calendar date
          name: to
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: event
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: actor
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: project_id
          in: query
      responses:
        '200':
          description: Deployment audit events, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/AuditLogPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/events:
    get:
      operationId: projects.audit.list
      tags:
        - Projects
      summary: List a project's audit events for one day
      description: 'Catalog mutation audit trail (project/notebook lifecycle,
        membership changes), one UTC day at a time. Manager-only: events may
        record member management and deletions.'
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
            example: 2026-07-01
            description: UTC day (defaults to today)
          required: false
          description: UTC day (defaults to today)
          name: date
          in: query
      responses:
        '200':
          description: The day's audit events for this project, in append order
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuditEvent'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/admin/runtime/projects/{pid}/sessions/{sid}/reclaim:
    post:
      operationId: admin.runtime.reclaim
      tags:
        - Admin
      summary: Reclaim an inactive session sandbox
      description: Super-admin and session authentication required. Saving is best
        effort and only applies when the session still owns its edits. Active
        sessions must be stopped first.
      security: *a4
      parameters:
        - schema:
            type: string
          required: true
          name: pid
          in: path
        - schema:
            type: string
          required: true
          name: sid
          in: path
      requestBody:
        description: Optional; omit to attempt saving before destruction.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                save:
                  type: boolean
                  default: true
      responses:
        '200':
          description: Sandbox reclaimed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      reclaimed:
                        type: boolean
                        enum:
                          - true
                      saved:
                        type: boolean
                        description: Whether a new version was committed from the sandbox before
                          destruction.
                    required:
                      - reclaimed
                      - saved
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/admin/runtime:
    get:
      operationId: admin.runtime.inspect
      tags:
        - Admin
      summary: Inspect app pools and editor sessions
      description: Read-only runtime snapshot, cached for 30 seconds per service
        instance. Super-admin and session authentication required. Recorded
        state is not a live compute health check.
      security: *a4
      responses:
        '200':
          description: Runtime snapshot
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/RuntimeDashboard'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/admin/users:
    get:
      operationId: admin.users.list
      tags:
        - Admin
      summary: List all users in the identity directory
      description: 'Every user who has signed in at least once, name-sorted. Currently
        a single page (`next_cursor` is always null). Super-admin only, and
        session-only: a PAT — even a super admin’s — is rejected with 403.'
      security: *a4
      responses:
        '200':
          description: The user directory, name-sorted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/AdminUserPage'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/admin/users/{id}/suspension:
    put:
      operationId: admin.users.suspend
      x-cli-destructive: true
      tags:
        - Users
        - Admin
      summary: Suspend a user
      description: Blocks the user at authentication time, including personal access
        tokens. Super-admin only and session-only. A super admin cannot suspend
        their own account.
      security: *a4
      parameters:
        - schema:
            type: string
            minLength: 1
            example: user_01HXY00000000000000000000
          required: true
          name: id
          in: path
          description: The user's identity-provider subject id
      responses:
        '200':
          description: The suspended user
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/AdminUser'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: admin.users.unsuspend
      tags:
        - Users
        - Admin
      summary: Reactivate a suspended user
      description: Restores authentication for a known user. Super-admin only and
        session-only.
      security: *a4
      parameters:
        - schema:
            type: string
            minLength: 1
            example: user_01HXY00000000000000000000
          required: true
          name: id
          in: path
          description: The user's identity-provider subject id
      responses:
        '200':
          description: The reactivated user
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/AdminUser'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/admin/debug/sandbox-startup:
    post:
      operationId: admin.debug.sandboxStartup
      x-cli-hidden: true
      tags:
        - Admin
      summary: Measure sandbox startup and command latency
      description: Creates a fresh ephemeral sandbox, uses the first fixed echo
        command as the readiness probe, and measures a second fixed echo
        command. An optional fresh-sandbox uv benchmark also records runtime and
        CPU limits, files.pythonhosted.org throughput, uv phase timings, and CPU
        throttling counters. The sandbox is always destroyed. Runtime failures
        are returned as a partial report. Super-admin only and session-only.
      security: *a4
      requestBody:
        required: false
        description: Optional; omit to use the deployment defaults.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxStartupRequest'
      responses:
        '200':
          description: The sandbox startup diagnostic report
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/SandboxStartupReport'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/admin/config:
    get:
      operationId: admin.config.get
      tags:
        - Admin
      summary: Describe the deployment's configuration
      description: Read-only view of every configuration group (storage, compute,
        auth, …) as resolved from the serving replica's environment at boot;
        secret values are never included, only whether they are set. Super-admin
        only, session-only.
      security: *a4
      responses:
        '200':
          description: The deployment configuration, secrets redacted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/DeploymentConfig'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/admin/policy-analyzer/metadata:
    get:
      operationId: admin.policyAnalyzer.metadata
      tags:
        - Admin
      summary: Describe policy analyzer inputs
      security: *a4
      responses:
        '200':
          description: Policy analyzer metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/PolicyAnalyzerMetadata'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/admin/policy-analyzer/evaluate:
    post:
      operationId: admin.policyAnalyzer.evaluate
      x-cli-hidden: true
      tags:
        - Admin
      summary: Evaluate a policy test suite
      security: *a4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PolicySuiteV1'
      responses:
        '200':
          description: Policy analysis results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/PolicySuiteResult'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/files:
    get:
      operationId: notebooks.workspace.files.read
      x-cli-hidden: true
      tags:
        - Notebooks
      summary: Read raw workspace file content
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            minLength: 1
          required: true
          name: path
          in: query
      responses:
        '200':
          description: Raw workspace file bytes
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: notebooks.workspace.files.write
      x-cli-hidden: true
      tags:
        - Notebooks
      summary: Create or overwrite a workspace file
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            minLength: 1
          required: true
          name: path
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
          required: false
          name: create
          in: query
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Workspace file saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkspaceItem'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/access:
    get:
      operationId: notebooks.workspace.access
      tags:
        - Notebooks
      summary: Get workspace file capabilities
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Workspace access policy
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkspaceAccess'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/entries:
    get:
      operationId: notebooks.workspace.list
      tags:
        - Notebooks
      summary: List a workspace directory
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            default: /
          required: false
          name: path
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 500
          required: false
          name: limit
          in: query
      responses:
        '200':
          description: Workspace entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/WorkspaceItem'
                      cursor:
                        type: string
                    required:
                      - items
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: notebooks.workspace.delete
      x-cli-destructive: true
      tags:
        - Notebooks
      summary: Delete a workspace entry
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            minLength: 1
          required: true
          name: path
          in: query
      responses:
        '200':
          description: Workspace entry deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/search:
    get:
      operationId: notebooks.workspace.search
      tags:
        - Notebooks
      summary: Search workspace paths
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            default: /
          required: false
          name: path
          in: query
        - schema:
            type: string
            minLength: 1
          required: true
          name: query
          in: query
      responses:
        '200':
          description: Workspace search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/WorkspaceItem'
                    required:
                      - items
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/directories:
    post:
      operationId: notebooks.workspace.directories.create
      tags:
        - Notebooks
      summary: Create a workspace directory
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: string
                  minLength: 1
              required:
                - path
      responses:
        '201':
          description: Workspace directory created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkspaceItem'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/move:
    post:
      operationId: notebooks.workspace.move
      x-cli-destructive: true
      tags:
        - Notebooks
      summary: Move a workspace entry
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  minLength: 1
                to:
                  type: string
                  minLength: 1
              required:
                - from
                - to
      responses:
        '200':
          description: Workspace entry moved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkspaceItem'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/copy:
    post:
      operationId: notebooks.workspace.copy
      tags:
        - Notebooks
      summary: Copy a workspace entry
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  minLength: 1
                to:
                  type: string
                  minLength: 1
              required:
                - from
                - to
      responses:
        '200':
          description: Workspace entry copied
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkspaceItem'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/uploads:
    post:
      operationId: startWorkspaceUpload
      tags:
        - Notebooks
      summary: Start a resumable workspace upload
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: string
                  minLength: 1
                size:
                  type: integer
                  minimum: 0
                create_only:
                  type: boolean
              required:
                - path
                - size
      responses:
        '201':
          description: Upload created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      path:
                        type: string
                      size:
                        type: integer
                        minimum: 0
                        maximum: 5368709120
                      part_size:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 8388608
                      parts_done:
                        type: array
                        items:
                          type: integer
                          exclusiveMinimum: 0
                      expires_at:
                        type: number
                      status:
                        type: string
                        enum:
                          - uploading
                          - publishing
                          - complete
                          - cancelled
                    required:
                      - id
                      - path
                      - size
                      - part_size
                      - parts_done
                      - expires_at
                      - status
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/uploads/{uploadId}:
    get:
      operationId: getWorkspaceUpload
      tags:
        - Notebooks
      summary: Get workspace upload progress
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: uploadId
          in: path
      responses:
        '200':
          description: Upload progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      path:
                        type: string
                      size:
                        type: integer
                        minimum: 0
                        maximum: 5368709120
                      part_size:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 8388608
                      parts_done:
                        type: array
                        items:
                          type: integer
                          exclusiveMinimum: 0
                      expires_at:
                        type: number
                      status:
                        type: string
                        enum:
                          - uploading
                          - publishing
                          - complete
                          - cancelled
                    required:
                      - id
                      - path
                      - size
                      - part_size
                      - parts_done
                      - expires_at
                      - status
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: cancelWorkspaceUpload
      tags:
        - Notebooks
      summary: Cancel a workspace upload
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: uploadId
          in: path
      responses:
        '200':
          description: Upload cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties: {}
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/uploads/{uploadId}/parts/{part}:
    put:
      operationId: putWorkspaceUploadPart
      tags:
        - Notebooks
      summary: Upload one workspace file part
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: uploadId
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
          required: true
          name: part
          in: path
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Part stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      path:
                        type: string
                      size:
                        type: integer
                        minimum: 0
                        maximum: 5368709120
                      part_size:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 8388608
                      parts_done:
                        type: array
                        items:
                          type: integer
                          exclusiveMinimum: 0
                      expires_at:
                        type: number
                      status:
                        type: string
                        enum:
                          - uploading
                          - publishing
                          - complete
                          - cancelled
                    required:
                      - id
                      - path
                      - size
                      - part_size
                      - parts_done
                      - expires_at
                      - status
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/workspace/uploads/{uploadId}/complete:
    post:
      operationId: completeWorkspaceUpload
      tags:
        - Notebooks
      summary: Publish a workspace upload
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: uploadId
          in: path
      responses:
        '200':
          description: File published
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkspaceItem'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks:
    get:
      operationId: notebooks.list
      tags:
        - Notebooks
      summary: List notebooks in a project
      description: When paging a filtered list, send the same filters with each cursor.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - draft
              - active
              - archived
              - deleted
            description: Notebook status to match. Deleted notebooks are excluded when
              omitted.
            example: active
          required: false
          description: Notebook status to match. Deleted notebooks are excluded when
            omitted.
          name: status
          in: query
        - schema:
            type: string
            description: Exact tag to match.
            example: analytics
          required: false
          description: Exact tag to match.
          name: tag
          in: query
        - schema:
            type: string
            description: Case-insensitive substring to match against the name or title and
              description.
            example: revenue
          required: false
          description: Case-insensitive substring to match against the name or title and
            description.
          name: q
          in: query
      responses:
        '200':
          description: List of notebooks, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: notebooks.create
      tags:
        - Notebooks
      summary: Create a notebook
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: false
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  example: Revenue Analysis
                description:
                  type: string
                  example: Monthly revenue breakdown
                code:
                  type: string
                  example: import marimo as mo
                tags:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 256
                  maxItems: 50
                  example:
                    - finance
                readme:
                  type: string
                deps:
                  type: string
                runtime:
                  type: object
                  properties:
                    python_version:
                      type: string
                    marimo_version:
                      type: string
                base_image:
                  type: string
                  minLength: 1
                  example: ghcr.io/orgname/marimo-gpu:latest
                compute_profile:
                  type: string
                  minLength: 1
                  example: large
                app_compute_profile:
                  type: string
                  minLength: 1
                  example: large
              required:
                - title
                - description
                - code
      responses:
        '201':
          description: Notebook created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookMeta'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebook-imports:
    post:
      operationId: notebooks.imports.prepare
      x-cli-hidden: true
      tags:
        - Notebooks
      summary: Upload a folder snapshot for notebook import
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      requestBody:
        required: true
        content:
          application/zip:
            schema:
              type: string
              format: binary
      responses:
        '201':
          description: Prepared folder snapshot
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        pattern: ^imp-[0-9a-z]{16}$
                      expires_at:
                        type: string
                        format: date-time
                      files:
                        type: array
                        items:
                          type: object
                          properties:
                            path:
                              type: string
                            size:
                              type: integer
                              minimum: 0
                          required:
                            - path
                            - size
                    required:
                      - id
                      - expires_at
                      - files
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebook-imports/{import_id}/notebooks:
    post:
      operationId: notebooks.imports.publish
      x-cli-hidden: true
      tags:
        - Notebooks
      summary: Create a notebook from a prepared folder snapshot
      description: 'Idempotent per entrypoint: a retry with the same body returns the
        same notebook. A different body for an entrypoint already attempted
        returns 409 `IMPORT_RESTART_REQUIRED`.'
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^imp-[0-9a-z]{16}$
            example: imp-4xz7rp3w8h2k9qm4
          required: true
          name: import_id
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entry_notebook:
                  type: string
                  minLength: 1
                  example: reports/revenue.py
                title:
                  type: string
                  minLength: 1
                  example: Revenue Analysis
                base_image:
                  type: string
                  minLength: 1
                  example: ghcr.io/orgname/marimo-gpu:latest
                compute_profile:
                  type: string
                  minLength: 1
                  example: large
              required:
                - entry_notebook
                - title
      responses:
        '201':
          description: Notebook imported
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookMeta'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebook-imports/{import_id}:
    get:
      operationId: notebooks.imports.get
      x-cli-hidden: true
      tags:
        - Notebooks
      summary: Get the outcome of each notebook in a folder import
      description: Lists every entrypoint with an attempt in progress or finished.
        Entrypoints that were never attempted, or whose attempt stopped and can
        be retried, are absent.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^imp-[0-9a-z]{16}$
            example: imp-4xz7rp3w8h2k9qm4
          required: true
          name: import_id
          in: path
      responses:
        '200':
          description: Import outcome
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        pattern: ^imp-[0-9a-z]{16}$
                      expires_at:
                        type: string
                        format: date-time
                      notebooks:
                        type: array
                        items:
                          type: object
                          properties:
                            entry_notebook:
                              type: string
                            state:
                              type: string
                              enum:
                                - preparing
                                - publishing
                                - complete
                                - expired
                            notebook:
                              $ref: '#/components/schemas/NotebookMeta'
                          required:
                            - entry_notebook
                            - state
                    required:
                      - id
                      - expires_at
                      - notebooks
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/git:
    post:
      operationId: notebooks.create-git
      tags:
        - Notebooks
      summary: Create a git-synced workspace notebook
      description: Ordinary Git sources require manager access. With fork, editors can
        create a working branch when enabled; Idempotency-Key is required and
        the head branch is generated.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: false
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  example: GitHub app
                description:
                  type: string
                  example: Synced from a git repository
                provider:
                  type: string
                  minLength: 1
                  description: Git provider id. Recognized repository hosts take precedence over
                    this explicit claim.
                  example: github
                repo:
                  type: string
                  minLength: 1
                  example: marimo-team/marimohub
                branch:
                  type: string
                  minLength: 1
                  example: main
                fork:
                  type: object
                  properties:
                    base_branch:
                      type: string
                      minLength: 1
                  required:
                    - base_branch
                root_path:
                  type: string
                  example: apps
                entry_notebook:
                  type: string
                  minLength: 1
                  example: my_app.py
                tags:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 256
                  maxItems: 50
                  example:
                    - git
                readme:
                  type: string
                runtime:
                  type: object
                  properties:
                    python_version:
                      type: string
                    marimo_version:
                      type: string
                base_image:
                  type: string
                  minLength: 1
                compute_profile:
                  type: string
                  minLength: 1
                  example: large
                app_compute_profile:
                  type: string
                  minLength: 1
                  example: large
                sync_mode:
                  type: string
                  enum:
                    - push
                    - pull
                  default: push
              required:
                - title
                - description
                - repo
                - entry_notebook
      responses:
        '201':
          description: Git-synced notebook created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/GitNotebookCreateResult'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/sync-token/rotate:
    post:
      operationId: notebooks.rotate-sync-token
      x-cli-destructive: true
      tags:
        - Notebooks
      summary: Rotate a notebook sync token
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Sync token rotated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/SyncToken'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/source:
    patch:
      operationId: notebooks.update-source
      tags:
        - Notebooks
      summary: Update a git-synced notebook source
      description: Requires project manager access because this changes the
        server-side repository.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                repo:
                  type: string
                  minLength: 1
                  example: marimo-team/marimohub
                branch:
                  type: string
                  minLength: 1
                  example: main
                root_path:
                  type: string
                  example: apps
                entry_notebook:
                  type: string
                  minLength: 1
                  example: my_app.py
                sync_mode:
                  type: string
                  enum:
                    - push
                    - pull
              required:
                - repo
                - branch
                - root_path
                - entry_notebook
      responses:
        '200':
          description: Git source updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      source:
                        type: object
                        properties:
                          working_branch:
                            type: object
                            properties:
                              id:
                                type: string
                                pattern: ^[a-f0-9]{64}$
                              base_branch:
                                type: string
                                minLength: 1
                              fork_commit:
                                type: string
                                minLength: 1
                              created_by:
                                type: string
                            required:
                              - id
                              - base_branch
                              - fork_commit
                              - created_by
                          type:
                            type: string
                            enum:
                              - git
                          provider:
                            type:
                              - string
                              - 'null'
                            minLength: 1
                            description:
                              Detected Git provider id, or null when the repository host is not
                              recognized.
                            example: github
                          repo:
                            type: string
                            description: 'Normalized repository coordinate: owner/repo or an HTTPS
                              repository URL.'
                            example: marimo-team/marimohub
                          branch:
                            type: string
                            description: Synced repository branch.
                            example: main
                          root_path:
                            type: string
                            description: Repository-relative directory synced into the notebook workspace.
                            example: apps
                          entry_notebook:
                            type: string
                            description: Path to the entry notebook relative to root_path.
                            example: dashboard.py
                          pending_config:
                            $ref: '#/components/schemas/GitSourceConfig'
                          sync_mode:
                            type: string
                            enum:
                              - push
                              - pull
                          current_version_id:
                            type:
                              - string
                              - 'null'
                          commit:
                            type:
                              - string
                              - 'null'
                          last_synced_at:
                            type:
                              - string
                              - 'null'
                            format: date-time
                            example: 2025-03-05T14:00:00Z
                        required:
                          - type
                          - provider
                          - repo
                          - branch
                          - root_path
                          - entry_notebook
                          - sync_mode
                          - current_version_id
                          - commit
                          - last_synced_at
                    required:
                      - source
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/source/drift:
    get:
      operationId: notebooks.source.drift
      tags:
        - Notebooks
      summary: Compare a git-synced notebook against its branch head
      description: Resolves the configured branch head via the server-side provider
        credential and reports whether the notebook is behind it. Stateless —
        nothing is stored. Requires a provider listed in
        `capabilities.source_control.sync_providers`.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Drift between the synced commit and the branch head
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/SourceDrift'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/source/sync:
    post:
      operationId: notebooks.source.sync
      x-cli-destructive: true
      tags:
        - Notebooks
      summary: Pull the branch head into a git-synced notebook
      description: 'Server-initiated sync: fetches the configured repository tree at
        the branch head and ingests it exactly like a pushed archive. A no-op
        when already at the head. Requires a provider listed in
        `capabilities.source_control.sync_providers`.'
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Sync outcome
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/SourceSyncResult'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}:
    get:
      operationId: notebooks.get
      tags:
        - Notebooks
      summary: Get notebook metadata
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Notebook detail
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookDetail'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: notebooks.update
      tags:
        - Notebooks
      summary: Update a notebook
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                description:
                  type: string
                code:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 256
                  maxItems: 50
                readme:
                  type: string
                deps:
                  type: string
                message:
                  type: string
                  example: Add regional breakdown
                base_image:
                  type:
                    - string
                    - 'null'
                  minLength: 1
                compute_profile:
                  type:
                    - string
                    - 'null'
                  minLength: 1
                app_compute_profile:
                  type:
                    - string
                    - 'null'
                  minLength: 1
                  example: large
      responses:
        '200':
          description: Notebook updated
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookMeta'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: notebooks.delete
      tags:
        - Notebooks
      summary: Delete a notebook (soft-delete)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      responses:
        '200':
          description: Notebook deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/content:
    get:
      operationId: notebooks.content
      tags:
        - Notebooks
      summary: Get notebook code
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Notebook source code
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      code:
                        type: string
                    required:
                      - code
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/security-labels:
    put:
      operationId: notebooks.securityLabels.set
      tags:
        - Notebooks
      summary: Set a notebook security-label override
      description: Sets an override enforced IN ADDITION to the project labels, so it
        can only add restrictions. Requires super-admin standing — no project
        role grants label authority.
      security: *a4
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityLabelsInput'
      responses:
        '200':
          description: Security labels updated
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookMeta'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: notebooks.securityLabels.clear
      tags:
        - Notebooks
      summary: Remove a notebook security-label override
      security: *a4
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      responses:
        '200':
          description: Security labels removed
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookMeta'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/versions:
    get:
      operationId: notebooks.versions.list
      tags:
        - Notebooks
      summary: List notebook versions
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: List of versions, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookVersionPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/versions/{vid}:
    get:
      operationId: notebooks.versions.get
      tags:
        - Notebooks
      summary: Get a specific version
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^ver_[0-9A-Z]{26}$
            example: ver_01HXYZ33333RSTUVWXYZAB
          required: true
          name: vid
          in: path
      responses:
        '200':
          description: Version details with code
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      version:
                        $ref: '#/components/schemas/NotebookVersion'
                      code:
                        type: string
                    required:
                      - version
                      - code
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/html:
    get:
      operationId: notebooks.html
      tags:
        - Notebooks
      summary: Latest HTML snapshot of the notebook's outputs
      description: Serves the newest version's HTML snapshot (captured best-effort at
        session teardown) raw — the static outputs shown to viewers under
        MARIMOHUB_VIEWER_MODE=static. `X-Marimohub-Version-Id` /
        `X-Marimohub-Captured-At` identify the snapshot. 404 with code
        `NO_HTML_SNAPSHOT` when no version has one.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: The HTML snapshot, served sandboxed (CSP forces an opaque origin)
          content:
            text/html:
              schema:
                type: string
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/versions/{vid}/html:
    get:
      operationId: notebooks.versions.html
      tags:
        - Notebooks
      summary: One version's HTML snapshot of the notebook's outputs
      description: Serves the HTML snapshot captured for this specific version, raw.
        404 with code `NO_HTML_SNAPSHOT` when the version captured none.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^ver_[0-9A-Z]{26}$
            example: ver_01HXYZ33333RSTUVWXYZAB
          required: true
          name: vid
          in: path
      responses:
        '200':
          description: The HTML snapshot, served sandboxed (CSP forces an opaque origin)
          content:
            text/html:
              schema:
                type: string
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/versions/{vid}/restore:
    post:
      operationId: notebooks.versions.restore
      x-cli-destructive: true
      tags:
        - Notebooks
      summary: Restore a version as a new save
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^ver_[0-9A-Z]{26}$
            example: ver_01HXYZ33333RSTUVWXYZAB
          required: true
          name: vid
          in: path
      responses:
        '201':
          description: Version restored as a new save; returns the updated notebook
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookMeta'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/duplicate:
    post:
      operationId: notebooks.duplicate
      tags:
        - Notebooks
      summary: Duplicate a notebook
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: false
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  example: Revenue Analysis (copy)
      responses:
        '201':
          description: Notebook duplicated; returns the new notebook
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookMeta'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/move:
    delete:
      operationId: notebooks.move.cancel
      tags:
        - Notebooks
      summary: Cancel an unpublished notebook move
      description: Removes destination copies and makes the notebook available in its
        source project again. A move that has already published cannot be
        cancelled; repeat it to finish.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Move cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: notebooks.move
      tags:
        - Notebooks
      summary: Move a notebook to another project
      description: Repeat the same request to resume a move that was interrupted; the
        notebook is unavailable in both projects until it completes.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: true
          name: if-match
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                destination_project_id:
                  type: string
                  pattern: ^proj-[0-9a-z]{16}$
                  example: proj-7h2k9qm4xz7rp3w8
              required:
                - destination_project_id
      responses:
        '200':
          description: Notebook moved
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookMeta'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/thumbnails:
    get:
      operationId: projects.thumbnails
      tags:
        - Projects
      summary: List visible notebook thumbnails
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      responses:
        '200':
          description: Thumbnail metadata by notebook ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        source:
                          type:
                            - string
                            - 'null'
                          enum:
                            - custom
                            - automatic
                            - null
                        revision:
                          type:
                            - string
                            - 'null'
                        captured_at:
                          type:
                            - string
                            - 'null'
                        has_custom:
                          type: boolean
                      required:
                        - source
                        - revision
                        - captured_at
                        - has_custom
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/thumbnail:
    get:
      operationId: notebooks.thumbnail
      tags:
        - Notebooks
      summary: Get thumbnail metadata
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Thumbnail metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      source:
                        type:
                          - string
                          - 'null'
                        enum:
                          - custom
                          - automatic
                          - null
                      revision:
                        type:
                          - string
                          - 'null'
                      captured_at:
                        type:
                          - string
                          - 'null'
                      has_custom:
                        type: boolean
                    required:
                      - source
                      - revision
                      - captured_at
                      - has_custom
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: notebooks.thumbnail.set
      tags:
        - Notebooks
      summary: Upload a custom cropped thumbnail
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      requestBody:
        required: true
        content:
          image/png:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Thumbnail metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      source:
                        type:
                          - string
                          - 'null'
                        enum:
                          - custom
                          - automatic
                          - null
                      revision:
                        type:
                          - string
                          - 'null'
                      captured_at:
                        type:
                          - string
                          - 'null'
                      has_custom:
                        type: boolean
                    required:
                      - source
                      - revision
                      - captured_at
                      - has_custom
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: notebooks.thumbnail.remove
      tags:
        - Notebooks
      summary: Remove the custom thumbnail
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Thumbnail metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      source:
                        type:
                          - string
                          - 'null'
                        enum:
                          - custom
                          - automatic
                          - null
                      revision:
                        type:
                          - string
                          - 'null'
                      captured_at:
                        type:
                          - string
                          - 'null'
                      has_custom:
                        type: boolean
                    required:
                      - source
                      - revision
                      - captured_at
                      - has_custom
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/thumbnail/image:
    get:
      operationId: notebooks.thumbnail.image
      tags:
        - Notebooks
      summary: Read the selected thumbnail
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            description: Current thumbnail revision for private caching
          required: false
          description: Current thumbnail revision for private caching
          name: r
          in: query
      responses:
        '200':
          description: PNG thumbnail
          content:
            image/png:
              schema:
                type: string
                format: binary
        '304':
          description: Not modified
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/deep-links/{slug}:
    get:
      operationId: deep-links.resolve
      tags:
        - App links
      summary: Resolve an app link using notebook permissions
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 63
            pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?![\s\S])
          required: true
          name: slug
          in: path
      responses:
        '200':
          description: Authorized app link
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      schema_version:
                        type: number
                        enum:
                          - 1
                      registration_id:
                        type: string
                        format: ulid
                      slug:
                        type: string
                        minLength: 1
                        maxLength: 63
                        pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?![\s\S])
                      target:
                        type: object
                        properties:
                          kind:
                            type: string
                            enum:
                              - app
                          project_id:
                            type: string
                          notebook_id:
                            type: string
                        required:
                          - kind
                          - project_id
                          - notebook_id
                        additionalProperties: false
                      access:
                        type: object
                        properties:
                          mode:
                            type: string
                            enum:
                              - inherit
                        required:
                          - mode
                        additionalProperties: false
                      created_by:
                        type: string
                      created_at:
                        type: string
                        format: date-time
                      app:
                        $ref: '#/components/schemas/NotebookApp'
                    required:
                      - schema_version
                      - registration_id
                      - slug
                      - target
                      - access
                      - created_by
                      - created_at
                      - app
                    additionalProperties: false
                    description: The app link. `app` is the app summary for the link target. App
                      users and callers whose token grants `app.read` need
                      `app.read` on the project and notebook; other callers need
                      `project.read`.
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/deep-links/{slug}:
    delete:
      operationId: deep-links.release
      tags:
        - App links
      summary: Release an app slug for immediate reuse
      description: Releases the slug only when the notebook and registration ID match.
        The slug is immediately available for reuse. Old shared URLs can then
        open another notebook. App sessions and notebook permissions stay
        unchanged.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 63
            pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?![\s\S])
          required: true
          name: slug
          in: path
        - schema:
            type: string
            format: ulid
          required: true
          name: registration_id
          in: query
      responses:
        '200':
          description: Registration released, absent, or replaced
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: 'null'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/deep-links:
    get:
      operationId: deep-links.list
      tags:
        - App links
      summary: List notebook app links
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: App links
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeepLink'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: deep-links.register
      tags:
        - App links
      summary: Register a globally unique app slug
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                slug:
                  type: string
                  minLength: 1
                  maxLength: 63
                  pattern: ^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*(?![\s\S])
                kind:
                  type: string
                  enum:
                    - app
                  default: app
                access:
                  type: object
                  properties:
                    mode:
                      type: string
                      enum:
                        - inherit
                  default:
                    mode: inherit
                  required:
                    - mode
                  additionalProperties: false
              required:
                - slug
              additionalProperties: false
      responses:
        '200':
          description: New or existing app link for this notebook
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/DeepLink'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/search:
    get:
      operationId: search.query
      tags:
        - Search
      summary: Search accessible projects and resources
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 256
          required: true
          name: q
          in: query
        - schema:
            type: string
          required: false
          name: project_id
          in: query
        - schema:
            type: string
            description: 'Comma-separated result kinds to include. Values: notebook, code,
              output, datasource, namespace, table, column.'
            example: notebook,code
          required: false
          description: 'Comma-separated result kinds to include. Values: notebook, code,
            output, datasource, namespace, table, column.'
          name: kinds
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          required: false
          name: limit
          in: query
        - schema:
            type: string
            enum:
              - keyword
              - hybrid
            default: keyword
          required: false
          name: mode
          in: query
      responses:
        '200':
          description: Search results and source coverage
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/SearchResponse'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/conversations:
    get:
      operationId: conversations.list
      tags: &a5
        - Conversations
      summary: List your conversations in a project
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      responses:
        '200':
          description: Private project conversations, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      conversations:
                        type: array
                        items:
                          type: object
                          properties:
                            schema_version:
                              type: number
                              enum:
                                - 1
                            id:
                              type: string
                              pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                            title:
                              type: string
                              maxLength: 120
                            created_at:
                              type: string
                              format: date-time
                            updated_at:
                              type: string
                              format: date-time
                            pending:
                              type: object
                              properties:
                                id:
                                  type: string
                                  pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                                expires_at:
                                  type: string
                                  format: date-time
                                stop_requested:
                                  type: boolean
                              required:
                                - id
                                - expires_at
                            last_error:
                              type: string
                              maxLength: 400
                            working_notebook:
                              type: string
                              pattern: ^nb-[0-9a-z]{16}$
                            message_count:
                              type: integer
                              minimum: 0
                            continuation:
                              type: object
                              properties:
                                status:
                                  type: string
                                  enum:
                                    - running
                                    - paused
                                    - needs_review
                                reason:
                                  type: string
                                  enum:
                                    - tool_limit
                                    - context_limit
                                    - interrupted
                                    - stopped
                                    - failed
                              required:
                                - status
                          required:
                            - schema_version
                            - id
                            - title
                            - created_at
                            - updated_at
                            - message_count
                    required:
                      - conversations
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: conversations.create
      tags: *a5
      summary: Start a private conversation
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 120
      responses:
        '200':
          description: Private project conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      conversation:
                        type: object
                        properties:
                          schema_version:
                            type: number
                            enum:
                              - 1
                          id:
                            type: string
                            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                          title:
                            type: string
                            maxLength: 120
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                          messages:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  minLength: 1
                                  maxLength: 80
                                role:
                                  type: string
                                  enum:
                                    - user
                                    - assistant
                                metadata:
                                  type: object
                                  properties:
                                    created_at:
                                      type: string
                                      format: date-time
                                  required:
                                    - created_at
                                parts:
                                  type: array
                                  items:
                                    oneOf:
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - text
                                          text:
                                            type: string
                                            maxLength: 24000
                                          state:
                                            type: string
                                            enum:
                                              - streaming
                                              - done
                                        required:
                                          - type
                                          - text
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - dynamic-tool
                                          toolName:
                                            type: string
                                            maxLength: 80
                                          toolCallId:
                                            type: string
                                            maxLength: 128
                                          state:
                                            type: string
                                            enum:
                                              - input-streaming
                                              - input-available
                                              - output-available
                                              - output-error
                                          input:
                                            type: string
                                            maxLength: 2000
                                          output:
                                            type: string
                                            maxLength: 2000
                                          errorText:
                                            type: string
                                            maxLength: 2000
                                        required:
                                          - type
                                          - toolName
                                          - toolCallId
                                          - state
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - data-permission
                                          id:
                                            type: string
                                            format: uuid
                                          data:
                                            type: object
                                            properties:
                                              id:
                                                type: string
                                                format: uuid
                                              tool_call_id:
                                                type: string
                                                maxLength: 128
                                              kind:
                                                type: string
                                                maxLength: 40
                                              action:
                                                type: string
                                                maxLength: 120
                                              details:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    label:
                                                      type: string
                                                      maxLength: 40
                                                    value:
                                                      type: string
                                                      maxLength: 20000
                                                  required:
                                                    - label
                                                    - value
                                                maxItems: 8
                                              scope:
                                                type: object
                                                properties:
                                                  key:
                                                    type: string
                                                    maxLength: 200
                                                  label:
                                                    type: string
                                                    maxLength: 120
                                                required:
                                                  - key
                                                  - label
                                              can_remember:
                                                type: boolean
                                              status:
                                                type: string
                                                enum:
                                                  - open
                                                  - allowed
                                                  - remembered
                                                  - denied
                                                  - expired
                                                  - cancelled
                                                  - unavailable
                                              expires_at:
                                                type: string
                                                format: date-time
                                            required:
                                              - id
                                              - tool_call_id
                                              - kind
                                              - action
                                              - details
                                              - scope
                                              - can_remember
                                              - status
                                              - expires_at
                                        required:
                                          - type
                                          - id
                                          - data
                                  maxItems: 80
                              required:
                                - id
                                - role
                                - metadata
                                - parts
                            maxItems: 80
                          pending:
                            type: object
                            properties:
                              id:
                                type: string
                                pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                              expires_at:
                                type: string
                                format: date-time
                              stop_requested:
                                type: boolean
                            required:
                              - id
                              - expires_at
                          last_error:
                            type: string
                            maxLength: 400
                          continuation:
                            type: object
                            properties:
                              status:
                                type: string
                                enum:
                                  - running
                                  - paused
                                  - needs_review
                              reason:
                                type: string
                                enum:
                                  - tool_limit
                                  - context_limit
                                  - interrupted
                                  - stopped
                                  - failed
                              task:
                                type: string
                                maxLength: 8000
                              omitted_observations:
                                type: integer
                                minimum: 0
                              observations:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      minLength: 1
                                      maxLength: 155
                                    name:
                                      type: string
                                      minLength: 1
                                      maxLength: 128
                                    result:
                                      type: string
                                      maxLength: 4000
                                  required:
                                    - id
                                    - name
                                    - result
                                maxItems: 16
                              unresolved_calls:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      maxLength: 155
                                    name:
                                      type: string
                                      maxLength: 128
                                  required:
                                    - id
                                    - name
                                maxItems: 48
                            required:
                              - status
                              - task
                              - observations
                              - unresolved_calls
                          working_notebook:
                            type: string
                            pattern: ^nb-[0-9a-z]{16}$
                        required:
                          - schema_version
                          - id
                          - title
                          - created_at
                          - updated_at
                          - messages
                    required:
                      - conversation
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/conversations/{cid}:
    get:
      operationId: conversations.get
      tags: *a5
      summary: Read a conversation
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
      responses:
        '200':
          description: Private project conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      conversation:
                        type: object
                        properties:
                          schema_version:
                            type: number
                            enum:
                              - 1
                          id:
                            type: string
                            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                          title:
                            type: string
                            maxLength: 120
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                          messages:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  minLength: 1
                                  maxLength: 80
                                role:
                                  type: string
                                  enum:
                                    - user
                                    - assistant
                                metadata:
                                  type: object
                                  properties:
                                    created_at:
                                      type: string
                                      format: date-time
                                  required:
                                    - created_at
                                parts:
                                  type: array
                                  items:
                                    oneOf:
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - text
                                          text:
                                            type: string
                                            maxLength: 24000
                                          state:
                                            type: string
                                            enum:
                                              - streaming
                                              - done
                                        required:
                                          - type
                                          - text
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - dynamic-tool
                                          toolName:
                                            type: string
                                            maxLength: 80
                                          toolCallId:
                                            type: string
                                            maxLength: 128
                                          state:
                                            type: string
                                            enum:
                                              - input-streaming
                                              - input-available
                                              - output-available
                                              - output-error
                                          input:
                                            type: string
                                            maxLength: 2000
                                          output:
                                            type: string
                                            maxLength: 2000
                                          errorText:
                                            type: string
                                            maxLength: 2000
                                        required:
                                          - type
                                          - toolName
                                          - toolCallId
                                          - state
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - data-permission
                                          id:
                                            type: string
                                            format: uuid
                                          data:
                                            type: object
                                            properties:
                                              id:
                                                type: string
                                                format: uuid
                                              tool_call_id:
                                                type: string
                                                maxLength: 128
                                              kind:
                                                type: string
                                                maxLength: 40
                                              action:
                                                type: string
                                                maxLength: 120
                                              details:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    label:
                                                      type: string
                                                      maxLength: 40
                                                    value:
                                                      type: string
                                                      maxLength: 20000
                                                  required:
                                                    - label
                                                    - value
                                                maxItems: 8
                                              scope:
                                                type: object
                                                properties:
                                                  key:
                                                    type: string
                                                    maxLength: 200
                                                  label:
                                                    type: string
                                                    maxLength: 120
                                                required:
                                                  - key
                                                  - label
                                              can_remember:
                                                type: boolean
                                              status:
                                                type: string
                                                enum:
                                                  - open
                                                  - allowed
                                                  - remembered
                                                  - denied
                                                  - expired
                                                  - cancelled
                                                  - unavailable
                                              expires_at:
                                                type: string
                                                format: date-time
                                            required:
                                              - id
                                              - tool_call_id
                                              - kind
                                              - action
                                              - details
                                              - scope
                                              - can_remember
                                              - status
                                              - expires_at
                                        required:
                                          - type
                                          - id
                                          - data
                                  maxItems: 80
                              required:
                                - id
                                - role
                                - metadata
                                - parts
                            maxItems: 80
                          pending:
                            type: object
                            properties:
                              id:
                                type: string
                                pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                              expires_at:
                                type: string
                                format: date-time
                              stop_requested:
                                type: boolean
                            required:
                              - id
                              - expires_at
                          last_error:
                            type: string
                            maxLength: 400
                          continuation:
                            type: object
                            properties:
                              status:
                                type: string
                                enum:
                                  - running
                                  - paused
                                  - needs_review
                              reason:
                                type: string
                                enum:
                                  - tool_limit
                                  - context_limit
                                  - interrupted
                                  - stopped
                                  - failed
                              task:
                                type: string
                                maxLength: 8000
                              omitted_observations:
                                type: integer
                                minimum: 0
                              observations:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      minLength: 1
                                      maxLength: 155
                                    name:
                                      type: string
                                      minLength: 1
                                      maxLength: 128
                                    result:
                                      type: string
                                      maxLength: 4000
                                  required:
                                    - id
                                    - name
                                    - result
                                maxItems: 16
                              unresolved_calls:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      maxLength: 155
                                    name:
                                      type: string
                                      maxLength: 128
                                  required:
                                    - id
                                    - name
                                maxItems: 48
                            required:
                              - status
                              - task
                              - observations
                              - unresolved_calls
                          working_notebook:
                            type: string
                            pattern: ^nb-[0-9a-z]{16}$
                        required:
                          - schema_version
                          - id
                          - title
                          - created_at
                          - updated_at
                          - messages
                    required:
                      - conversation
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: conversations.update
      x-cli-hidden: true
      tags: *a5
      summary: Choose the notebook shown beside a conversation
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                working_notebook:
                  type:
                    - string
                    - 'null'
                  pattern: ^nb-[0-9a-z]{16}$
                  description: Notebook shown beside the conversation; null closes the pane.
              required:
                - working_notebook
              additionalProperties: false
      responses:
        '200':
          description: Private project conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      conversation:
                        type: object
                        properties:
                          schema_version:
                            type: number
                            enum:
                              - 1
                          id:
                            type: string
                            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                          title:
                            type: string
                            maxLength: 120
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                          messages:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  minLength: 1
                                  maxLength: 80
                                role:
                                  type: string
                                  enum:
                                    - user
                                    - assistant
                                metadata:
                                  type: object
                                  properties:
                                    created_at:
                                      type: string
                                      format: date-time
                                  required:
                                    - created_at
                                parts:
                                  type: array
                                  items:
                                    oneOf:
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - text
                                          text:
                                            type: string
                                            maxLength: 24000
                                          state:
                                            type: string
                                            enum:
                                              - streaming
                                              - done
                                        required:
                                          - type
                                          - text
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - dynamic-tool
                                          toolName:
                                            type: string
                                            maxLength: 80
                                          toolCallId:
                                            type: string
                                            maxLength: 128
                                          state:
                                            type: string
                                            enum:
                                              - input-streaming
                                              - input-available
                                              - output-available
                                              - output-error
                                          input:
                                            type: string
                                            maxLength: 2000
                                          output:
                                            type: string
                                            maxLength: 2000
                                          errorText:
                                            type: string
                                            maxLength: 2000
                                        required:
                                          - type
                                          - toolName
                                          - toolCallId
                                          - state
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - data-permission
                                          id:
                                            type: string
                                            format: uuid
                                          data:
                                            type: object
                                            properties:
                                              id:
                                                type: string
                                                format: uuid
                                              tool_call_id:
                                                type: string
                                                maxLength: 128
                                              kind:
                                                type: string
                                                maxLength: 40
                                              action:
                                                type: string
                                                maxLength: 120
                                              details:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    label:
                                                      type: string
                                                      maxLength: 40
                                                    value:
                                                      type: string
                                                      maxLength: 20000
                                                  required:
                                                    - label
                                                    - value
                                                maxItems: 8
                                              scope:
                                                type: object
                                                properties:
                                                  key:
                                                    type: string
                                                    maxLength: 200
                                                  label:
                                                    type: string
                                                    maxLength: 120
                                                required:
                                                  - key
                                                  - label
                                              can_remember:
                                                type: boolean
                                              status:
                                                type: string
                                                enum:
                                                  - open
                                                  - allowed
                                                  - remembered
                                                  - denied
                                                  - expired
                                                  - cancelled
                                                  - unavailable
                                              expires_at:
                                                type: string
                                                format: date-time
                                            required:
                                              - id
                                              - tool_call_id
                                              - kind
                                              - action
                                              - details
                                              - scope
                                              - can_remember
                                              - status
                                              - expires_at
                                        required:
                                          - type
                                          - id
                                          - data
                                  maxItems: 80
                              required:
                                - id
                                - role
                                - metadata
                                - parts
                            maxItems: 80
                          pending:
                            type: object
                            properties:
                              id:
                                type: string
                                pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                              expires_at:
                                type: string
                                format: date-time
                              stop_requested:
                                type: boolean
                            required:
                              - id
                              - expires_at
                          last_error:
                            type: string
                            maxLength: 400
                          continuation:
                            type: object
                            properties:
                              status:
                                type: string
                                enum:
                                  - running
                                  - paused
                                  - needs_review
                              reason:
                                type: string
                                enum:
                                  - tool_limit
                                  - context_limit
                                  - interrupted
                                  - stopped
                                  - failed
                              task:
                                type: string
                                maxLength: 8000
                              omitted_observations:
                                type: integer
                                minimum: 0
                              observations:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      minLength: 1
                                      maxLength: 155
                                    name:
                                      type: string
                                      minLength: 1
                                      maxLength: 128
                                    result:
                                      type: string
                                      maxLength: 4000
                                  required:
                                    - id
                                    - name
                                    - result
                                maxItems: 16
                              unresolved_calls:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      maxLength: 155
                                    name:
                                      type: string
                                      maxLength: 128
                                  required:
                                    - id
                                    - name
                                maxItems: 48
                            required:
                              - status
                              - task
                              - observations
                              - unresolved_calls
                          working_notebook:
                            type: string
                            pattern: ^nb-[0-9a-z]{16}$
                        required:
                          - schema_version
                          - id
                          - title
                          - created_at
                          - updated_at
                          - messages
                    required:
                      - conversation
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: conversations.delete
      x-cli-destructive: true
      tags: *a5
      summary: Delete a conversation
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
      responses:
        '200':
          description: Conversation deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                        enum:
                          - true
                    required:
                      - deleted
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/conversations/{cid}/messages:
    post:
      operationId: conversations.send
      tags: *a5
      summary: Send a message and wait for the reply
      description: Runs one assistant turn and returns the saved conversation.
        Mutating tools that need consent are skipped on this endpoint; use the
        web UI to approve them.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  minLength: 1
                  maxLength: 8000
              required:
                - content
              additionalProperties: false
      responses:
        '200':
          description: Private project conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      conversation:
                        type: object
                        properties:
                          schema_version:
                            type: number
                            enum:
                              - 1
                          id:
                            type: string
                            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                          title:
                            type: string
                            maxLength: 120
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                          messages:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  minLength: 1
                                  maxLength: 80
                                role:
                                  type: string
                                  enum:
                                    - user
                                    - assistant
                                metadata:
                                  type: object
                                  properties:
                                    created_at:
                                      type: string
                                      format: date-time
                                  required:
                                    - created_at
                                parts:
                                  type: array
                                  items:
                                    oneOf:
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - text
                                          text:
                                            type: string
                                            maxLength: 24000
                                          state:
                                            type: string
                                            enum:
                                              - streaming
                                              - done
                                        required:
                                          - type
                                          - text
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - dynamic-tool
                                          toolName:
                                            type: string
                                            maxLength: 80
                                          toolCallId:
                                            type: string
                                            maxLength: 128
                                          state:
                                            type: string
                                            enum:
                                              - input-streaming
                                              - input-available
                                              - output-available
                                              - output-error
                                          input:
                                            type: string
                                            maxLength: 2000
                                          output:
                                            type: string
                                            maxLength: 2000
                                          errorText:
                                            type: string
                                            maxLength: 2000
                                        required:
                                          - type
                                          - toolName
                                          - toolCallId
                                          - state
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - data-permission
                                          id:
                                            type: string
                                            format: uuid
                                          data:
                                            type: object
                                            properties:
                                              id:
                                                type: string
                                                format: uuid
                                              tool_call_id:
                                                type: string
                                                maxLength: 128
                                              kind:
                                                type: string
                                                maxLength: 40
                                              action:
                                                type: string
                                                maxLength: 120
                                              details:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    label:
                                                      type: string
                                                      maxLength: 40
                                                    value:
                                                      type: string
                                                      maxLength: 20000
                                                  required:
                                                    - label
                                                    - value
                                                maxItems: 8
                                              scope:
                                                type: object
                                                properties:
                                                  key:
                                                    type: string
                                                    maxLength: 200
                                                  label:
                                                    type: string
                                                    maxLength: 120
                                                required:
                                                  - key
                                                  - label
                                              can_remember:
                                                type: boolean
                                              status:
                                                type: string
                                                enum:
                                                  - open
                                                  - allowed
                                                  - remembered
                                                  - denied
                                                  - expired
                                                  - cancelled
                                                  - unavailable
                                              expires_at:
                                                type: string
                                                format: date-time
                                            required:
                                              - id
                                              - tool_call_id
                                              - kind
                                              - action
                                              - details
                                              - scope
                                              - can_remember
                                              - status
                                              - expires_at
                                        required:
                                          - type
                                          - id
                                          - data
                                  maxItems: 80
                              required:
                                - id
                                - role
                                - metadata
                                - parts
                            maxItems: 80
                          pending:
                            type: object
                            properties:
                              id:
                                type: string
                                pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                              expires_at:
                                type: string
                                format: date-time
                              stop_requested:
                                type: boolean
                            required:
                              - id
                              - expires_at
                          last_error:
                            type: string
                            maxLength: 400
                          continuation:
                            type: object
                            properties:
                              status:
                                type: string
                                enum:
                                  - running
                                  - paused
                                  - needs_review
                              reason:
                                type: string
                                enum:
                                  - tool_limit
                                  - context_limit
                                  - interrupted
                                  - stopped
                                  - failed
                              task:
                                type: string
                                maxLength: 8000
                              omitted_observations:
                                type: integer
                                minimum: 0
                              observations:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      minLength: 1
                                      maxLength: 155
                                    name:
                                      type: string
                                      minLength: 1
                                      maxLength: 128
                                    result:
                                      type: string
                                      maxLength: 4000
                                  required:
                                    - id
                                    - name
                                    - result
                                maxItems: 16
                              unresolved_calls:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      maxLength: 155
                                    name:
                                      type: string
                                      maxLength: 128
                                  required:
                                    - id
                                    - name
                                maxItems: 48
                            required:
                              - status
                              - task
                              - observations
                              - unresolved_calls
                          working_notebook:
                            type: string
                            pattern: ^nb-[0-9a-z]{16}$
                        required:
                          - schema_version
                          - id
                          - title
                          - created_at
                          - updated_at
                          - messages
                    required:
                      - conversation
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/conversations/{cid}/resume:
    post:
      operationId: conversations.resume
      tags: *a5
      summary: Continue an interrupted task and wait for the reply
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                acknowledge_uncertain:
                  type: boolean
              additionalProperties: false
      responses:
        '200':
          description: Private project conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      conversation:
                        type: object
                        properties:
                          schema_version:
                            type: number
                            enum:
                              - 1
                          id:
                            type: string
                            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                          title:
                            type: string
                            maxLength: 120
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                          messages:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  minLength: 1
                                  maxLength: 80
                                role:
                                  type: string
                                  enum:
                                    - user
                                    - assistant
                                metadata:
                                  type: object
                                  properties:
                                    created_at:
                                      type: string
                                      format: date-time
                                  required:
                                    - created_at
                                parts:
                                  type: array
                                  items:
                                    oneOf:
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - text
                                          text:
                                            type: string
                                            maxLength: 24000
                                          state:
                                            type: string
                                            enum:
                                              - streaming
                                              - done
                                        required:
                                          - type
                                          - text
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - dynamic-tool
                                          toolName:
                                            type: string
                                            maxLength: 80
                                          toolCallId:
                                            type: string
                                            maxLength: 128
                                          state:
                                            type: string
                                            enum:
                                              - input-streaming
                                              - input-available
                                              - output-available
                                              - output-error
                                          input:
                                            type: string
                                            maxLength: 2000
                                          output:
                                            type: string
                                            maxLength: 2000
                                          errorText:
                                            type: string
                                            maxLength: 2000
                                        required:
                                          - type
                                          - toolName
                                          - toolCallId
                                          - state
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - data-permission
                                          id:
                                            type: string
                                            format: uuid
                                          data:
                                            type: object
                                            properties:
                                              id:
                                                type: string
                                                format: uuid
                                              tool_call_id:
                                                type: string
                                                maxLength: 128
                                              kind:
                                                type: string
                                                maxLength: 40
                                              action:
                                                type: string
                                                maxLength: 120
                                              details:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    label:
                                                      type: string
                                                      maxLength: 40
                                                    value:
                                                      type: string
                                                      maxLength: 20000
                                                  required:
                                                    - label
                                                    - value
                                                maxItems: 8
                                              scope:
                                                type: object
                                                properties:
                                                  key:
                                                    type: string
                                                    maxLength: 200
                                                  label:
                                                    type: string
                                                    maxLength: 120
                                                required:
                                                  - key
                                                  - label
                                              can_remember:
                                                type: boolean
                                              status:
                                                type: string
                                                enum:
                                                  - open
                                                  - allowed
                                                  - remembered
                                                  - denied
                                                  - expired
                                                  - cancelled
                                                  - unavailable
                                              expires_at:
                                                type: string
                                                format: date-time
                                            required:
                                              - id
                                              - tool_call_id
                                              - kind
                                              - action
                                              - details
                                              - scope
                                              - can_remember
                                              - status
                                              - expires_at
                                        required:
                                          - type
                                          - id
                                          - data
                                  maxItems: 80
                              required:
                                - id
                                - role
                                - metadata
                                - parts
                            maxItems: 80
                          pending:
                            type: object
                            properties:
                              id:
                                type: string
                                pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                              expires_at:
                                type: string
                                format: date-time
                              stop_requested:
                                type: boolean
                            required:
                              - id
                              - expires_at
                          last_error:
                            type: string
                            maxLength: 400
                          continuation:
                            type: object
                            properties:
                              status:
                                type: string
                                enum:
                                  - running
                                  - paused
                                  - needs_review
                              reason:
                                type: string
                                enum:
                                  - tool_limit
                                  - context_limit
                                  - interrupted
                                  - stopped
                                  - failed
                              task:
                                type: string
                                maxLength: 8000
                              omitted_observations:
                                type: integer
                                minimum: 0
                              observations:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      minLength: 1
                                      maxLength: 155
                                    name:
                                      type: string
                                      minLength: 1
                                      maxLength: 128
                                    result:
                                      type: string
                                      maxLength: 4000
                                  required:
                                    - id
                                    - name
                                    - result
                                maxItems: 16
                              unresolved_calls:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      maxLength: 155
                                    name:
                                      type: string
                                      maxLength: 128
                                  required:
                                    - id
                                    - name
                                maxItems: 48
                            required:
                              - status
                              - task
                              - observations
                              - unresolved_calls
                          working_notebook:
                            type: string
                            pattern: ^nb-[0-9a-z]{16}$
                        required:
                          - schema_version
                          - id
                          - title
                          - created_at
                          - updated_at
                          - messages
                    required:
                      - conversation
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/conversations/{cid}/stream:
    post:
      operationId: conversations.stream
      x-cli-hidden: true
      tags: *a5
      summary: Send a message and stream the reply
      description: Runs one turn and streams the assistant reply as an AI SDK UI
        message stream (server-sent events). The turn keeps running if the
        client disconnects; reconnect with GET …/stream or reload the
        conversation.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - type: object
                  properties:
                    content:
                      type: string
                      minLength: 1
                      maxLength: 8000
                    resume:
                      type: boolean
                      enum:
                        - false
                  required:
                    - content
                  additionalProperties: false
                - type: object
                  properties:
                    resume:
                      type: boolean
                      enum:
                        - true
                    acknowledge_uncertain:
                      type: boolean
                  required:
                    - resume
                  additionalProperties: false
      responses:
        '200':
          description: UI message stream for the assistant reply
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: conversations.reconnect
      x-cli-hidden: true
      tags: *a5
      summary: Re-attach to the running reply
      description: Replays the chunks streamed so far for the turn running on this
        instance and follows it live. Responds 204 when no turn runs here; the
        saved conversation then carries the progress.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
      responses:
        '200':
          description: UI message stream for the running reply
          content:
            text/event-stream:
              schema:
                type: string
        '204':
          description: No reply is streaming on this instance
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/conversations/{cid}/stop:
    post:
      operationId: conversations.stop
      tags: *a5
      summary: Stop the running reply
      description: Stops the turn running for this conversation on any instance.
        Completed tool results stay saved and the task can be continued. Returns
        stopped=false when no turn is running.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
      responses:
        '200':
          description: Stop request outcome
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      stopped:
                        type: boolean
                    required:
                      - stopped
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/conversations/{cid}/continuation/dismiss:
    post:
      operationId: conversations.dismiss
      tags: *a5
      summary: Discard the saved task without continuing it
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
      responses:
        '200':
          description: Private project conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      conversation:
                        type: object
                        properties:
                          schema_version:
                            type: number
                            enum:
                              - 1
                          id:
                            type: string
                            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                          title:
                            type: string
                            maxLength: 120
                          created_at:
                            type: string
                            format: date-time
                          updated_at:
                            type: string
                            format: date-time
                          messages:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  minLength: 1
                                  maxLength: 80
                                role:
                                  type: string
                                  enum:
                                    - user
                                    - assistant
                                metadata:
                                  type: object
                                  properties:
                                    created_at:
                                      type: string
                                      format: date-time
                                  required:
                                    - created_at
                                parts:
                                  type: array
                                  items:
                                    oneOf:
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - text
                                          text:
                                            type: string
                                            maxLength: 24000
                                          state:
                                            type: string
                                            enum:
                                              - streaming
                                              - done
                                        required:
                                          - type
                                          - text
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - dynamic-tool
                                          toolName:
                                            type: string
                                            maxLength: 80
                                          toolCallId:
                                            type: string
                                            maxLength: 128
                                          state:
                                            type: string
                                            enum:
                                              - input-streaming
                                              - input-available
                                              - output-available
                                              - output-error
                                          input:
                                            type: string
                                            maxLength: 2000
                                          output:
                                            type: string
                                            maxLength: 2000
                                          errorText:
                                            type: string
                                            maxLength: 2000
                                        required:
                                          - type
                                          - toolName
                                          - toolCallId
                                          - state
                                      - type: object
                                        properties:
                                          type:
                                            type: string
                                            enum:
                                              - data-permission
                                          id:
                                            type: string
                                            format: uuid
                                          data:
                                            type: object
                                            properties:
                                              id:
                                                type: string
                                                format: uuid
                                              tool_call_id:
                                                type: string
                                                maxLength: 128
                                              kind:
                                                type: string
                                                maxLength: 40
                                              action:
                                                type: string
                                                maxLength: 120
                                              details:
                                                type: array
                                                items:
                                                  type: object
                                                  properties:
                                                    label:
                                                      type: string
                                                      maxLength: 40
                                                    value:
                                                      type: string
                                                      maxLength: 20000
                                                  required:
                                                    - label
                                                    - value
                                                maxItems: 8
                                              scope:
                                                type: object
                                                properties:
                                                  key:
                                                    type: string
                                                    maxLength: 200
                                                  label:
                                                    type: string
                                                    maxLength: 120
                                                required:
                                                  - key
                                                  - label
                                              can_remember:
                                                type: boolean
                                              status:
                                                type: string
                                                enum:
                                                  - open
                                                  - allowed
                                                  - remembered
                                                  - denied
                                                  - expired
                                                  - cancelled
                                                  - unavailable
                                              expires_at:
                                                type: string
                                                format: date-time
                                            required:
                                              - id
                                              - tool_call_id
                                              - kind
                                              - action
                                              - details
                                              - scope
                                              - can_remember
                                              - status
                                              - expires_at
                                        required:
                                          - type
                                          - id
                                          - data
                                  maxItems: 80
                              required:
                                - id
                                - role
                                - metadata
                                - parts
                            maxItems: 80
                          pending:
                            type: object
                            properties:
                              id:
                                type: string
                                pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
                              expires_at:
                                type: string
                                format: date-time
                              stop_requested:
                                type: boolean
                            required:
                              - id
                              - expires_at
                          last_error:
                            type: string
                            maxLength: 400
                          continuation:
                            type: object
                            properties:
                              status:
                                type: string
                                enum:
                                  - running
                                  - paused
                                  - needs_review
                              reason:
                                type: string
                                enum:
                                  - tool_limit
                                  - context_limit
                                  - interrupted
                                  - stopped
                                  - failed
                              task:
                                type: string
                                maxLength: 8000
                              omitted_observations:
                                type: integer
                                minimum: 0
                              observations:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      minLength: 1
                                      maxLength: 155
                                    name:
                                      type: string
                                      minLength: 1
                                      maxLength: 128
                                    result:
                                      type: string
                                      maxLength: 4000
                                  required:
                                    - id
                                    - name
                                    - result
                                maxItems: 16
                              unresolved_calls:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      maxLength: 155
                                    name:
                                      type: string
                                      maxLength: 128
                                  required:
                                    - id
                                    - name
                                maxItems: 48
                            required:
                              - status
                              - task
                              - observations
                              - unresolved_calls
                          working_notebook:
                            type: string
                            pattern: ^nb-[0-9a-z]{16}$
                        required:
                          - schema_version
                          - id
                          - title
                          - created_at
                          - updated_at
                          - messages
                    required:
                      - conversation
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/conversations/{cid}/permissions/{rid}:
    post:
      operationId: conversations.permissions.decide
      x-cli-hidden: true
      tags: *a5
      summary: Answer a tool consent request
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          required: true
          name: cid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: rid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                decision:
                  type: string
                  enum:
                    - allow
                    - always
                    - deny
              required:
                - decision
      responses:
        '200':
          description: Permission decision outcome
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      accepted:
                        type: boolean
                      reason:
                        type: string
                        enum:
                          - closed
                    required:
                      - accepted
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/chat-permissions:
    get:
      operationId: chat-permissions.list
      tags: *a5
      summary: List remembered tool permissions
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      responses:
        '200':
          description: Remembered permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      grants:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                            kind:
                              type: string
                              minLength: 1
                              maxLength: 40
                            scope_key:
                              type: string
                              minLength: 1
                              maxLength: 200
                            scope_label:
                              type: string
                              maxLength: 120
                            action:
                              type: string
                              maxLength: 120
                            created_at:
                              type: string
                              format: date-time
                          required:
                            - id
                            - kind
                            - scope_key
                            - scope_label
                            - action
                            - created_at
                        maxItems: 200
                    required:
                      - grants
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/chat-permissions/{grant_id}:
    delete:
      operationId: chat-permissions.revoke
      tags: *a5
      summary: Forget a remembered tool permission
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: grant_id
          in: path
      responses:
        '200':
          description: Permission removal outcome
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      removed:
                        type: boolean
                    required:
                      - removed
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/previews:
    post:
      operationId: notebooks.previews.create
      tags:
        - Previews
      summary: Create a notebook preview
      description: Creation persists intent and returns immediately; preparation runs
        asynchronously. Idempotency keys are retained for seven days from
        creation. Branch previews automatically publish future branch commits.
        Commit previews remain pinned. Previews inherit notebook access,
        integrations, and secrets. Editors are temporary and never write back.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: false
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                source:
                  oneOf:
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - branch
                        branch:
                          type: string
                          minLength: 1
                          pattern: ^(?!@(?:$|\{))(?![-/])(?!.*(?:\.\.|\/\/|@\{|[\x00-\x20\x7f~^:?*[\\]))(?!.*(?:^|\/)\.)(?!.*\.lock(?:\/|$))[^/]+(?:\/[^/]+)*(?<![/.])$
                      required:
                        - type
                        - branch
                      additionalProperties: false
                    - type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - commit
                        commit:
                          type: string
                          pattern: ^[a-fA-F0-9]{40}$
                      required:
                        - type
                        - commit
                      additionalProperties: false
                compute_profile:
                  type: string
                  minLength: 1
                eager:
                  type: boolean
                expires_at:
                  type: string
                  format: date-time
                pull_request:
                  type: integer
                  exclusiveMinimum: 0
              required:
                - name
                - source
              additionalProperties: false
      responses:
        '202':
          description: Preview accepted for preparation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookPreview'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: notebooks.previews.list
      tags:
        - Previews
      summary: List notebook previews
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Previews
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookPreviewPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/previews/reconcile:
    post:
      operationId: notebooks.previews.reconcile
      x-cli-hidden: true
      tags:
        - Previews
      summary: Reconcile previews for a GitHub pull request
      description: Records ordered workflow events and applies the PR retention
        policy. Preparation and capacity retries run asynchronously.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                repository:
                  type: string
                  minLength: 1
                  maxLength: 500
                pull_request:
                  type: integer
                  exclusiveMinimum: 0
                event:
                  type: string
                  enum:
                    - opened
                    - reopened
                    - synchronize
                    - closed
                commit:
                  type: string
                  pattern: ^[a-fA-F0-9]{40}$
                workflow_id:
                  type: string
                  pattern: ^\d+$
                run_id:
                  type: string
                  pattern: ^\d{1,20}$
                run_number:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 1000000000
                event_at:
                  type: string
                  format: date-time
                policy:
                  type: object
                  properties:
                    mode:
                      type: string
                      enum:
                        - sticky
                        - commits
                      default: sticky
                    keep:
                      type: integer
                      minimum: 1
                      maximum: 25
                      default: 5
                    eager:
                      type: boolean
                      default: true
                    idle_days:
                      type: integer
                      minimum: 1
                      maximum: 30
                  additionalProperties: false
              required:
                - repository
                - pull_request
                - event
                - commit
                - workflow_id
                - run_id
                - run_number
                - event_at
                - policy
              additionalProperties: false
      responses:
        '202':
          description: Preview reconciliation accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      state:
                        type: string
                        enum:
                          - active
                          - closed
                          - expired
                          - unknown
                        description: 'Known values: active, closed, expired. Unrecognized values
                          normalize to unknown.'
                        example: active
                      pending:
                        type: boolean
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/NotebookPreview'
                    required:
                      - state
                      - pending
                      - items
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/previews/{prid}/prepare:
    post:
      operationId: notebooks.previews.prepare
      tags:
        - Previews
      summary: Request preview preparation
      description: Queues deferred preparation or retries failed preparation without
        starting compute. Retry requests respect the existing backoff. Requires
        permission to run an app or temporary editor.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^prev-[0-9a-z]{16}$
            example: prev-7h2k9qm4xz7rp3w8
          required: true
          name: prid
          in: path
      responses:
        '202':
          description: Preparation requested
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookPreview'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/previews/{prid}:
    get:
      operationId: notebooks.previews.get
      tags:
        - Previews
      summary: Get a notebook preview
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^prev-[0-9a-z]{16}$
            example: prev-7h2k9qm4xz7rp3w8
          required: true
          name: prid
          in: path
      responses:
        '200':
          description: Preview
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookPreview'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: notebooks.previews.delete
      tags:
        - Previews
      summary: Delete a preview and retire its compute
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^prev-[0-9a-z]{16}$
            example: prev-7h2k9qm4xz7rp3w8
          required: true
          name: prid
          in: path
      responses:
        '202':
          description: Preview revoked; cleanup pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/previews/{prid}/sessions:
    post:
      operationId: notebooks.previews.sessions.create
      tags:
        - Previews
      summary: Run a preview app or temporary editor
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^prev-[0-9a-z]{16}$
            example: prev-7h2k9qm4xz7rp3w8
          required: true
          name: prid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum:
                    - edit
                    - app
                app_visit_id:
                  type: string
                  minLength: 1
                  maxLength: 128
              required:
                - mode
              additionalProperties: false
      responses:
        '200':
          description: Preview session
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/SessionCreateResult'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/source/refs:
    get:
      operationId: notebooks.source.refs
      tags:
        - Previews
      summary: Suggest GitHub branches or recent commits
      description: Returns at most 30 matches from the first 100 branches or recent
        commits. Manual values remain supported. Providers without suggestion
        support return 422.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            enum:
              - branch
              - commit
          required: true
          name: type
          in: query
        - schema:
            type: string
            maxLength: 250
            default: ''
          required: false
          name: query
          in: query
      responses:
        '200':
          description: Source suggestions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        value:
                          type: string
                        commit:
                          type: string
                        label:
                          type: string
                      required:
                        - value
                        - commit
                        - label
                    maxItems: 30
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/apps:
    get:
      operationId: apps.list
      tags:
        - Apps
      summary: List accessible notebook apps
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
        - schema:
            type: string
          required: false
          name: q
          in: query
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
          required: false
          name: project_id
          in: query
      responses:
        '200':
          description: Apps
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    allOf:
                      - $ref: '#/components/schemas/NotebookAppPage'
                      - type: object
                        properties:
                          project:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              your_role:
                                type:
                                  - string
                                  - 'null'
                                enum:
                                  - admin
                                  - manager
                                  - editor
                                  - viewer
                                  - app-user
                                  - null
                            required:
                              - id
                              - name
                              - your_role
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/app:
    get:
      operationId: apps.get
      tags:
        - Apps
      summary: Get notebook app details
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: App
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/NotebookApp'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/sessions/{sid}/change-requests:
    post:
      operationId: notebooks.change-requests.open
      tags:
        - Source control publishing
      summary: Publish notebook changes to a new or existing change request
      description: A proposal is an immutable set of notebook changes captured with
        its exact source revision. This operation captures a proposal from a
        running persistent editor session and publishes it as a pull request,
        merge request, or equivalent through the configured source-control
        provider. Set target_proposal_id to update the change request published
        by that proposal; omit it to create a new change request. The
        Idempotency-Key header is required; retry with the same key to resume
        the same operation. If the error code is PROPOSAL_RETRY_REQUIRED, retry
        with a new key instead.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^sess-[0-9a-z]{16}$
            example: sess-9qm4xz7rp3w8h2k9
          required: true
          name: sid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: true
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenNotebookChangeRequestBody'
      responses:
        '201':
          description: Change request published
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/OpenNotebookChangeRequestResult'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/sessions/{sid}/working-branch/saves:
    post:
      operationId: notebooks.working-branch.saves.create
      tags: &a6
        - Working branches
      summary: Commit source changes to the working branch
      description: Requires working-branch.write and access to the session. Reuse
        Idempotency-Key to resume the same captured changes. The returned state
        distinguishes confirmed commits from pending synchronization and
        conflicts. Does not save excluded runtime files.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^sess-[0-9a-z]{16}$
            example: sess-9qm4xz7rp3w8h2k9
          required: true
          name: sid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: true
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  minLength: 1
                  maxLength: 65536
      responses:
        '200':
          description: Save operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkingBranchSave'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/working-branch:
    get:
      operationId: notebooks.working-branch.get
      tags: *a6
      summary: Inspect the working branch and latest save
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Working branch status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkingBranchStatus'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/working-branch/saves/{save_id}:
    get:
      operationId: notebooks.working-branch.saves.get
      tags: *a6
      summary: Inspect a captured save operation
      description: Only the save author or a project manager can read the receipt.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^[a-f0-9]{64}$
          required: true
          name: save_id
          in: path
      responses:
        '200':
          description: Save operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkingBranchSave'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/working-branch/saves/{save_id}/recovery:
    get:
      operationId: notebooks.working-branch.saves.recovery
      tags: *a6
      summary: Download captured source changes for recovery
      description: Returns a ZIP containing a manifest of modifications/deletions and
        captured file bytes. Only the save author or a project manager can
        download it. Payloads become eligible for cleanup at expires_at.
        Captures of unfinished dispatched saves (`ref_dispatched`,
        `remote_committed`, `hub_synced`) stay until the save finishes.
        Downloads remain available until the payload is pruned.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^[a-f0-9]{64}$
          required: true
          name: save_id
          in: path
      responses:
        '200':
          description: Recovery archive
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/working-branch/saves/{save_id}/retry:
    post:
      operationId: notebooks.working-branch.saves.retry
      tags: *a6
      summary: Resume an existing save operation
      description: The save author can resume any stage. Any editor can resume a save
        whose commit is already on GitHub (`remote_committed` or `hub_synced`).
        Reuses its immutable capture and commit; does not require the original
        Idempotency-Key.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^[a-f0-9]{64}$
          required: true
          name: save_id
          in: path
      responses:
        '200':
          description: Save operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkingBranchSave'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/working-branch/change-request:
    post:
      operationId: notebooks.working-branch.change-request.open
      tags: *a6
      summary: Open the working branch pull request
      description: Opens or returns the one pull request associated with this working
        branch. Does not capture or commit unsaved session edits. The
        Idempotency-Key header is required; retry with the same key after a lost
        response.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: true
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 256
                body:
                  type: string
                  maxLength: 65536
                draft:
                  type: boolean
                  default: true
      responses:
        '201':
          description: Working branch pull request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/WorkingBranchChangeRequestResponse'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/sessions:
    get:
      operationId: sessions.list
      tags:
        - Sessions
      summary: List active sessions for a project
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Active sessions for the project, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/SessionPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/sessions/{sid}:
    get:
      operationId: sessions.get
      tags:
        - Sessions
      summary: Get a session (status + kernel URL)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^sess-[0-9a-z]{16}$
            example: sess-9qm4xz7rp3w8h2k9
          required: true
          name: sid
          in: path
        - schema:
            type:
              - integer
              - 'null'
            minimum: 0
            maximum: 20
            description: Wait up to this many seconds for a starting session to change
              status.
          required: false
          description: Wait up to this many seconds for a starting session to change status.
          name: wait
          in: query
      responses:
        '200':
          description: Session
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Session'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: sessions.terminate
      tags:
        - Sessions
      summary: Terminate a session and destroy sandbox
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^sess-[0-9a-z]{16}$
            example: sess-9qm4xz7rp3w8h2k9
          required: true
          name: sid
          in: path
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            description: Wait for teardown to finish before responding. Use for restart.
          required: false
          description: Wait for teardown to finish before responding. Use for restart.
          name: wait
          in: query
      responses:
        '200':
          description: Session terminated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '202':
          description: Session termination accepted; teardown continues in the background
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/editor-session:
    get:
      operationId: sessions.editor.get
      tags:
        - Sessions
      summary: Inspect persistent editor ownership
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      responses:
        '200':
          description: Persistent editor ownership and current activity
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/EditorSessionState'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/editor-session/takeover:
    post:
      operationId: sessions.editor.takeover
      x-cli-destructive: true
      tags:
        - Sessions
      summary: Gracefully take over an exclusive editor session
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditorTakeoverBody'
      responses:
        '200':
          description: The prior editor was saved and stopped
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/sessions:
    post:
      operationId: sessions.create
      tags:
        - Sessions
      summary: Create a session and provision a sandbox
      description: Create or reuse a notebook sandbox. Edit-session reuse follows the
        configured editor sandbox-sharing policy. App sessions use sticky visit
        assignments in a version-aware pool.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: false
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: false
        description: Optional; omit for an edit session.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionCreateBody'
      responses:
        '200':
          description: Session created or reused
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/SessionCreateResult'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/sessions/{sid}/heartbeat:
    post:
      operationId: sessions.heartbeat
      tags:
        - Sessions
      summary: Update session heartbeat
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^sess-[0-9a-z]{16}$
            example: sess-9qm4xz7rp3w8h2k9
          required: true
          name: sid
          in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                visit_id:
                  type: string
                  minLength: 1
                  maxLength: 128
                generation:
                  type: string
                  minLength: 1
                  maxLength: 128
              required:
                - visit_id
                - generation
      responses:
        '200':
          description: Heartbeat updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Session'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/sessions/{sid}/leave:
    post:
      operationId: sessions.leaveApp
      tags:
        - Sessions
      summary: Release this app visit
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^sess-[0-9a-z]{16}$
            example: sess-9qm4xz7rp3w8h2k9
          required: true
          name: sid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                visit_id:
                  type: string
                  minLength: 1
                  maxLength: 128
                generation:
                  type: string
                  minLength: 1
                  maxLength: 128
              required:
                - visit_id
                - generation
      responses:
        '200':
          description: Visit released
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/sessions/{sid}/surfaces/{surface}:
    post:
      operationId: sessions.surfaces.ensure
      tags:
        - Sessions
      summary: Start or reuse a session surface
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^sess-[0-9a-z]{16}$
            example: sess-9qm4xz7rp3w8h2k9
          required: true
          name: sid
          in: path
        - schema:
            type: string
            enum:
              - vscode
              - opencode
          required: true
          name: surface
          in: path
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SurfaceStartBody'
      responses:
        '200':
          description: Surface ready
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    allOf:
                      - $ref: '#/components/schemas/Surface'
                      - type: object
                        properties:
                          id:
                            type: string
                            enum:
                              - vscode
                              - opencode
                        required:
                          - id
                required:
                  - success
                  - data
        '202':
          description: Surface starting
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    allOf:
                      - $ref: '#/components/schemas/Surface'
                      - type: object
                        properties:
                          id:
                            type: string
                            enum:
                              - vscode
                              - opencode
                        required:
                          - id
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: sessions.surfaces.get
      tags:
        - Sessions
      summary: Get a session surface
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^sess-[0-9a-z]{16}$
            example: sess-9qm4xz7rp3w8h2k9
          required: true
          name: sid
          in: path
        - schema:
            type: string
            enum:
              - vscode
              - opencode
          required: true
          name: surface
          in: path
      responses:
        '200':
          description: Surface status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    allOf:
                      - $ref: '#/components/schemas/Surface'
                      - type: object
                        properties:
                          id:
                            type: string
                            enum:
                              - vscode
                              - opencode
                        required:
                          - id
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: sessions.surfaces.stop
      tags:
        - Sessions
      summary: Stop a secondary session surface
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^sess-[0-9a-z]{16}$
            example: sess-9qm4xz7rp3w8h2k9
          required: true
          name: sid
          in: path
        - schema:
            type: string
            enum:
              - vscode
              - opencode
          required: true
          name: surface
          in: path
      responses:
        '200':
          description: Surface stopped
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/jobs:
    get:
      operationId: jobs.list
      tags:
        - Jobs
      summary: List a notebook’s jobs
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Job definitions, oldest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/JobPage'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: jobs.create
      tags:
        - Jobs
      summary: Create a job
      description: A job runs the notebook headlessly with `marimo export html` — on a
        cron schedule, or on demand via `jobs.runs.trigger`. Runs execute with
        the project’s resolved integration secrets and federated credentials, so
        this requires the editor role like starting a session.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: false
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCreateBody'
      responses:
        '201':
          description: Job created
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Job'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/jobs/{jid}:
    get:
      operationId: jobs.get
      tags:
        - Jobs
      summary: Get a job
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^job-[0-9a-z]{16}$
            example: job-7h2k9qm4xz7rp3w8
          required: true
          name: jid
          in: path
      responses:
        '200':
          description: Job
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Job'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: jobs.update
      tags:
        - Jobs
      summary: Update a job
      description: Partial update. `null` clears an optional field (schedule,
        parameters, retry, timeout, notifications).
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^job-[0-9a-z]{16}$
            example: job-7h2k9qm4xz7rp3w8
          required: true
          name: jid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobUpdateBody'
      responses:
        '200':
          description: Job updated
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/Job'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: jobs.delete
      x-cli-destructive: true
      tags:
        - Jobs
      summary: Delete a job and its run history
      description: Active runs are cancelled and their sandboxes destroyed first.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^job-[0-9a-z]{16}$
            example: job-7h2k9qm4xz7rp3w8
          required: true
          name: jid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: true
          name: if-match
          in: header
      responses:
        '200':
          description: Job deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/jobs/{jid}/runs:
    post:
      operationId: jobs.runs.trigger
      tags:
        - Jobs
      summary: Run a job now
      description: Enqueues a run; the scheduler on the maintenance replica dispatches
        it within one tick. Returns the queued run — poll `jobs.runs.get` for
        progress.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^job-[0-9a-z]{16}$
            example: job-7h2k9qm4xz7rp3w8
          required: true
          name: jid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: Stable client-generated key reused for retries of the same
              operation.
            example: a1b2c3d4-e5f6-7890
          required: false
          description: Stable client-generated key reused for retries of the same operation.
          name: idempotency-key
          in: header
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobRunTriggerBody'
      responses:
        '201':
          description: Run queued
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/JobRun'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: jobs.runs.list
      tags:
        - Jobs
      summary: List a job’s runs
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^job-[0-9a-z]{16}$
            example: job-7h2k9qm4xz7rp3w8
          required: true
          name: jid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Runs, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/JobRunPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/jobs/{jid}/runs/{rid}:
    get:
      operationId: jobs.runs.get
      tags:
        - Jobs
      summary: Get a run
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^job-[0-9a-z]{16}$
            example: job-7h2k9qm4xz7rp3w8
          required: true
          name: jid
          in: path
        - schema:
            type: string
            pattern: ^run_[0-9A-HJKMNP-TV-Z]{26}$
            example: run_01HXYZ33333RSTUVWXYZABCDEF
          required: true
          name: rid
          in: path
      responses:
        '200':
          description: Run
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/JobRun'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/jobs/{jid}/runs/{rid}/cancel:
    post:
      operationId: jobs.runs.cancel
      x-cli-destructive: true
      tags:
        - Jobs
      summary: Cancel a run
      description: Marks the run cancelled and destroys its sandbox when one exists.
        Runs are history and are never deleted individually.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^job-[0-9a-z]{16}$
            example: job-7h2k9qm4xz7rp3w8
          required: true
          name: jid
          in: path
        - schema:
            type: string
            pattern: ^run_[0-9A-HJKMNP-TV-Z]{26}$
            example: run_01HXYZ33333RSTUVWXYZABCDEF
          required: true
          name: rid
          in: path
      responses:
        '200':
          description: Run cancelled (or already terminal)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/JobRun'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/jobs/{jid}/runs/{rid}/html:
    get:
      operationId: jobs.runs.html
      tags:
        - Jobs
      summary: Rendered notebook output of a run
      description: Serves the HTML the run exported, raw. 404 with code
        `NO_RUN_OUTPUT` when the run captured none (still running, cancelled, or
        failed before exporting).
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^job-[0-9a-z]{16}$
            example: job-7h2k9qm4xz7rp3w8
          required: true
          name: jid
          in: path
        - schema:
            type: string
            pattern: ^run_[0-9A-HJKMNP-TV-Z]{26}$
            example: run_01HXYZ33333RSTUVWXYZABCDEF
          required: true
          name: rid
          in: path
      responses:
        '200':
          description: The rendered output, served sandboxed (CSP forces an opaque origin)
          content:
            text/html:
              schema:
                type: string
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/notebooks/{nid}/jobs/{jid}/runs/{rid}/logs:
    get:
      operationId: jobs.runs.logs
      tags:
        - Jobs
      summary: stdout/stderr of a run
      description: 'Raw text, editor-only: logs can echo environment values and
        tracebacks the viewer role cannot otherwise read. 404 with code
        `NO_RUN_OUTPUT` when none were captured.'
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^nb-[0-9a-z]{16}$
            example: nb-3w8h2k9qm4xz7rp3
          required: true
          name: nid
          in: path
        - schema:
            type: string
            pattern: ^job-[0-9a-z]{16}$
            example: job-7h2k9qm4xz7rp3w8
          required: true
          name: jid
          in: path
        - schema:
            type: string
            pattern: ^run_[0-9A-HJKMNP-TV-Z]{26}$
            example: run_01HXYZ33333RSTUVWXYZABCDEF
          required: true
          name: rid
          in: path
      responses:
        '200':
          description: Captured logs
          content:
            text/plain:
              schema:
                type: string
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/integrations/kinds:
    get:
      operationId: integrations.kinds.list
      tags:
        - Integrations
      summary: List available integration kinds (schemas drive the config forms)
      responses:
        '200':
          description: Registered integration kinds
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationKind'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations:
    get:
      operationId: integrations.project.list
      tags:
        - Integrations
      summary: List a project's integrations
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Integration instances (no config)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: integrations.project.create
      tags:
        - Integrations
      summary: Create an integration (manager only)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                kind:
                  type: string
                  minLength: 1
                name:
                  type: string
                  pattern: ^[a-z][a-z0-9-]{0,31}$
                  example: prod
                config:
                  type: object
                  additionalProperties: {}
                change_note:
                  type: string
                  maxLength: 500
              required:
                - kind
                - name
                - config
              additionalProperties: false
      responses:
        '201':
          description: Integration created (config redacted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationDetail'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}:
    get:
      operationId: integrations.project.get
      tags:
        - Integrations
      summary: Get an integration with its redacted config
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
      responses:
        '200':
          description: Integration detail (config redacted)
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationDetail'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: integrations.project.update
      tags:
        - Integrations
      summary: Update an integration (manager only); a config change appends a version
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  pattern: ^[a-z][a-z0-9-]{0,31}$
                enabled:
                  type: boolean
                config:
                  type: object
                  additionalProperties: {}
                change_note:
                  type: string
                  maxLength: 500
              additionalProperties: false
      responses:
        '200':
          description: Integration updated (config redacted)
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationDetail'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: integrations.project.delete
      tags:
        - Integrations
      summary: Delete an integration and its version history (manager only)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      responses:
        '200':
          description: Integration deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/versions:
    get:
      operationId: integrations.project.versions
      tags:
        - Integrations
      summary: List an integration's config versions (metadata only)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Version history, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationVersionPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/copy:
    post:
      operationId: integrations.project.copy
      tags:
        - Integrations
      summary: Copy an integration from another project (manager of both projects)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationCopyRequest'
      responses:
        '201':
          description: Integration copied (inline secrets re-encrypted; external
            references preserved)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationDetail'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/test:
    post:
      operationId: integrations.project.test
      tags:
        - Integrations
      summary: Probe connectivity for an unsaved config or a stored instance (manager
        only)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationTestRequest'
      responses:
        '200':
          description: Probe outcome (never secret material)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationTestResult'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/query-readiness:
    post:
      operationId: integrations.project.query-readiness
      tags:
        - Integrations
      summary: Evaluate SQL readiness for an unsaved integration config (manager only)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationQueryReadinessRequest'
      responses:
        '200':
          description: All SQL readiness checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationQueryReadinessCheck'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/uploads:
    post:
      operationId: startObjectUpload
      tags:
        - Integrations
      summary: Start an object upload
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                bucket:
                  type: string
                  minLength: 1
                  maxLength: 256
                path:
                  type: string
                  minLength: 1
                  maxLength: 1024
                size:
                  type: integer
                  minimum: 0
                  maximum: 5368709120
                content_type:
                  type: string
                  maxLength: 256
                  pattern: ^[^\r\n]*$
              required:
                - bucket
                - path
                - size
      responses:
        '201':
          description: Upload created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      path:
                        type: string
                      size:
                        type: integer
                        minimum: 0
                        maximum: 5368709120
                      part_size:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 8388608
                      parts_done:
                        type: array
                        items:
                          type: integer
                          exclusiveMinimum: 0
                      expires_at:
                        type: number
                      status:
                        type: string
                        enum:
                          - uploading
                          - publishing
                          - complete
                          - cancelled
                    required:
                      - id
                      - path
                      - size
                      - part_size
                      - parts_done
                      - expires_at
                      - status
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/uploads/{uploadId}:
    get:
      operationId: getObjectUpload
      tags:
        - Integrations
      summary: Get object upload progress
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: uploadId
          in: path
      responses:
        '200':
          description: Upload progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      path:
                        type: string
                      size:
                        type: integer
                        minimum: 0
                        maximum: 5368709120
                      part_size:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 8388608
                      parts_done:
                        type: array
                        items:
                          type: integer
                          exclusiveMinimum: 0
                      expires_at:
                        type: number
                      status:
                        type: string
                        enum:
                          - uploading
                          - publishing
                          - complete
                          - cancelled
                    required:
                      - id
                      - path
                      - size
                      - part_size
                      - parts_done
                      - expires_at
                      - status
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: cancelObjectUpload
      tags:
        - Integrations
      summary: Cancel an object upload
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: uploadId
          in: path
      responses:
        '200':
          description: Upload cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties: {}
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/uploads/{uploadId}/parts/{part}:
    put:
      operationId: putObjectUploadPart
      tags:
        - Integrations
      summary: Upload one object part
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: uploadId
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
          required: true
          name: part
          in: path
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Part stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      path:
                        type: string
                      size:
                        type: integer
                        minimum: 0
                        maximum: 5368709120
                      part_size:
                        type: integer
                        exclusiveMinimum: 0
                        maximum: 8388608
                      parts_done:
                        type: array
                        items:
                          type: integer
                          exclusiveMinimum: 0
                      expires_at:
                        type: number
                      status:
                        type: string
                        enum:
                          - uploading
                          - publishing
                          - complete
                          - cancelled
                    required:
                      - id
                      - path
                      - size
                      - part_size
                      - parts_done
                      - expires_at
                      - status
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/uploads/{uploadId}/complete:
    post:
      operationId: completeObjectUpload
      tags:
        - Integrations
      summary: Publish an object upload
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            format: uuid
          required: true
          name: uploadId
          in: path
      responses:
        '200':
          description: Object published
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      bucket:
                        type: string
                      key:
                        type: string
                      size:
                        type: number
                    required:
                      - bucket
                      - key
                      - size
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse:
    get:
      operationId: integrations.project.browse.get
      tags:
        - Integrations
      summary: Whether this integration instance can be browsed (editor or above)
      description: Browse routes resolve the id against the project tier first, then
        the inherited org tier; a shadowed org instance reads as absent. Object
        uploads require explicit write access.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
      responses:
        '200':
          description: Instance browse capability
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationBrowseCapability'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/namespaces:
    get:
      operationId: integrations.project.browse.namespaces
      tags:
        - Integrations
      summary: List catalog namespaces (editor or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 500
            default: 100
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            example: 'false'
          required: false
          name: fresh
          in: query
        - schema:
            type: string
            minLength: 1
            description: Namespace parts joined by U+001F (percent-encoded as %1F).
            example: sales
          required: false
          description: Namespace parts joined by U+001F (percent-encoded as %1F).
          name: parent
          in: query
      responses:
        '200':
          description: Namespaces, with upstream pagination passed through
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationBrowseNamespacePage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/tables:
    get:
      operationId: integrations.project.browse.tables
      tags:
        - Integrations
      summary: List tables in a namespace (editor or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 500
            default: 100
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            example: 'false'
          required: false
          name: fresh
          in: query
        - schema:
            type: string
            minLength: 1
            description: Namespace parts joined by U+001F (percent-encoded as %1F).
            example: sales
          required: true
          description: Namespace parts joined by U+001F (percent-encoded as %1F).
          name: namespace
          in: query
      responses:
        '200':
          description: Table names, with upstream pagination passed through
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationBrowseTablePage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/schema:
    get:
      operationId: integrations.project.browse.schema
      tags:
        - Integrations
      summary: Get a table's schema (editor or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            minLength: 1
            description: Namespace parts joined by U+001F (percent-encoded as %1F).
            example: sales
          required: true
          description: Namespace parts joined by U+001F (percent-encoded as %1F).
          name: namespace
          in: query
        - schema:
            type: string
            minLength: 1
            example: orders
          required: true
          name: table
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            example: 'false'
          required: false
          name: fresh
          in: query
      responses:
        '200':
          description: Column names, types, and partitioning
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationTableSchema'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/preview:
    post:
      operationId: integrations.project.browse.preview
      tags:
        - Integrations
      summary: Preview a table's rows (editor or above)
      description: Runs a bounded read-only scan. HTTP-native integrations execute
        through the guarded browse probe; other integrations use a fresh,
        isolated preview sandbox.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                namespace:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  minItems: 1
                table:
                  type: string
                  minLength: 1
                limit:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 100
                  default: 20
              required:
                - namespace
                - table
      responses:
        '200':
          description: Column names and a bounded row sample
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationTablePreview'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/query:
    post:
      operationId: integrations.project.browse.query
      tags:
        - Integrations
      summary: Run SQL against one integration (manager or above)
      description: SQL execution gated by deployment configuration. Each request uses
        a fresh isolated worker with hard execution, row, and byte limits.
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sql:
                  type: string
                  minLength: 1
              required:
                - sql
              additionalProperties: false
      responses:
        '200':
          description: Bounded query result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationDataQueryResult'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/query/schema:
    get:
      operationId: integrations.project.browse.query-schema
      tags:
        - Integrations
      summary: Get bounded SQL completion schema (manager or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            minLength: 1
          required: false
          name: focus_namespace
          in: query
        - schema:
            type: string
            minLength: 1
          required: false
          name: focus_table
          in: query
      responses:
        '200':
          description: Bounded table and column schema for SQL tools
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationQuerySchema'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/query/generate:
    post:
      operationId: integrations.project.browse.generate-query
      tags:
        - Integrations
      summary: Generate or revise SQL with managed AI (manager or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum:
                    - generate
                    - revise
                instruction:
                  type: string
                  minLength: 1
                  maxLength: 4000
                sql:
                  type: string
              required:
                - mode
                - instruction
              additionalProperties: false
      responses:
        '200':
          description: Generated DuckDB SQL
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      sql:
                        type: string
                    required:
                      - sql
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/buckets:
    get:
      operationId: integrations.project.browse.object-buckets
      tags:
        - Integrations
      summary: List object-store buckets (editor or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            default: 50
            example: 50
          required: false
          name: limit
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            example: 'false'
          required: false
          name: fresh
          in: query
      responses:
        '200':
          description: Buckets visible through the integration
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/IntegrationObjectBucket'
                      next_cursor:
                        type:
                          - string
                          - 'null'
                    required:
                      - items
                      - next_cursor
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects:
    get:
      operationId: integrations.project.browse.objects
      tags:
        - Integrations
      summary: List direct object-store children (editor or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            default: 50
            example: 50
          required: false
          name: limit
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            example: 'false'
          required: false
          name: fresh
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            example: analytics-lake
          required: true
          name: bucket
          in: query
        - schema:
            type: string
            example: events/2026/
          required: false
          name: prefix
          in: query
      responses:
        '200':
          description: Direct prefixes and objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/IntegrationObjectEntry'
                      next_cursor:
                        type:
                          - string
                          - 'null'
                    required:
                      - items
                      - next_cursor
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/search:
    get:
      operationId: integrations.project.browse.search-objects
      tags:
        - Integrations
      summary: Run a bounded object-key search (editor or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            default: 50
            example: 50
          required: false
          name: limit
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            example: analytics-lake
          required: true
          name: bucket
          in: query
        - schema:
            type: string
            example: events/2026/
          required: false
          name: prefix
          in: query
        - schema:
            type: string
            minLength: 2
            maxLength: 1024
          required: true
          name: query
          in: query
        - schema:
            type: string
          required: false
          name: formats
          in: query
        - schema:
            type: string
            format: date-time
          required: false
          name: modified_after
          in: query
        - schema:
            type: string
            format: date-time
          required: false
          name: modified_before
          in: query
        - schema:
            type:
              - number
              - 'null'
            minimum: 0
          required: false
          name: min_size
          in: query
        - schema:
            type:
              - number
              - 'null'
            minimum: 0
          required: false
          name: max_size
          in: query
      responses:
        '200':
          description: Bounded object-key search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/IntegrationObjectEntry'
                      next_cursor:
                        type:
                          - string
                          - 'null'
                      scanned:
                        type: integer
                        minimum: 0
                      complete:
                        type: boolean
                    required:
                      - items
                      - next_cursor
                      - scanned
                      - complete
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/head:
    get:
      operationId: integrations.project.browse.object-head
      tags:
        - Integrations
      summary: Read object metadata and tags (editor or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            example: analytics-lake
          required: true
          name: bucket
          in: query
        - schema:
            type: string
            minLength: 1
            example: events/2026/part-001.jsonl
          required: true
          name: key
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 2048
          required: false
          name: version_id
          in: query
      responses:
        '200':
          description: Object metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationObjectDetail'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/versions:
    get:
      operationId: integrations.project.browse.object-versions
      tags:
        - Integrations
      summary: List object versions and delete markers (editor or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            maximum: 100
            default: 50
            example: 50
          required: false
          name: limit
          in: query
        - schema:
            type: string
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            example: 'false'
          required: false
          name: fresh
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            example: analytics-lake
          required: true
          name: bucket
          in: query
        - schema:
            type: string
            minLength: 1
            example: events/2026/part-001.jsonl
          required: true
          name: key
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 2048
          required: false
          name: version_id
          in: query
      responses:
        '200':
          description: Object versions and delete markers
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/IntegrationObjectVersion'
                      next_cursor:
                        type:
                          - string
                          - 'null'
                    required:
                      - items
                      - next_cursor
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/preview:
    post:
      operationId: integrations.project.browse.preview-object
      tags:
        - Integrations
      summary: Preview bounded object content (editor or above)
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                bucket:
                  type: string
                  minLength: 1
                  maxLength: 255
                key:
                  type: string
                  minLength: 1
                version_id:
                  type: string
                  minLength: 1
                  maxLength: 2048
                limit:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 100
                  default: 20
              required:
                - bucket
                - key
      responses:
        '200':
          description: Bounded object preview
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationObjectPreview'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/projects/{pid}/integrations/{iid}/browse/objects/content:
    get:
      operationId: integrations.project.browse.object-content
      tags:
        - Integrations
      summary: Stream object content (editor or above)
      description: 'Streams the object bytes raw — the target of the `content_url`
        embedded in preview responses. `inline=true` serves a sandboxed inline
        rendering (CSP forces an opaque origin); otherwise the response is a
        download (`Content-Disposition: attachment`). Supports single-part
        `Range` requests and an `etag` precondition (412 on mismatch).'
      parameters:
        - schema:
            type: string
            pattern: ^proj-[0-9a-z]{16}$
            example: proj-7h2k9qm4xz7rp3w8
          required: true
          name: pid
          in: path
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            example: analytics-lake
          required: true
          name: bucket
          in: query
        - schema:
            type: string
            minLength: 1
            example: events/2026/part-001.jsonl
          required: true
          name: key
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 2048
          required: false
          name: version_id
          in: query
        - schema:
            type: string
            enum:
              - 'true'
              - 'false'
            default: 'false'
          required: false
          name: inline
          in: query
        - schema:
            type: string
            maxLength: 1024
          required: false
          name: etag
          in: query
        - schema:
            type: string
            example: bytes=0-1023
          required: false
          name: range
          in: header
      responses:
        '200':
          description: The object bytes, streamed
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '206':
          description: The requested byte range (`Content-Range` identifies it)
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '416':
          description: Range not satisfiable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/org/integrations:
    get:
      operationId: integrations.org.list
      tags:
        - Integrations
      summary: List org-wide integrations (requires org-integration.manage)
      parameters:
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Org integration instances (no config)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: integrations.org.create
      tags:
        - Integrations
      summary: Create an org-wide integration (requires org-integration.manage)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                kind:
                  type: string
                  minLength: 1
                name:
                  type: string
                  pattern: ^[a-z][a-z0-9-]{0,31}$
                  example: prod
                config:
                  type: object
                  additionalProperties: {}
                change_note:
                  type: string
                  maxLength: 500
              required:
                - kind
                - name
                - config
              additionalProperties: false
      responses:
        '201':
          description: Integration created (config redacted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationDetail'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/org/integrations/{iid}:
    get:
      operationId: integrations.org.get
      tags:
        - Integrations
      summary: Get an org-wide integration with its redacted config (requires
        org-integration.manage)
      parameters:
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
      responses:
        '200':
          description: Integration detail (config redacted)
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationDetail'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      operationId: integrations.org.update
      tags:
        - Integrations
      summary: Update an org-wide integration (requires org-integration.manage)
      parameters:
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  pattern: ^[a-z][a-z0-9-]{0,31}$
                enabled:
                  type: boolean
                config:
                  type: object
                  additionalProperties: {}
                change_note:
                  type: string
                  maxLength: 500
              additionalProperties: false
      responses:
        '200':
          description: Integration updated (config redacted)
          headers:
            ETag:
              schema:
                type: string
                description: Validator for the resource version. It may be weak (`W/`) when the
                  response is compressed. Send it back unchanged as `If-Match`
                  to guard a write.
                example: '"2025-03-05T14:00:00Z"'
              required: true
              description: Validator for the resource version. It may be weak (`W/`) when the
                response is compressed. Send it back unchanged as `If-Match` to
                guard a write.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationDetail'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: integrations.org.delete
      tags:
        - Integrations
      summary: Delete an org-wide integration and its version history (requires
        org-integration.manage)
      parameters:
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: string
            example: '"2025-03-05T14:00:00Z"'
          required: false
          name: if-match
          in: header
      responses:
        '200':
          description: Integration deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '412':
          description: Precondition failed (If-Match did not match the current version)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/org/integrations/{iid}/versions:
    get:
      operationId: integrations.org.versions
      tags:
        - Integrations
      summary: List an org-wide integration's config versions (requires
        org-integration.manage)
      parameters:
        - schema:
            type: string
            pattern: ^intg-[0-9a-z]{16}$
            example: intg-7h2k9qm4xz7rp3w8
          required: true
          name: iid
          in: path
        - schema:
            type: integer
            exclusiveMinimum: 0
            example: 100
          required: false
          name: limit
          in: query
        - schema:
            type: string
            example: WyIyMDI1LTAzLTA1VDE0OjAwOjAwWiIsIm5iLTEiXQ
          required: false
          name: cursor
          in: query
      responses:
        '200':
          description: Version history, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationVersionPage'
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/org/integrations/test:
    post:
      operationId: integrations.org.test
      tags:
        - Integrations
      summary: Probe connectivity for an unsaved or stored org config (requires
        org-integration.manage)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationTestRequest'
      responses:
        '200':
          description: Probe outcome (never secret material)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/IntegrationTestResult'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/org/integrations/query-readiness:
    post:
      operationId: integrations.org.query-readiness
      tags:
        - Integrations
      summary: Evaluate SQL readiness for an unsaved org config (requires
        org-integration.manage)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationQueryReadinessRequest'
      responses:
        '200':
          description: All SQL readiness checks
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IntegrationQueryReadinessCheck'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/users/search:
    get:
      operationId: users.search
      tags:
        - Users
      summary: Search the user directory
      description: Case-insensitive substring search over email, name, and id, for the
        add-member picker. Only users who have signed in at least once are in
        the directory. Under MARIMOHUB_DEFAULT_ROLE=none the caller must own or
        belong to at least one project — a signed-in account with no involvement
        cannot enumerate the directory; with a default role set, every
        authenticated user may search.
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 200
            example: ada
          required: true
          name: q
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 25
            default: 10
          required: false
          name: limit
          in: query
      responses:
        '200':
          description: Matching users, name-sorted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/users:
    get:
      operationId: users.resolve
      tags:
        - Users
      summary: Resolve user ids to display identities
      description: Batch-resolve opaque user ids (the auth `sub` stored as a notebook
        `author` or session `user_id`) into `{ id, email, name, picture_url }`.
        Ids with no recorded identity are omitted from the result map.
        Authenticated users may resolve display identities without project
        membership. Credential grants still restrict lookup of other users.
      parameters:
        - schema:
            type: string
            description: Comma-separated user ids. At most 100 non-empty ids; whitespace and
              empty entries are ignored.
            example: user,sub-abc123
          required: false
          description: Comma-separated user ids. At most 100 non-empty ids; whitespace and
            empty entries are ignored.
          name: ids
          in: query
      responses:
        '200':
          description: Map of user id → resolved identity (unknown ids omitted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/User'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/tokens:
    post:
      operationId: auth.tokens.create
      tags:
        - Auth
      summary: Create a personal access token
      description: 'Mint a machine credential that acts as the calling user (CI,
        scripts, the CLI): send it as `Authorization: Bearer mhub_pat_…`. The
        plaintext token is returned once, in this response, and never again.
        Requires session (SSO) auth — a token cannot mint tokens.'
      security: *a4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  example: ci-deploy
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 3650
                  description: Days until expiry; omit for a non-expiring token.
                  example: 90
              required:
                - name
              additionalProperties: false
      responses:
        '201':
          description: The new token — copy it now; it is never shown again
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/ApiTokenCreated'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: auth.tokens.list
      tags:
        - Auth
      summary: List the caller's personal access tokens
      description: Metadata only — the secret is never retrievable after creation.
      security: *a4
      responses:
        '200':
          description: Tokens, newest first
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiToken'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/tokens/scoped:
    post:
      operationId: auth.tokens.createScoped
      tags:
        - Auth
      summary: Create a scoped personal access token
      description: Mint a v2 personal access token with an immutable action and
        project grant. Selected projects must be visible to the caller when the
        token is created.
      security: *a4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  example: ci-deploy
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 3650
                  description: Days until expiry; omit for a non-expiring token.
                  example: 90
                grant:
                  type: object
                  properties:
                    actions:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            enum:
                              - support.request
                              - project.create
                              - admin.access
                              - org-integration.manage
                              - audit.global.read
                              - directory.search
                              - app.read
                              - project.read
                              - project.update
                              - project.delete
                              - project.members.manage
                              - project.events.read
                              - project.alerts.manage
                              - notebook.write
                              - notebook.manage
                              - deep-link.manage
                              - preview.manage
                              - integration.read
                              - integration.use
                              - integration.write
                              - integration.manage
                              - change-request.publish
                              - working-branch.write
                              - security-labels.raise
                              - security-labels.lower
                              - session.attach
                              - session.stop
                              - session.surface
                              - session.proxy
                              - session.start
                          uniqueItems: true
                    projects:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            pattern: ^proj-[0-9a-z]{16}$
                          minItems: 1
                          maxItems: 100
                          uniqueItems: true
                  required:
                    - actions
                    - projects
                  additionalProperties: false
              required:
                - name
                - grant
              additionalProperties: false
      responses:
        '201':
          description: The new token — copy it now; it is never shown again
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/ApiTokenCreated'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/tokens/mcp:
    post:
      operationId: auth.tokens.createMcp
      tags:
        - Auth
      summary: Create a manual MCP token
      description: Mint a scoped token bound to this deployment’s MCP URL. It
        authenticates only to MCP, not the REST API, and expires in at most 90
        days. Requires session authentication and
        MARIMOHUB_MCP_MANUAL_TOKENS=on. The plaintext token is returned only
        once.
      security: *a4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  example: ci-deploy
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 90
                  description: Days until expiry, at most 90.
                  example: 30
                grant:
                  type: object
                  properties:
                    actions:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            enum:
                              - support.request
                              - project.create
                              - admin.access
                              - org-integration.manage
                              - audit.global.read
                              - directory.search
                              - app.read
                              - project.read
                              - project.update
                              - project.delete
                              - project.members.manage
                              - project.events.read
                              - project.alerts.manage
                              - notebook.write
                              - notebook.manage
                              - deep-link.manage
                              - preview.manage
                              - integration.read
                              - integration.use
                              - integration.write
                              - integration.manage
                              - change-request.publish
                              - working-branch.write
                              - security-labels.raise
                              - security-labels.lower
                              - session.attach
                              - session.stop
                              - session.surface
                              - session.proxy
                              - session.start
                          uniqueItems: true
                    projects:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            pattern: ^proj-[0-9a-z]{16}$
                          minItems: 1
                          maxItems: 100
                          uniqueItems: true
                  required:
                    - actions
                    - projects
                  additionalProperties: false
              required:
                - name
                - expires_in_days
                - grant
              additionalProperties: false
      responses:
        '201':
          description: The new MCP token
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    $ref: '#/components/schemas/ApiTokenCreated'
                required:
                  - success
                  - data
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/tokens/{tokenId}:
    delete:
      operationId: auth.tokens.revoke
      tags:
        - Auth
      summary: Revoke a personal access token
      description: Deletes the token; API requests using it fail within the
        verification-cache TTL (~30 seconds) on other replicas, immediately on
        this one.
      security: *a4
      parameters:
        - schema:
            type: string
            pattern: ^[0-9A-Z]{26}$
            example: 01HXY0S6GWMBASVAG3PZ7Y2K5T
          required: true
          name: tokenId
          in: path
      responses:
        '200':
          description: Token revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/cli-authorizations:
    post:
      operationId: auth.cli.approve
      x-cli-hidden: true
      tags:
        - Auth
      summary: Approve a CLI login
      description: Creates a one-time code that is bound to the CLI PKCE challenge.
        Requires a browser session. Exchange creates the personal access token.
      security: *a4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callback_uri:
                  type: string
                  maxLength: 300
                  format: uri
                  description: HTTP loopback callback using 127.0.0.1 or [::1], an explicit port,
                    and the exact /callback path.
                  example: http://127.0.0.1:49152/callback
                state:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{32,128}$
                  description: Opaque base64url CSRF state generated by the CLI.
                code_challenge:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{43}$
                  description: Base64url-encoded SHA-256 PKCE challenge generated by the CLI.
                token_name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Name shown in the user's personal access token list.
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 3650
                  description: Lifetime of the personal access token minted during exchange.
              required:
                - callback_uri
                - state
                - code_challenge
                - token_name
                - expires_in_days
              additionalProperties: false
      responses:
        '201':
          description: Loopback callback carrying the one-time authorization code
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      redirect_uri:
                        type: string
                        format: uri
                      expires_at:
                        type: string
                        format: date-time
                    required:
                      - redirect_uri
                      - expires_at
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/cli-authorizations/scoped:
    post:
      operationId: auth.cli.approveScoped
      x-cli-hidden: true
      tags:
        - Auth
      summary: Approve a scoped CLI login
      security: *a4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                callback_uri:
                  type: string
                  maxLength: 300
                  format: uri
                  description: HTTP loopback callback using 127.0.0.1 or [::1], an explicit port,
                    and the exact /callback path.
                  example: http://127.0.0.1:49152/callback
                state:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{32,128}$
                  description: Opaque base64url CSRF state generated by the CLI.
                code_challenge:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{43}$
                  description: Base64url-encoded SHA-256 PKCE challenge generated by the CLI.
                token_name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Name shown in the user's personal access token list.
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 3650
                  description: Lifetime of the personal access token minted during exchange.
                requested_grant:
                  type: object
                  properties:
                    actions:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            enum:
                              - support.request
                              - project.create
                              - admin.access
                              - org-integration.manage
                              - audit.global.read
                              - directory.search
                              - app.read
                              - project.read
                              - project.update
                              - project.delete
                              - project.members.manage
                              - project.events.read
                              - project.alerts.manage
                              - notebook.write
                              - notebook.manage
                              - deep-link.manage
                              - preview.manage
                              - integration.read
                              - integration.use
                              - integration.write
                              - integration.manage
                              - change-request.publish
                              - working-branch.write
                              - security-labels.raise
                              - security-labels.lower
                              - session.attach
                              - session.stop
                              - session.surface
                              - session.proxy
                              - session.start
                          uniqueItems: true
                    projects:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            pattern: ^proj-[0-9a-z]{16}$
                          minItems: 1
                          maxItems: 100
                          uniqueItems: true
                  required:
                    - actions
                    - projects
                  additionalProperties: false
                grant:
                  type: object
                  properties:
                    actions:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            enum:
                              - support.request
                              - project.create
                              - admin.access
                              - org-integration.manage
                              - audit.global.read
                              - directory.search
                              - app.read
                              - project.read
                              - project.update
                              - project.delete
                              - project.members.manage
                              - project.events.read
                              - project.alerts.manage
                              - notebook.write
                              - notebook.manage
                              - deep-link.manage
                              - preview.manage
                              - integration.read
                              - integration.use
                              - integration.write
                              - integration.manage
                              - change-request.publish
                              - working-branch.write
                              - security-labels.raise
                              - security-labels.lower
                              - session.attach
                              - session.stop
                              - session.surface
                              - session.proxy
                              - session.start
                          uniqueItems: true
                    projects:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            pattern: ^proj-[0-9a-z]{16}$
                          minItems: 1
                          maxItems: 100
                          uniqueItems: true
                  required:
                    - actions
                    - projects
                  additionalProperties: false
              required:
                - callback_uri
                - state
                - code_challenge
                - token_name
                - expires_in_days
                - requested_grant
                - grant
              additionalProperties: false
      responses:
        '201':
          description: Loopback callback carrying the one-time authorization code
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      redirect_uri:
                        type: string
                        format: uri
                      expires_at:
                        type: string
                        format: date-time
                    required:
                      - redirect_uri
                      - expires_at
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/cli-device-authorizations:
    post:
      operationId: auth.cli.device.approve
      x-cli-hidden: true
      tags:
        - Auth
      summary: Approve a CLI device login
      description: Approves a short-lived device code for the signed-in user. Requires
        a browser session. Personal access tokens cannot approve device logins.
      security: *a4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_code:
                  type: string
                  minLength: 8
                  maxLength: 20
                token_name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Name shown in the user's personal access token list.
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 3650
                  description: Lifetime of the personal access token minted during exchange.
              required:
                - user_code
                - token_name
                - expires_in_days
              additionalProperties: false
      responses:
        '200':
          description: Device authorization approved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      expires_at:
                        type: string
                        format: date-time
                    required:
                      - expires_at
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/cli-device-authorizations/{userCode}:
    get:
      operationId: auth.cli.device.preview
      x-cli-hidden: true
      tags:
        - Auth
      summary: Preview a CLI device login
      security: *a4
      parameters:
        - schema:
            type: string
            minLength: 8
            maxLength: 20
          required: true
          name: userCode
          in: path
      responses:
        '200':
          description: CLI device authorization type and requested grant
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    oneOf:
                      - type: object
                        properties:
                          status:
                            type: string
                            enum:
                              - legacy
                          expires_at:
                            type: string
                            format: date-time
                        required:
                          - status
                          - expires_at
                      - type: object
                        properties:
                          status:
                            type: string
                            enum:
                              - scoped
                          requested_grant:
                            type: object
                            properties:
                              actions:
                                anyOf:
                                  - type: string
                                    enum:
                                      - '*'
                                  - type: array
                                    items:
                                      type: string
                                      enum:
                                        - support.request
                                        - project.create
                                        - admin.access
                                        - org-integration.manage
                                        - audit.global.read
                                        - directory.search
                                        - app.read
                                        - project.read
                                        - project.update
                                        - project.delete
                                        - project.members.manage
                                        - project.events.read
                                        - project.alerts.manage
                                        - notebook.write
                                        - notebook.manage
                                        - deep-link.manage
                                        - preview.manage
                                        - integration.read
                                        - integration.use
                                        - integration.write
                                        - integration.manage
                                        - change-request.publish
                                        - working-branch.write
                                        - security-labels.raise
                                        - security-labels.lower
                                        - session.attach
                                        - session.stop
                                        - session.surface
                                        - session.proxy
                                        - session.start
                                    uniqueItems: true
                              projects:
                                anyOf:
                                  - type: string
                                    enum:
                                      - '*'
                                  - type: array
                                    items:
                                      type: string
                                      pattern: ^proj-[0-9a-z]{16}$
                                    minItems: 1
                                    maxItems: 100
                                    uniqueItems: true
                            required:
                              - actions
                              - projects
                            additionalProperties: false
                          expires_at:
                            type: string
                            format: date-time
                        required:
                          - status
                          - requested_grant
                          - expires_at
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/cli-device-authorizations/scoped:
    post:
      operationId: auth.cli.device.approveScoped
      x-cli-hidden: true
      tags:
        - Auth
      summary: Approve a scoped CLI device login
      security: *a4
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_code:
                  type: string
                  minLength: 8
                  maxLength: 20
                token_name:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: Name shown in the user's personal access token list.
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 3650
                  description: Lifetime of the personal access token minted during exchange.
                grant:
                  type: object
                  properties:
                    actions:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            enum:
                              - support.request
                              - project.create
                              - admin.access
                              - org-integration.manage
                              - audit.global.read
                              - directory.search
                              - app.read
                              - project.read
                              - project.update
                              - project.delete
                              - project.members.manage
                              - project.events.read
                              - project.alerts.manage
                              - notebook.write
                              - notebook.manage
                              - deep-link.manage
                              - preview.manage
                              - integration.read
                              - integration.use
                              - integration.write
                              - integration.manage
                              - change-request.publish
                              - working-branch.write
                              - security-labels.raise
                              - security-labels.lower
                              - session.attach
                              - session.stop
                              - session.surface
                              - session.proxy
                              - session.start
                          uniqueItems: true
                    projects:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            pattern: ^proj-[0-9a-z]{16}$
                          minItems: 1
                          maxItems: 100
                          uniqueItems: true
                  required:
                    - actions
                    - projects
                  additionalProperties: false
              required:
                - user_code
                - token_name
                - expires_in_days
                - grant
              additionalProperties: false
      responses:
        '200':
          description: Device authorization approved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      expires_at:
                        type: string
                        format: date-time
                    required:
                      - expires_at
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/oauth-authorizations/{id}:
    get:
      operationId: auth.oauth.preview
      x-cli-hidden: true
      tags:
        - Auth
      security: *a4
      parameters:
        - schema:
            type: string
            pattern: ^[0-9A-Z]{26}$
          required: true
          name: id
          in: path
      responses:
        '200':
          description: OAuth request
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      client_name:
                        type: string
                      client_uri:
                        type: string
                      redirect_uri:
                        type: string
                      scopes:
                        type: array
                        items:
                          type: string
                      expires_at:
                        type: string
                        format: date-time
                    required:
                      - client_name
                      - redirect_uri
                      - scopes
                      - expires_at
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/oauth-authorizations/{id}/approve:
    post:
      operationId: auth.oauth.approve
      x-cli-hidden: true
      tags:
        - Auth
      security: *a4
      parameters:
        - schema:
            type: string
            pattern: ^[0-9A-Z]{26}$
          required: true
          name: id
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                grant:
                  type: object
                  properties:
                    actions:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            enum:
                              - support.request
                              - project.create
                              - admin.access
                              - org-integration.manage
                              - audit.global.read
                              - directory.search
                              - app.read
                              - project.read
                              - project.update
                              - project.delete
                              - project.members.manage
                              - project.events.read
                              - project.alerts.manage
                              - notebook.write
                              - notebook.manage
                              - deep-link.manage
                              - preview.manage
                              - integration.read
                              - integration.use
                              - integration.write
                              - integration.manage
                              - change-request.publish
                              - working-branch.write
                              - security-labels.raise
                              - security-labels.lower
                              - session.attach
                              - session.stop
                              - session.surface
                              - session.proxy
                              - session.start
                          uniqueItems: true
                    projects:
                      anyOf:
                        - type: string
                          enum:
                            - '*'
                        - type: array
                          items:
                            type: string
                            pattern: ^proj-[0-9a-z]{16}$
                          minItems: 1
                          maxItems: 100
                          uniqueItems: true
                  required:
                    - actions
                    - projects
                  additionalProperties: false
                token_name:
                  type: string
                  minLength: 1
                  maxLength: 100
                expires_in_days:
                  type: integer
                  minimum: 1
                  maximum: 90
              required:
                - grant
                - expires_in_days
              additionalProperties: false
      responses:
        '200':
          description: OAuth redirect
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      redirect_uri:
                        type: string
                    required:
                      - redirect_uri
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/me/oauth-authorizations/{id}/deny:
    post:
      operationId: auth.oauth.deny
      x-cli-hidden: true
      tags:
        - Auth
      security: *a4
      parameters:
        - schema:
            type: string
            pattern: ^[0-9A-Z]{26}$
          required: true
          name: id
          in: path
      responses:
        '200':
          description: OAuth redirect
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      redirect_uri:
                        type: string
                    required:
                      - redirect_uri
                required:
                  - success
                  - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Resource limit reached
          headers:
            Retry-After:
              schema:
                type: string
                description: Seconds to wait before retrying.
                example: '5'
              required: true
              description: Seconds to wait before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
webhooks: {}
