openapi: 3.0.3
info:
  title: vellum-assistant-platform API
  version: 1.0.0 (v1)
  description: Documentation of API endpoints of vellum-assistant-platform
paths:
  /v1/admin/assistants/{assistant_id}/doctor/sessions/:
    post:
      operationId: admin_assistants_doctor_sessions_create
      description: Create a Doctor session for any hosted assistant as a staff user.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - admin
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DoctorSessionCreateResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/admin/assistants/{assistant_id}/doctor/sessions/{session_id}/:
    delete:
      operationId: admin_assistants_doctor_sessions_destroy
      description: Delete an upstream Doctor session through the admin scope.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - admin
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '204':
          description: No response body
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/admin/assistants/{assistant_id}/doctor/sessions/{session_id}/events/:
    get:
      operationId: admin_assistants_doctor_sessions_events_retrieve
      description: Proxy the Doctor SSE event stream for staff users.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: query
        name: format
        schema:
          type: string
          enum:
          - event-stream
          - json
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - admin
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            text/event-stream:
              schema:
                type: string
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/admin/assistants/{assistant_id}/doctor/sessions/{session_id}/messages/:
    post:
      operationId: admin_assistants_doctor_sessions_messages_create
      description: Send a message to an admin-created or existing Doctor session.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - admin
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DoctorSessionMessageRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DoctorSessionMessageRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DoctorSessionMessageRequestRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '202':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/:
    get:
      operationId: assistants_list
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: query
        name: hosting
        schema:
          type: string
          enum:
          - all
          - local
          - platform
          default: platform
        description: Filter assistants by hosting mode. 'platform' (default) returns
          only platform-managed assistants. 'local' returns only self-hosted local
          assistants. 'all' returns both.
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAssistantList'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/backups/:
    get:
      operationId: assistants_backups_retrieve
      description: List backups and trigger manual point-in-time backups for an assistant.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    post:
      operationId: assistants_backups_create
      description: Trigger a manual point-in-time backup for the assistant.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/backups/{snapshot_name}/restore/:
    post:
      operationId: assistants_backups_restore_create
      description: |-
        Restore an assistant from a named backup snapshot.

        Enforces ownership; the shared restore flow verifies the snapshot
        belongs to the requested assistant by listing backups first, and
        never attempts the restore if the snapshot is absent from the list.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: snapshot_name
        schema:
          type: string
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/doctor/history/:
    get:
      operationId: assistants_doctor_history_list
      description: |-
        List persisted Doctor sessions for an assistant, newest first.

        Sessions are scoped to the assistant identified by ``assistant_id``
        (ownership/auth is enforced by ``_DoctorAPIView`` via
        ``self.get_object()``). Results are ordered by
        ``last_message_at DESC NULLS LAST, -created`` so that the most
        recently active session appears first and sessions that have
        never received a message sink to the bottom (PostgreSQL defaults
        ``DESC`` to ``NULLS FIRST``, which would otherwise float empty
        sessions above active ones). An annotated ``message_count`` is
        included on each row so list views do not need a per-row query
        to display the message tally.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDoctorSessionListList'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/doctor/history/{doctor_session_id}/:
    get:
      operationId: assistants_doctor_history_retrieve
      description: |-
        Return a single persisted Doctor session with its message ledger.

        Looks up the session by Django UUID PK *and* by assistant
        ownership; lookups across assistants always return 404, never 200.
        Messages are returned in ``sequence`` order.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: doctor_session_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DoctorSessionDetail'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/doctor/sessions/:
    post:
      operationId: assistants_doctor_sessions_create
      description: |-
        Create a new Doctor diagnostic session.

        Calls the Doctor service to create a session and returns the session ID.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DoctorSessionCreateResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/doctor/sessions/{session_id}/:
    delete:
      operationId: assistants_doctor_sessions_destroy
      description: Delete a Doctor session.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '204':
          description: No response body
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/doctor/sessions/{session_id}/events/:
    get:
      operationId: assistants_doctor_sessions_events_retrieve
      description: Proxy the Doctor SSE event stream for a session.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: query
        name: format
        schema:
          type: string
          enum:
          - event-stream
          - json
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            text/event-stream:
              schema:
                type: string
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/doctor/sessions/{session_id}/messages/:
    post:
      operationId: assistants_doctor_sessions_messages_create
      description: Send a user message to an active Doctor session.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DoctorSessionMessageRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DoctorSessionMessageRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DoctorSessionMessageRequestRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '202':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/doctor/sessions/{session_id}/user-outcome/:
    post:
      operationId: assistants_doctor_sessions_user_outcome_create
      description: |-
        Record whether the Doctor solved the user's problem.

        Writes only to the persisted Django row (no upstream Doctor call),
        so it works for live sessions and for sessions that already ended.
        Idempotent: the latest answer wins.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DoctorSessionUserOutcomeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DoctorSessionUserOutcomeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DoctorSessionUserOutcomeRequestRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DoctorSessionUserOutcomeResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/domains/:
    get:
      operationId: assistants_domains_list
      description: List, create, and delete domains for a specific assistant.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAssistantDomainList'
          description: ''
      x-vellum-api-clients:
      - platform
    post:
      operationId: assistants_domains_create
      description: List, create, and delete domains for a specific assistant.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAssistantDomainRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateAssistantDomainRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateAssistantDomainRequest'
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantDomain'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/domains/{id}/:
    delete:
      operationId: assistants_domains_destroy
      description: List, create, and delete domains for a specific assistant.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '204':
          description: No response body
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/domains/{id}/provision/:
    post:
      operationId: assistants_domains_provision_create
      description: Provision an existing managed domain with the email provider and
        DNS.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainVerificationStatus'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/domains/{id}/verification-status/:
    get:
      operationId: assistants_domains_verification_status_retrieve
      description: Return the current Resend verification status of the domain.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainVerificationStatus'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/email-addresses/:
    get:
      operationId: assistants_email_addresses_list
      description: List, create, and delete email addresses for a specific assistant.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAssistantEmailAddressList'
          description: ''
      x-vellum-api-clients:
      - platform
    post:
      operationId: assistants_email_addresses_create
      description: List, create, and delete email addresses for a specific assistant.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailAddressRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateEmailAddressRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateEmailAddressRequest'
        required: true
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantEmailAddress'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/email-addresses/{id}/:
    delete:
      operationId: assistants_email_addresses_destroy
      description: List, create, and delete email addresses for a specific assistant.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '204':
          description: No response body
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/email-addresses/{id}/status/:
    get:
      operationId: assistants_email_addresses_status_retrieve
      description: Return email address info and usage statistics.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAddressStatus'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/emails/:
    get:
      operationId: assistants_emails_list
      description: List and retrieve email messages for a specific assistant.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: query
        name: direction
        schema:
          type: string
          enum:
          - inbound
          - outbound
        description: Filter by message direction.
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      - in: query
        name: since
        schema:
          type: string
          format: date-time
        description: Only return messages created at or after this ISO 8601 datetime.
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - SDKCompatibleAssistantKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEmailMessageList'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/handle-available/:
    get:
      operationId: assistants_handle_available_retrieve
      description: |-
        Live availability check used by the settings UI.

        ``GET /v1/assistants/{assistant_id}/handle-available/?handle=foo``

        Response shape (always 200 even when unavailable — the client renders
        inline state, not a global error):

        .. code-block:: json

            {"available": true,  "code": null,        "message": null}
            {"available": false, "code": "too_short", "message": "Must be at least 3 characters."}
            {"available": false, "code": "taken",     "message": "This handle is already taken."}

        A 429 is returned only when the per-user rate cap is exceeded — the
        request was not evaluated.

        Authorization: the URL is scoped under ``/v1/assistants/{assistant_id}/``
        so the standard ownership filter in :class:`_AssistantAPIView` already
        enforces that the caller can see this assistant. We exclude the
        assistant's own current handle from the "taken" check so the UI can
        treat the existing value as available (useful for re-confirming without
        a save).
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: query
        name: handle
        schema:
          type: string
        description: Candidate handle (will be lowercased before check).
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantHandleAvailability'
          description: ''
        '400':
          description: No response body
        '429':
          description: No response body
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/live-activity/tokens/:
    post:
      operationId: assistants_live_activity_tokens_upsert
      description: |-
        Register the ActivityKit update token for a running voice session.

        Called by the web layer inside the iOS WebView the moment ActivityKit
        mints a token for the Live Activity it just started, and again whenever
        that token rotates. Session-authenticated like its device-token sibling —
        the requesting user must own the assistant in the URL.

        The row is replaced rather than accumulated: a token identifies one
        activity, and the plugin holds at most one at a time, so re-registering
        under the same ``(user, token)`` is an update of the same activity.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LiveActivityTokenUpsertRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LiveActivityTokenUpsertRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LiveActivityTokenUpsertRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveActivityTokenUpsert'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/live-activity/tokens/{token}/:
    delete:
      operationId: assistants_live_activity_tokens_delete
      description: |-
        Deregister a Live Activity token when its session ends.

        Idempotent — 204 whether or not the row existed. Best-effort by nature:
        the client calls this as the session ends, which is precisely when the app
        may be backgrounded, suspended, or already gone. That is why the row also
        carries ``expires_at``; this endpoint is the fast path, not the guarantee.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: token
        schema:
          type: string
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '204':
          description: No response body
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/maintenance-mode/enter/:
    post:
      operationId: assistants_maintenance_mode_enter_create
      description: |-
        Enter maintenance mode for the given assistant.

        Pauses the assistant StatefulSet, hands the workspace PVC off to a debug
        pod, and persists ``maintenance_mode_enabled=True`` on the Assistant row
        only after vembda confirms the handoff succeeded.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/maintenance-mode/exit/:
    post:
      operationId: assistants_maintenance_mode_exit_create
      description: |-
        Exit maintenance mode for the given assistant.

        Tears down the debug pod, returns the workspace PVC to the assistant
        StatefulSet, and clears ``maintenance_mode_enabled`` only after vembda
        confirms the StatefulSet handoff is complete.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/managed-search-proxy/{provider}/:
    post:
      operationId: assistants_managed_search_proxy_create
      description: Proxy a managed search-provider API request through Vellum. The
        caller supplies the provider-shaped request path/query/body; Vellum validates
        the route, checks billing eligibility, strips caller credentials, injects
        managed provider credentials, and returns the upstream response envelope.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: provider
        schema:
          type: string
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagedSearchProxyRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ManagedSearchProxyRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ManagedSearchProxyRequestRequest'
        required: true
      security:
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSearchProxyResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSearchProxyErrorResponse'
          description: ''
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSearchProxyErrorResponse'
          description: ''
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSearchProxyErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSearchProxyErrorResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSearchProxyErrorResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/managed-speech/stt/transcribe/:
    post:
      operationId: assistants_managed_speech_stt_transcribe_create
      description: Transcribe pre-recorded audio through Vellum's managed Deepgram
        speech-to-text proxy. Vellum validates the request, checks billing eligibility,
        calls Deepgram with managed credentials, bills the transcribed duration, and
        returns the transcript. Pass 'language' to name the spoken language (a BCP-47
        code, or 'multi' for code-switching); omitting it decodes as English rather
        than detecting the language.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagedSpeechSTTRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ManagedSpeechSTTRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ManagedSpeechSTTRequestRequest'
        required: true
      security:
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechSTTResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/managed-speech/tts/synthesize/:
    post:
      operationId: assistants_managed_speech_tts_synthesize_create
      description: Synthesize speech audio from text through Vellum's managed text-to-speech
        proxy. Vellum validates the request, checks billing eligibility, calls the
        speech provider for the selected voice with managed credentials, bills the
        input character count, and returns the synthesized audio bytes.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManagedSpeechTTSRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ManagedSpeechTTSRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ManagedSpeechTTSRequestRequest'
        required: true
      security:
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          description: Synthesized audio
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechErrorResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/managed-speech/tts/voices/:
    get:
      operationId: assistants_managed_speech_tts_voices_retrieve
      description: List the voices offered by Vellum's managed text-to-speech, in
        display order, with the platform's default voice. Only voices that are currently
        priced (and therefore usable via the synthesize endpoint) are returned.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechTTSVoicesResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/oauth/{provider}/start/:
    post:
      operationId: assistants_oauth_start_create
      description: |-
        Start an OAuth authorization flow for a given provider.

        The requesting user must own the assistant or belong to the same
        organization.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: provider
        schema:
          type: string
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthStartRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OAuthStartRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OAuthStartRequestRequest'
      security:
      - AssistantAPIKey: []
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthStartResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/oauth/connections/:
    get:
      operationId: assistants_oauth_connections_list
      description: |-
        List all OAuth connections for the current user on an assistant.

        Returns connection state (active/expired/revoked/error) and account label
        for each connected provider credential.

        Supports both session auth (webapp) and assistant API key auth (CLI/daemon).
      parameters:
      - in: query
        name: account_identifier
        schema:
          type: string
        description: Filter connections by provider account ID.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: query
        name: provider
        schema:
          type: string
          enum:
          - airtable
          - asana
          - calendly
          - discord
          - dropbox
          - eventbrite
          - figma
          - github
          - google
          - hubspot
          - linear
          - monday
          - notion
          - outlook
          - quickbooks
          - salesforce
          - shopify
          - stripe_link
          - todoist
          - twitter
        description: Filter connections by OAuth provider.
      - in: query
        name: status
        schema:
          type: string
          enum:
          - ACTIVE
          - ALL
          - ERROR
          - REVOKED
        description: Filter by connection status. Defaults to ACTIVE. Use ALL to return
          all statuses.
      tags:
      - assistants
      security:
      - AssistantAPIKey: []
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OAuthConnection'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/oauth/connections/{connection_id}/disconnect/:
    post:
      operationId: assistants_oauth_disconnect_by_connection_create
      description: |-
        Disconnect (revoke) a specific OAuth connection by its ID.

        Marks the connection status as REVOKED. Optionally attempts to revoke
        the upstream token with the provider.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: connection_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - AssistantAPIKey: []
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthDisconnectResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/owner-consent/:
    get:
      operationId: assistants_owner_consent
      description: GET /v1/assistants/<uuid:assistant_id>/owner-consent/
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OwnerConsent'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/push-tokens/:
    post:
      operationId: assistants_push_tokens_upsert
      description: |-
        Register or update a device push token for the assistant owner.

        Authenticates via either:

        - **Session** (web / iOS WebView): the requesting user must own the
          ``assistant_id`` referenced in the URL.  This is the path used by
          the `web/src/lib/push/register.ts` Capacitor flow on iOS.
        - **AssistantAPIKey** (external SDK): the key must match the URL
          ``assistant_id``; the registered user is ``assistant.created_by``.

        Both paths converge on the same ``(user, token, bundle_id)`` upsert.
        The ``last_seen_at`` timestamp is updated on every successful call.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DevicePushTokenUpsertRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DevicePushTokenUpsertRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DevicePushTokenUpsertRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DevicePushTokenUpsert'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/push-tokens/{token}/:
    delete:
      operationId: assistants_push_tokens_delete
      description: |-
        Remove a device push token for the assistant owner.

        Idempotent — returns 204 even if the token does not exist for the
        given ``(user, token, bundle_id)`` triple.

        Authenticates via either session or AssistantAPIKey (see
        :class:`DevicePushTokenUpsertView` docstring).  The web/iOS WebView
        logout path in ``web/src/lib/auth.tsx`` calls this BEFORE
        ``allauthLogout()`` so the session cookie is still valid.

        The ``bundle_id`` query parameter is REQUIRED so the delete is scoped
        to a single (user, token, bundle_id) row.  Without it, a user who
        legitimately had the same token registered under two app bundles
        (e.g. main app and a TestFlight build) would lose both registrations
        on a single logout, which would silently disable push for the other
        app.  The model's unique constraint is ``(user, token, bundle_id)``,
        so the delete filter must match all three to be safe.
      parameters:
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: query
        name: bundle_id
        schema:
          type: string
        description: iOS app bundle identifier the token was registered under.  Required
          so the delete is scoped to a single (user, token, bundle_id) row.
        required: true
      - in: path
        name: token
        schema:
          type: string
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '204':
          description: No response body
        '400':
          description: No response body
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/release-channel/:
    get:
      operationId: assistants_release_channel_retrieve
      description: Read release-channel state and preview safety backups for an assistant.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReleaseChannelStatus'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/release-channel/preview/opt-in/:
    post:
      operationId: assistants_release_channel_preview_opt_in_create
      description: Switch a stable-channel assistant to the preview release channel.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewChannelOptInResult'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '504':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/release-channel/preview/opt-out/:
    post:
      operationId: assistants_release_channel_preview_opt_out_create
      description: Switch a preview-channel assistant back to the stable release channel.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewChannelOptOutRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PreviewChannelOptOutRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PreviewChannelOptOutRequestRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewChannelOptOutResult'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/system-events/:
    get:
      operationId: assistants_system_events_list
      description: |-
        List retained system events for an assistant, newest first.

        Only the owner of the assistant can access this endpoint.  Events older
        than the retention window (``ASSISTANT_SYSTEM_EVENT_RETENTION_DAYS``) are
        never returned.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAssistantSystemEventList'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/terminal/sessions/:
    post:
      operationId: assistants_terminal_sessions_create
      description: |-
        Create a new terminal session for the given assistant.

        Proxies POST /v1/assistants/{id}/terminal/sessions/ to vembda which spawns
        a PTY inside the assistant pod and returns the new session ID. Returns
        429 when the per-user creation rate is exceeded.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: {}
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: {}
          multipart/form-data:
            schema:
              type: object
              additionalProperties: {}
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/terminal/sessions/{session_id}/:
    delete:
      operationId: assistants_terminal_sessions_destroy
      description: |-
        Close and clean up a terminal session.

        Proxies DELETE /v1/assistants/{id}/terminal/sessions/{session_id}/ to
        vembda which terminates the PTY process and frees the session slot.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/terminal/sessions/{session_id}/input/:
    post:
      operationId: assistants_terminal_sessions_input_create
      description: |-
        Send keyboard input to an active terminal session.

        Proxies POST /v1/assistants/{id}/terminal/sessions/{session_id}/input/ to
        vembda which writes the data bytes into the PTY stdin.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: {}
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: {}
          multipart/form-data:
            schema:
              type: object
              additionalProperties: {}
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{assistant_id}/terminal/sessions/{session_id}/resize/:
    post:
      operationId: assistants_terminal_sessions_resize_create
      description: |-
        Notify vembda of a terminal window resize event.

        Proxies POST /v1/assistants/{id}/terminal/sessions/{session_id}/resize/ to
        vembda which forwards the new dimensions to the PTY.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: assistant_id
        schema:
          type: string
          format: uuid
        required: true
      - in: path
        name: session_id
        schema:
          type: string
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: {}
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: {}
          multipart/form-data:
            schema:
              type: object
              additionalProperties: {}
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/:
    get:
      operationId: assistants_retrieve
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
          description: ''
      x-vellum-api-clients:
      - platform
    patch:
      operationId: assistants_partial_update
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedAssistantPartialUpdateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedAssistantPartialUpdateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedAssistantPartialUpdateRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
          description: ''
        '400':
          description: No response body
        '409':
          description: No response body
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/access-consent/:
    get:
      operationId: assistants_access_consent_detail_read
      description: Read or update the owner's consent for admin daemon-log access.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessConsent'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    patch:
      operationId: assistants_access_consent_detail_partial_update
      description: Read or update the owner's consent for admin daemon-log access.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedAccessConsentRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedAccessConsentRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedAccessConsentRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessConsent'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/activate/:
    post:
      operationId: assistants_activate_create
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/connection-status/:
    post:
      operationId: assistants_connection_status
      description: |-
        Return the live reachability of the assistant's runtime pod.

        The web frontend polls this endpoint to distinguish a pod that is
        waking from idle-sleep (transient) from one that is genuinely
        unreachable (surface an error).
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionStatus'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/debug-bundle-upload-url/:
    post:
      operationId: assistants_debug_bundle_upload_url_create
      description: Returns a signed PUT URL the assistant uploads a debug-profile
        .vbundle to, so Vellum staff can open it on a debug clone. Only while the
        owner's staff access grant is active. Bundles are deleted after seven days.
      summary: Mint a signed upload URL for a debug bundle
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebugBundleUploadUrl'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/operational/status/:
    get:
      operationId: assistants_operational_status_detail_read
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationalStatus'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/resize/:
    post:
      operationId: assistants_resize
      description: |-
        Resize an assistant's machine size and/or workspace PVC.

        Pro-gated and bounded by the org's purchased machine/storage tiers.
        Either dimension may be supplied independently; storage grows only
        (never shrinks). The actual vembda mechanics live in the policy-free
        ``resize_assistant`` helper — this view owns the entitlement and
        per-tier ceiling policy.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantResizeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AssistantResizeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AssistantResizeRequestRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantResizeResponse'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssistantResize403'
          description: Forbidden. Either the org lacks the Pro entitlement (``{detail}``)
            or the request exceeds a purchased tier (``{error, max_machine_tier |
            max_storage_gib}``).
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/restart/:
    post:
      operationId: assistants_restart_detail_create
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AssistantRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AssistantRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/retire/:
    delete:
      operationId: assistants_retire_detail_destroy
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      - in: query
        name: successor_assistant_id
        schema:
          type: string
          format: uuid
        description: Optional assistant that inherits the retiring assistant's managed
          OAuth connections, e.g. the target of a teleport. Must be a live assistant
          owned by the caller in the same organization. The rows are moved before
          the retiring assistant's credentials are revoked.
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '204':
          description: No response body
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/rollback/:
    post:
      operationId: assistants_rollback_detail_create
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RollbackRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RollbackRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/RollbackRequestRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RollbackResult'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/sleep-policy/:
    get:
      operationId: assistants_sleep_policy_detail_read
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SleepPolicy'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    patch:
      operationId: assistants_sleep_policy_detail_partial_update
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedSleepPolicyRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedSleepPolicyRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedSleepPolicyRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SleepPolicy'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/upgrade/:
    post:
      operationId: assistants_upgrade_detail_create
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpgradeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpgradeRequestRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpgradeResult'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/upgrade-policy/:
    get:
      operationId: assistants_upgrade_policy_detail_read
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpgradePolicy'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    patch:
      operationId: assistants_upgrade_policy_detail_partial_update
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedUpgradePolicyRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedUpgradePolicyRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedUpgradePolicyRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpgradePolicy'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/{id}/upgrade-status/:
    get:
      operationId: assistants_upgrade_status_detail_read
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpgradeStatus'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/access-consent/:
    get:
      operationId: assistants_access_consent_retrieve
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessConsent'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    patch:
      operationId: assistants_access_consent_partial_update
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedAccessConsentRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedAccessConsentRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedAccessConsentRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessConsent'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/active/:
    get:
      operationId: assistants_active_retrieve
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - assistants
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/hatch/:
    post:
      operationId: assistants_hatch_create
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: query
        name: mode
        schema:
          type: string
          enum:
          - create
          - ensure
          default: ensure
        description: '`ensure` returns an existing managed assistant when possible.
          `create` creates an additional assistant when multi-assistant hatching is
          enabled.'
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HatchAssistantRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/HatchAssistantRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/HatchAssistantRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Assistant'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/telemetry/ingest/:
    post:
      operationId: assistants_telemetry_ingest_create
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelemetryIngestRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TelemetryIngestRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TelemetryIngestRequestRequest'
        required: true
      security:
      - SDKCompatibleAssistantKey: []
      - XSessionTokenAuth: []
      - cookieAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryIngestResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/assistants/upgrade/:
    post:
      operationId: assistants_upgrade_create
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - assistants
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpgradeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpgradeRequestRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpgradeResult'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: {}
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/auth/live-voice-token/:
    post:
      operationId: auth_live_voice_token_create
      description: |-
        Mint a short-lived, single-use live-voice WS token for the web SPA.

        Requires session auth + CSRF (enforced by DRF ``SessionAuthentication`` for
        this unsafe POST) and the ``Vellum-Organization-Id`` header. The caller
        must own the requested assistant within the resolved organization.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - auth
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LiveVoiceTokenRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LiveVoiceTokenRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LiveVoiceTokenRequestRequest'
        required: true
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveVoiceTokenResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/feature-flags/client-flag-values/:
    get:
      operationId: feature_flags_client_flag_values_retrieve
      description: |-
        Return evaluated feature flag values for the current user.

        When session-authenticated with the ``Vellum-Organization-Id`` header,
        flags are evaluated against the user/org LD context. Unauthenticated
        requests receive flags evaluated against an anonymous LD context.
      parameters:
      - in: header
        name: Vellum-Device-Id
        schema:
          type: string
        description: Stable device identifier for per-device flag targeting.
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - feature-flags
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientFeatureFlagsResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/feedback/:
    post:
      operationId: feedback_create
      tags:
      - feedback
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackIngestRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/FeedbackIngestRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FeedbackIngestRequestRequest'
        required: true
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      - {}
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackIngestResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/feedback/assistant/:
    post:
      operationId: feedback_assistant_create
      description: |-
        A report filed by an assistant under its own API key.

        Everything about the submitter comes from the key: the assistant, its
        organization, and its owner account's email as the contact. ``user``
        stays unset, because the assistant is the submitter and its owner is not.
        The public ``FeedbackIngestView`` is untouched by this path.
      tags:
      - feedback
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssistantFeedbackIngestRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AssistantFeedbackIngestRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AssistantFeedbackIngestRequestRequest'
        required: true
      security:
      - AssistantAPIKey: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackIngestResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/managed-speech/tts/voices/:
    get:
      operationId: managed_speech_tts_voices_retrieve
      description: List the voices offered by Vellum's managed text-to-speech, in
        display order, with the platform's default voice. Only voices that are currently
        priced (and therefore usable via the synthesize endpoint) are returned.
      tags:
      - managed-speech
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedSpeechTTSVoicesResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/:
    get:
      operationId: organizations_list
      description: APIs to manage organizations for an authenticated User.
      parameters:
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedOrganizationReadList'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/auto-top-up/:
    get:
      operationId: organizations_billing_auto_top_up_retrieve
      description: Return the current auto top-up configuration for the org.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpConfigResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    put:
      operationId: organizations_billing_auto_top_up_update
      description: Create or update the auto top-up configuration for the org.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoTopUpConfigRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AutoTopUpConfigRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AutoTopUpConfigRequestRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpConfigResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/auto-top-up/confirm-setup-intent/:
    post:
      operationId: organizations_billing_auto_top_up_confirm_setup_intent_create
      description: |-
        Persist the payment method from a just-confirmed SetupIntent.

        Call this immediately after Stripe's client-side ``confirmSetup``
        resolves so the saved card is readable on the very next GET, instead of
        waiting on the ``setup_intent.succeeded`` webhook. The webhook remains
        the durable fallback; whichever lands second is a no-op.

        Returns the same payload as ``GET .../auto-top-up/``.

        The caller's id is never trusted on its own: the SetupIntent is re-read
        from Stripe and must be tagged ``metadata.auto_top_up=true``, carry this
        org's ``metadata.organization_id``, sit on this org's Stripe customer,
        and be ``succeeded`` with a payment method attached.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoTopUpConfirmSetupIntentRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AutoTopUpConfirmSetupIntentRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AutoTopUpConfirmSetupIntentRequestRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpConfigResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/auto-top-up/disable/:
    post:
      operationId: organizations_billing_auto_top_up_disable_create
      description: Disable automatic top-ups for the org. Preserves saved settings.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpDisableResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/auto-top-up/history/:
    get:
      operationId: organizations_billing_auto_top_up_history_retrieve
      description: List recent auto top-up attempts for the org (most recent first,
        max 20).
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpHistoryResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/auto-top-up/remove-payment-method/:
    post:
      operationId: organizations_billing_auto_top_up_remove_payment_method_create
      description: |-
        Remove the saved auto top-up payment method and disable automatic top-ups.

        Clears ``AutoTopUpConfig.stripe_payment_method_id`` and sets
        ``enabled=False`` so no future ``attempt_charge`` can fire against
        the removed card.

        The Stripe PaymentMethod object is intentionally **not** detached from
        the customer — it may be referenced by the Pro plan subscription.
        Callers that need to fully remove the card from Stripe can use
        ``PaymentMethodViewSet.destroy`` separately.

        No-op (returns the same disabled payload) when no config row exists or
        the config already has no PM saved.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpDisableResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/auto-top-up/setup-intent/:
    post:
      operationId: organizations_billing_auto_top_up_setup_intent_create
      description: |-
        Create a Stripe SetupIntent for saving an off-session auto-top-up payment method.

        The SetupIntent is tagged with ``metadata.auto_top_up=true`` so the
        ``setup_intent.succeeded`` webhook handler can distinguish auto-top-up
        payment-method saves from manual-top-up saves and persist the resulting
        payment method onto ``AutoTopUpConfig.stripe_payment_method_id``.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoTopUpSetupIntentResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/checkout-bonus/:
    get:
      operationId: organizations_billing_checkout_bonus_retrieve
      description: |-
        Return whether the organization may claim the bonus, and its amount.

        Read-only — never creates or modifies billing state. The eligibility
        check may perform outbound Stripe reads to verify abandonment.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutBonusEligibilityResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    post:
      operationId: organizations_billing_checkout_bonus_create
      description: Claim the one-time bonus; the service re-verifies eligibility.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutBonusClaimResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/daily-credit-limit/:
    get:
      operationId: organizations_billing_daily_credit_limit_retrieve
      description: Return the daily limit (or null) and the read-only spend counter.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyCreditLimitResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    put:
      operationId: organizations_billing_daily_credit_limit_update
      description: Set (or clear, via null) the organization's daily credit limit.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DailyCreditLimitRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DailyCreditLimitRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DailyCreditLimitRequestRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyCreditLimitResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/daily-credit-limit/skip-today/:
    post:
      operationId: organizations_billing_daily_credit_limit_skip_today_create
      description: |-
        Skip the daily limit for the rest of the current UTC day.

        Idempotent: skipping an already-skipped day rewrites the same bucket.
        Rejected with 400 when no limit is configured, so the client can never
        record a skip that has nothing to suspend.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyCreditLimitResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    delete:
      operationId: organizations_billing_daily_credit_limit_skip_today_destroy
      description: Restore the daily limit immediately, ending an active skip early.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DailyCreditLimitResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/free-tier-daily-limit/:
    get:
      operationId: organizations_billing_free_tier_daily_limit_retrieve
      description: Return enrollment, enforcement, and today's usage-credit spend.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FreeTierDailyLimitResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/invoices/:
    get:
      operationId: organizations_billing_invoices_retrieve
      description: Return one page of the org's Stripe invoices, newest first.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: query
        name: starting_after
        schema:
          type: string
        description: 'Cursor: return invoices older than the invoice with this id
          (from the previous page''s last entry).'
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceListResponse'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailResponse'
          description: Invalid or expired starting_after cursor.
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/invoices/download/:
    get:
      operationId: organizations_billing_invoices_download_retrieve
      description: |-
        Download all of the org's invoice PDFs as a single zip archive.

        Stripe's ``invoice_pdf`` URLs don't serve CORS headers, so the
        browser can't fetch and zip them client-side — the archive has to
        be assembled server-side.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/zip:
              schema:
                type: string
                format: binary
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/low-balance-alert/:
    get:
      operationId: organizations_billing_low_balance_alert_retrieve
      description: Return the per-org override (or null), effective, and default values.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LowBalanceAlertResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    put:
      operationId: organizations_billing_low_balance_alert_update
      description: Set (or clear, via null) the per-org low-balance threshold override.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LowBalanceAlertRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/LowBalanceAlertRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/LowBalanceAlertRequestRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LowBalanceAlertResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/plans/:
    get:
      operationId: organizations_billing_plans_retrieve
      description: Return the Pro plan catalog (Base + Pro). Read-only, no Stripe
        I/O.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanListResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/portal-session/:
    post:
      operationId: organizations_billing_portal_session_create
      description: POST /v1/organizations/billing/portal-session/ → {portal_url}.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPortalSessionResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/:
    get:
      operationId: organizations_billing_subscription_retrieve
      description: GET /…/subscription/ → current state. POST upgrade action.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/cancel/:
    post:
      operationId: organizations_billing_subscription_cancel_create
      description: 'Cancel the org''s Pro subscription at the end of the current billing
        period — the server-side equivalent of cancelling through the Stripe Customer
        Portal. The subscription (and its entitlements) stays active until the period
        ends, when Stripe terminates it and the org returns to the Base plan; no refund
        or proration is issued. Idempotent: a subscription already pending cancellation
        returns no_op. Requires an active Pro subscription with a provisioned Stripe
        subscription. The optional body carries the cancel survey (``feedback`` from
        Stripe''s fixed vocabulary, free-text ``comment``), forwarded to Stripe as
        ``cancellation_details`` so the admin Revenue page''s Pending Cancellations
        reason column is populated for in-app cancels the same way it is for Customer
        Portal cancels.'
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCancelRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SubscriptionCancelRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SubscriptionCancelRequestRequest'
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionCancelResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/change-credit-tier/:
    post:
      operationId: organizations_billing_subscription_change_credit_tier_create
      description: 'DEPRECATED: use change-package with explicit tiers, which applies
        every dimension — and the platform fee every non-Mighty plan carries — in
        one call. Add, swap, or remove the included-credit bundle on the org''s active
        Pro subscription without re-checkout. A null ``credit_tier`` removes the bundle
        (back to the $0 default); a set value adds (when none today) or swaps the
        existing bundle. UPGRADES (the credit value strictly increases; adding a bundle
        counts) charge the full price difference between the two tiers immediately
        — a flat difference, not a time-based Stripe proration — and grant the credit
        difference immediately; the renewal then bills the full new price. A declined
        difference charge returns HTTP 402 and reverts the change. Subscriptions carrying
        an active discount defer upgrades to the next cycle instead (the flat difference
        would ignore the coupon). DOWNGRADES and removals still use proration_behavior=none:
        the change — and the smaller monthly grant — take effect at the next cycle
        boundary, with no immediate charge or refund. Rejected with HTTP 409 while
        a cancellation is pending. Requires an active Pro subscription with a provisioned
        Stripe subscription.'
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditTierChangeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreditTierChangeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreditTierChangeRequestRequest'
        required: true
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      deprecated: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditTierChangeResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/change-machine-tier/:
    post:
      operationId: organizations_billing_subscription_change_machine_tier_create
      description: 'DEPRECATED: use change-package with explicit tiers, which applies
        every dimension — and the platform fee every non-Mighty plan carries — in
        one call. Add, switch, or remove the compute (machine) tier on the org''s
        active Pro subscription. A set value swaps the Stripe subscription item in
        place (or adds one when the subscription has no machine item); a null ``machine_tier``
        removes the item entirely (back to the small baseline). Upgrades — including
        adding a tier — invoice immediately (always_invoice) and grow the org''s assistants
        up to the new ceiling asynchronously, the same way a Base→Pro subscribe does;
        the response does not wait on that rollout. Downgrades and removals net onto
        the next invoice (create_prorations, no refund) and cap any pods above the
        new ceiling via vembda. Rejected with HTTP 409 while a cancellation is pending.
        Requires an active Pro subscription with the multi-item structure; legacy
        single-price subscriptions get HTTP 409 until they are migrated.'
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComputeTierChangeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ComputeTierChangeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ComputeTierChangeRequestRequest'
        required: true
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      deprecated: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputeTierChangeResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/change-package/:
    post:
      operationId: organizations_billing_subscription_change_package_create
      description: 'Change the org''s active Pro subscription to another Pro plan:
        a named package (e.g. mighty/super/ultra) or a custom plan given as explicit
        machine/storage/credit tiers. This is the one endpoint for every Pro → Pro
        change (named ↔ named, named ↔ custom, custom ↔ custom). Diffs the target''s
        machine, storage, credit, and base-platform-fee line items against the current
        subscription and applies them as one or two atomic Stripe updates: the machine/storage/fee
        items (adding, swapping, or removing — including the ``vellum_pro_base`` fee)
        settle in a first ``Subscription.modify`` that bills immediately, while any
        included-credit bundle change settles in a separate ``proration_behavior=none``
        modify. A credit-tier INCREASE additionally charges the flat price difference
        between the two bundles immediately and grants the credit difference immediately
        (mirroring change-credit-tier); when that difference cannot be charged (active
        discount, no chargeable payment method, or a declined charge) the credits
        simply apply at the next cycle and the package switch stands. Credit decreases
        settle at the next cycle. A net price increase on the primary items invoices
        immediately and gates on payment success (HTTP 402 on a declined card, leaving
        the plan unchanged); a net decrease nets onto the next invoice. Machines above
        the new package''s ceiling are capped via vembda and lower ceilings grow asynchronously;
        PVCs are never shrunk. Rejected with HTTP 409 while a cancellation is pending.
        A named package is gated on the ``pro-packages`` flag (an unknown or gated
        package returns the same HTTP 400); a custom target is not gated, like the
        per-dimension tier endpoints it replaces. A custom plan ALWAYS carries the
        base platform fee and clears the package pin (``package`` is null in the response);
        only the Mighty package is sold without the fee, so leaving Mighty for any
        other plan adds the fee (invoiced immediately with the rest of the net increase)
        and grants the fee-backed managed-email / phone-number entitlements, while
        moving to Mighty removes it. Custom targets follow the per-dimension rules:
        storage is upgrade-or-keep, and retired credit bundles / legacy storage tiers
        are rejected unless unchanged.'
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageChangeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PackageChangeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PackageChangeRequestRequest'
        required: true
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageChangeResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/change-storage-tier/:
    post:
      operationId: organizations_billing_subscription_change_storage_tier_create
      description: 'DEPRECATED: use change-package with explicit tiers, which applies
        every dimension — and the platform fee every non-Mighty plan carries — in
        one call. Upgrade the storage tier on the org''s active Pro subscription.
        Modifies the Stripe subscription item in place and invoices immediately (always_invoice).
        Storage is upgrade-only — equal-tier requests are a no-op and smaller-tier
        requests are rejected with HTTP 400 before any Stripe call. Legacy (no-longer-offered)
        tiers are rejected with HTTP 400 unless they equal the current tier (which
        no-ops). On a successful change the org''s assistants grow up to the new ceiling
        asynchronously, the same way a Base→Pro subscribe does; the response does
        not wait on that rollout. PVCs are never shrunk. Rejected with HTTP 409 while
        a cancellation is pending. Requires an active Pro subscription with storage_tier
        metadata; legacy subscriptions get HTTP 409 until they are migrated.'
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorageTierChangeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/StorageTierChangeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/StorageTierChangeRequestRequest'
        required: true
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      deprecated: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageTierChangeResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/machine/:
    post:
      operationId: organizations_billing_subscription_machine_resize
      description: |-
        Within-tier machine resize: bump every org assistant up to ``machine_size``
        (no-op for assistants already at or above it). Bounded by the org's
        ``BillingAccount.max_machine_tier`` ceiling. Free — no Stripe call.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProMachineResizeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ProMachineResizeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ProMachineResizeRequestRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProMachineResizeResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/onboarding/:
    get:
      operationId: organizations_billing_subscription_onboarding_retrieve
      description: Post-checkout Pro onboarding wizard endpoints.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingStateResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/onboarding/domain/:
    post:
      operationId: organizations_billing_subscription_onboarding_domain_create
      description: Post-checkout Pro onboarding wizard endpoints.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingDomainRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OnboardingDomainRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OnboardingDomainRequestRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingDomainResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/onboarding/ensure-provisioned/:
    post:
      operationId: organizations_billing_subscription_onboarding_ensure_provisioned_create
      description: |-
        Idempotently reconcile Pro entitlements against actual resources.

        Returns a verdict; when provisioning is needed, submits the same
        background grow-only auto-resize the subscribe webhook triggers and
        reports ``started`` — the response never waits on the resize work.
        Repeated calls converge without duplicating resize work: an in-process
        guard dedupes submissions until the queued worker finishes (a retry
        racing ahead of the worker's first resize marker reports
        ``in_progress`` instead of enqueuing a duplicate org-wide resize).

        Responds 503 when the verdict was ``needs_provisioning`` but the
        background submission could not be queued (e.g. during a rolling
        deploy) — nothing was queued, and the request is safe to retry.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnsureProvisionedResponse'
          description: ''
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnsureProvisionedUnavailable'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/reactivate/:
    post:
      operationId: organizations_billing_subscription_reactivate_create
      description: 'Reactivate the org''s Pro subscription by removing a pending cancellation
        before the current billing period ends — the server-side equivalent of clicking
        "Do not cancel" in the Stripe Customer Portal. The subscription resumes renewing
        at the period end; nothing is charged now. Idempotent: a subscription with
        no pending cancellation returns no_op. Requires an active Pro subscription
        with a provisioned Stripe subscription — once the period has ended and the
        subscription is fully canceled it can no longer be reactivated (returns HTTP
        403; subscribe again via upgrade instead).'
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionReactivateResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/subscription/upgrade/:
    post:
      operationId: organizations_billing_subscription_upgrade_create
      description: GET /…/subscription/ → current state. POST upgrade action.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpgradeRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SubscriptionUpgradeRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SubscriptionUpgradeRequestRequest'
        required: true
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionUpgradeResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/summary/:
    get:
      operationId: organizations_billing_summary_retrieve
      description: |-
        Return settled, pending, and effective balance for the organization.

        Read-only — does not create or modify any billing state.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      - AssistantAPIKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSummaryResponse'
          description: ''
      x-vellum-api-clients:
      - platform
    post:
      operationId: organizations_billing_summary_create
      description: |-
        Bootstrap billing for the organization and return the summary.

        Creates a ``BillingAccount`` (with initial credit) for organizations
        that don't yet have one.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSummaryResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/top-ups/checkout-session/:
    post:
      operationId: organizations_billing_top_ups_checkout_session_create
      description: |-
        Create a new top-up checkout session.

        Validates the requested amount, ensures a billing account exists for
        the organization, creates a ``BillingTopUp`` row, and returns the
        Stripe Checkout URL for client-side redirect.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TopUpCheckoutRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TopUpCheckoutRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TopUpCheckoutRequestRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopUpCheckoutResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/usage/series/:
    get:
      operationId: organizations_billing_usage_series_retrieve
      description: Return time-bucketed usage data grouped by a chosen dimension.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: query
        name: from
        schema:
          type: string
        description: Inclusive start date (ISO 8601).
        required: true
      - in: query
        name: granularity
        schema:
          type: string
          enum:
          - daily
          - monthly
          - weekly
        description: 'Time bucket granularity: daily (default), weekly, or monthly.'
      - in: query
        name: group_by
        schema:
          type: string
          enum:
          - assistant
          - inference_profile
          - inference_provider
          - llm_call_site
          - model
          - oauth_provider
          - search_provider
          - usage_source
        description: 'Dimension to group by within each bucket (default: usage_source).'
      - in: query
        name: inference_profile
        schema:
          type: string
        description: Filter by runtime-proxy inference profile ID.
      - in: query
        name: inference_provider
        schema:
          type: string
        description: Filter by LLM inference provider (e.g. anthropic, openai, gemini).
      - in: query
        name: llm_call_site
        schema:
          type: string
        description: Filter by runtime-proxy LLM call-site ID (task).
      - in: query
        name: model
        schema:
          type: string
        description: Filter by model ID (e.g. claude-opus-4-6).
      - in: query
        name: oauth_provider
        schema:
          type: string
        description: Filter by OAuth provider (e.g. twitter, hubspot).
      - in: query
        name: search_provider
        schema:
          type: string
        description: Filter by search provider (e.g. brave).
      - in: query
        name: to
        schema:
          type: string
        description: Inclusive end date (ISO 8601).
        required: true
      - in: query
        name: tz
        schema:
          type: string
        description: 'IANA timezone for date-range and bucket boundaries (default:
          UTC).'
      - in: query
        name: usage_source
        schema:
          type: string
          enum:
          - managed_speech_proxy
          - oauth_proxy
          - runtime_proxy
          - search_proxy
        description: 'Filter by usage source: runtime_proxy, oauth_proxy, search_proxy,
          or managed_speech_proxy.'
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageSeriesResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/billing/usage/totals/:
    get:
      operationId: organizations_billing_usage_totals_retrieve
      description: Return total spend and event count for the organization.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: query
        name: from
        schema:
          type: string
        description: Inclusive start date (ISO 8601).
        required: true
      - in: query
        name: inference_profile
        schema:
          type: string
        description: Filter by runtime-proxy inference profile ID.
      - in: query
        name: inference_provider
        schema:
          type: string
        description: Filter by LLM inference provider (e.g. anthropic, openai, gemini).
      - in: query
        name: llm_call_site
        schema:
          type: string
        description: Filter by runtime-proxy LLM call-site ID (task).
      - in: query
        name: model
        schema:
          type: string
        description: Filter by model ID (e.g. claude-opus-4-6).
      - in: query
        name: oauth_provider
        schema:
          type: string
        description: Filter by OAuth provider (e.g. twitter, hubspot).
      - in: query
        name: search_provider
        schema:
          type: string
        description: Filter by search provider (e.g. brave).
      - in: query
        name: to
        schema:
          type: string
        description: Inclusive end date (ISO 8601).
        required: true
      - in: query
        name: tz
        schema:
          type: string
        description: 'IANA timezone for date-range and bucket boundaries (default:
          UTC).'
      - in: query
        name: usage_source
        schema:
          type: string
          enum:
          - managed_speech_proxy
          - oauth_proxy
          - runtime_proxy
          - search_proxy
        description: 'Filter by usage source: runtime_proxy, oauth_proxy, search_proxy,
          or managed_speech_proxy.'
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageTotalsResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/notifications/:
    get:
      operationId: organizations_notifications_list
      description: List notifications for the authenticated organization.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: query
        name: assistant_id
        schema:
          type: string
        description: Filter notifications scoped to a specific assistant.
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: notification_type
        schema:
          type: string
        description: Filter by notification type.
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      - in: query
        name: status
        schema:
          type: string
          enum:
          - open
          - resolved
        description: 'Filter by lifecycle status: ''open'' or ''resolved''.'
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedNotificationListList'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/notifications/{id}/acknowledge/:
    post:
      operationId: organizations_notifications_acknowledge_create
      description: Acknowledge or unacknowledge a notification for the requesting
        user.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this notification.
        required: true
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcknowledgeRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AcknowledgeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AcknowledgeRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcknowledgeResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/notifications/{id}/snooze/:
    post:
      operationId: organizations_notifications_snooze_create
      description: Snooze a notification until a given time (or clear the snooze if
        null).
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this notification.
        required: true
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SnoozeRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SnoozeRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SnoozeRequest'
        required: true
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnoozeResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/notifications/pause-rules/:
    post:
      operationId: organizations_notifications_pause_rules_create
      description: Create an org-scoped notification mute/pause rule.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PauseRuleCreateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PauseRuleCreateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PauseRuleCreateRequest'
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PauseRuleRead'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/organizations/notifications/pause-rules/{rule_id}/:
    delete:
      operationId: organizations_notifications_pause_rules_destroy
      description: Delete an org-scoped notification mute/pause rule.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      - in: path
        name: rule_id
        schema:
          type: string
          pattern: ^[0-9a-f-]+$
        required: true
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '204':
          description: No response body
      x-vellum-api-clients:
      - platform
  /v1/organizations/notifications/summary/:
    get:
      operationId: organizations_notifications_summary_retrieve
      description: Return unread and active notification counts for navigation badges.
      parameters:
      - in: header
        name: Vellum-Organization-Id
        schema:
          type: string
          format: uuid
        description: Required if using Cookie-based or X-Session-Token authentication
          methods.
      tags:
      - organizations
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationSummary'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/referral-codes/me/:
    get:
      operationId: referral_codes_me_retrieve
      description: |-
        Return the user's referral code and stats.

        Lazily creates a referral code if the user doesn't have one yet.
      tags:
      - referral-codes
      security:
      - VellumAPIKey: []
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MyReferralCodeResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/releases/:
    get:
      operationId: releases_list
      parameters:
      - in: query
        name: channel
        schema:
          enum:
          - stable
          - preview
          type: string
          minLength: 1
        description: |-
          Filter by release channel. Takes precedence over stable.

          * `stable` - Stable
          * `preview` - Preview
      - in: query
        name: limit
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 10
        description: Maximum number of releases to return. Defaults to 10.
      - in: query
        name: since_version
        schema:
          type: string
          minLength: 1
        description: Only return releases newer than this version.
      - in: query
        name: stable
        schema:
          type: boolean
          default: true
        description: Filter by stability. Defaults to true.
      tags:
      - releases
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      - SDKCompatibleAssistantKey: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReleaseListItem'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/telemetry/ingest/:
    post:
      operationId: telemetry_ingest_create
      tags:
      - telemetry
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TelemetryIngestRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TelemetryIngestRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TelemetryIngestRequestRequest'
        required: true
      security:
      - SDKCompatibleAssistantKey: []
      - XSessionTokenAuth: []
      - cookieAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelemetryIngestResponse'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/user/consent/:
    get:
      operationId: user_consent_retrieve
      tags:
      - user
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserConsent'
          description: ''
      x-vellum-api-clients:
      - platform
    put:
      operationId: user_consent_update
      tags:
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserConsentRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UserConsentRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UserConsentRequest'
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserConsent'
          description: ''
      x-vellum-api-clients:
      - platform
  /v1/user/deletion-request/:
    post:
      operationId: user_deletion_request_create
      tags:
      - user
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          description: No response body
        '404':
          description: No response body
        '409':
          description: No response body
      x-vellum-api-clients:
      - platform
  /v1/user/mfa/factors/:
    get:
      operationId: user_mfa_factors_list
      tags:
      - user
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MfaFactor'
          description: ''
        '429':
          description: No response body
        '502':
          description: No response body
      x-vellum-api-clients:
      - platform
    post:
      operationId: user_mfa_factors_create
      tags:
      - user
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaEnrollResponse'
          description: ''
        '400':
          description: No response body
        '409':
          description: No response body
        '429':
          description: No response body
        '502':
          description: No response body
      x-vellum-api-clients:
      - platform
  /v1/user/mfa/factors/{id}/:
    delete:
      operationId: user_mfa_factors_destroy
      parameters:
      - in: path
        name: id
        schema:
          type: string
        description: The authentication factor id.
        required: true
      tags:
      - user
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '204':
          description: No response body
        '404':
          description: No response body
        '429':
          description: No response body
        '502':
          description: No response body
      x-vellum-api-clients:
      - platform
  /v1/user/mfa/factors/verify/:
    post:
      operationId: user_mfa_factors_verify_create
      tags:
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MfaVerifyRequestRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MfaVerifyRequestRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MfaVerifyRequestRequest'
        required: true
      security:
      - cookieAuth: []
      - XSessionTokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaVerifyResponse'
          description: ''
        '400':
          description: No response body
        '404':
          description: No response body
        '409':
          description: No response body
        '410':
          description: No response body
        '429':
          description: No response body
        '502':
          description: No response body
      x-vellum-api-clients:
      - platform
components:
  schemas:
    AccessConsent:
      type: object
      description: Serializer for the user-controlled staff access consent toggle.
      properties:
        access_consented:
          type: boolean
          description: 'When True, Vellum staff may access this assistant and its
            data for debugging: daemon log files, an admin terminal on the running
            assistant, and a disposable clone of its disk. Defaults to False; the
            owner can revoke at any time, which blocks new access and further commands
            in open admin terminal sessions. A grant lapses on its own at access_consent_expires_at;
            reads report False once it has.'
        access_consent_expires_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: When the current grant lapses. Set on every enable, 24 hours
            out by default. Null when access is off or never expires.
        access_consent_never_expires:
          type: boolean
          readOnly: true
          description: True when the owner chose to keep access on until they turn
            it off, in which case access_consent_expires_at is null.
      required:
      - access_consent_expires_at
      - access_consent_never_expires
      - access_consented
    AcknowledgeRequest:
      type: object
      description: Serializer for acknowledge/unacknowledge actions.
      properties:
        acknowledged:
          type: boolean
      required:
      - acknowledged
    AcknowledgeResponse:
      type: object
      description: Response serializer for acknowledge/unacknowledge actions.
      properties:
        id:
          type: string
          format: uuid
        is_read:
          type: boolean
        read_at:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - is_read
      - read_at
    AndroidDevicePushTokenUpsertPlatformEnum:
      enum:
      - android
      type: string
      description: '* `android` - android'
    AndroidDevicePushTokenUpsertRequest:
      type: object
      properties:
        token:
          type: string
          minLength: 1
          maxLength: 512
        platform:
          $ref: '#/components/schemas/AndroidDevicePushTokenUpsertPlatformEnum'
        bundle_id:
          type: string
          minLength: 1
          maxLength: 128
        capabilities:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 64
          description: 'What the shell registering this token can render. Known values:
            native-notification-render. An unknown value is dropped and the rest of
            the registration succeeds, so a client can advertise a capability this
            server does not know yet. Omitting the field resets the stored list to
            [].'
          maxItems: 16
      required:
      - bundle_id
      - platform
      - token
    ApnsEnvironmentEnum:
      enum:
      - production
      - development
      type: string
      description: |-
        * `production` - production
        * `development` - development
    Assistant:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 255
        handle:
          type: string
          readOnly: true
        description:
          type: string
          nullable: true
        configuration: {}
        status:
          $ref: '#/components/schemas/AssistantStatusEnum'
        created:
          type: string
          format: date-time
          readOnly: true
        modified:
          type: string
          format: date-time
          readOnly: true
        release_channel:
          allOf:
          - $ref: '#/components/schemas/ReleaseChannelEnum'
          readOnly: true
        current_release_version:
          type: string
          nullable: true
          readOnly: true
        avatar_url:
          type: string
          nullable: true
          readOnly: true
        machine_id:
          type: string
          nullable: true
          maxLength: 255
        vembda_cluster_id:
          type: string
          readOnly: true
          nullable: true
        machine_size:
          readOnly: true
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/MachineSizeEnum'
          - $ref: '#/components/schemas/NullEnum'
        provisioned_storage_gib:
          type: integer
          readOnly: true
          nullable: true
          description: GiB of workspace PVC last successfully provisioned for THIS
            assistant via a resize/onboarding apply. Null until storage is first applied.
            Used to derive onboarding pvc_ready and as the never-shrink floor; distinct
            from BillingAccount billing markers.
        maintenance_mode:
          allOf:
          - $ref: '#/components/schemas/MaintenanceMode'
          readOnly: true
        is_local:
          type: boolean
          readOnly: true
        ingress_url:
          type: string
          nullable: true
          readOnly: true
        platform_actor_token:
          type: string
          nullable: true
          readOnly: true
        access_consented:
          type: boolean
          readOnly: true
        access_consent_expires_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        access_consent_never_expires:
          type: boolean
          readOnly: true
      required:
      - access_consent_expires_at
      - access_consent_never_expires
      - access_consented
      - avatar_url
      - created
      - current_release_version
      - handle
      - id
      - ingress_url
      - is_local
      - machine_size
      - maintenance_mode
      - modified
      - platform_actor_token
      - provisioned_storage_gib
      - release_channel
      - vembda_cluster_id
    AssistantDomain:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        subdomain:
          type: string
          description: Subdomain label (e.g. 'velly')
          maxLength: 63
        created:
          type: string
          format: date-time
          readOnly: true
        modified:
          type: string
          format: date-time
          readOnly: true
      required:
      - created
      - id
      - modified
      - subdomain
    AssistantEmailAddress:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        address:
          type: string
          format: email
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
      required:
      - address
      - created_at
      - id
    AssistantFeedbackClassificationEnum:
      enum:
      - bug_report
      - other
      type: string
      description: |-
        * `bug_report` - Bug Report
        * `other` - Other
    AssistantFeedbackIngestRequestRequest:
      type: object
      description: |-
        Body of a report an assistant files under its own API key.

        Who filed it comes from the key, so there is no identity field, and no
        upload field: what an assistant may attach is its own design.
      properties:
        message:
          type: string
          minLength: 1
          maxLength: 50000
        classification:
          $ref: '#/components/schemas/AssistantFeedbackClassificationEnum'
        assistant_version:
          type: string
          default: ''
          maxLength: 100
        client_version:
          type: string
          default: ''
          maxLength: 100
      required:
      - classification
      - message
    AssistantHandleAvailability:
      type: object
      description: |-
        Response shape for the live assistant-handle availability check.

        * ``available``: ``true`` only when the handle passes format validation
          AND no other assistant holds it (case-insensitively).
        * ``code``: ``null`` when ``available`` is ``true``; otherwise a stable
          machine-readable reason — either a validation code from
          :mod:`app.assistant.handle_validation` or ``"taken"``.
      properties:
        available:
          type: boolean
        code:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
      required:
      - available
    AssistantRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          nullable: true
        configuration: {}
        status:
          $ref: '#/components/schemas/AssistantStatusEnum'
        machine_id:
          type: string
          nullable: true
          maxLength: 255
    AssistantResize403:
      oneOf:
      - $ref: '#/components/schemas/AssistantResizeTierError'
      - $ref: '#/components/schemas/DetailResponse'
    AssistantResizeRequestRequest:
      type: object
      properties:
        machine_size:
          type: string
          minLength: 1
        storage_gib:
          type: integer
          minimum: 1
    AssistantResizeResponse:
      type: object
      properties:
        machine_size:
          type: string
          nullable: true
        provisioned_storage_gib:
          type: integer
          nullable: true
      required:
      - machine_size
      - provisioned_storage_gib
    AssistantResizeTierError:
      type: object
      description: |-
        403 body returned when a resize request exceeds a purchased tier.

        Two flavors share this shape: ``exceeds_machine_tier`` (with
        ``max_machine_tier``) and ``exceeds_storage_tier`` (with ``max_storage_gib``).
        The non-applicable ceiling field is omitted per branch, so both are optional
        and nullable. Distinct from the Pro-gate 403, which returns ``{detail}``.
      properties:
        error:
          type: string
        max_machine_tier:
          type: string
          nullable: true
        max_storage_gib:
          type: integer
          nullable: true
      required:
      - error
    AssistantStatusEnum:
      enum:
      - initializing
      - active
      - to_be_deleted
      - archiving
      - archived
      - restoring
      type: string
      description: |-
        * `initializing` - Initializing
        * `active` - Active
        * `to_be_deleted` - To be deleted
        * `archiving` - Archiving
        * `archived` - Archived
        * `restoring` - Restoring
    AssistantSystemEvent:
      type: object
      description: |-
        List-item serializer for AssistantSystemEvent.

        Exposes only the fields that the web and admin UIs need.  ``display_text``
        is derived from ``details`` at read time so that the stored schema can
        evolve without migrations.

        ``idle_timeout_seconds`` is read from the event's ``details`` payload
        where it was stored at record time.  ``None`` for non-idle_sleep events
        or events recorded before this field was persisted.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        type:
          allOf:
          - $ref: '#/components/schemas/SystemEventTypeEnum'
          readOnly: true
          description: |-
            High-level categorisation of what occurred.

            * `lifecycle` - Lifecycle
            * `upgrade` - Upgrade
            * `rollback` - Rollback
            * `crash` - Crash
            * `idle_sleep` - Idle Sleep
            * `wake` - Wake
            * `profiler` - Profiler
            * `other` - Other
        event_status:
          allOf:
          - $ref: '#/components/schemas/EventStatusEnum'
          readOnly: true
          description: |-
            Outcome or phase of the event.

            * `started` - Started
            * `succeeded` - Succeeded
            * `failed` - Failed
            * `in_progress` - In Progress
        source:
          allOf:
          - $ref: '#/components/schemas/SourceEnum'
          readOnly: true
          description: |-
            Component that produced the event.

            * `django` - Django
            * `vembda` - Vembda
        reason:
          type: string
          readOnly: true
          description: Short machine-readable reason code or message.
        display_text:
          type: string
          readOnly: true
        details:
          readOnly: true
          description: Structured event payload. Derive display text from this field.
        occurred_at:
          type: string
          format: date-time
          readOnly: true
          description: When the event actually occurred (caller-supplied).
        idle_timeout_seconds:
          type: integer
          nullable: true
          readOnly: true
      required:
      - details
      - display_text
      - event_status
      - id
      - idle_timeout_seconds
      - occurred_at
      - reason
      - source
      - type
    AutoTopUpConfigRequestRequest:
      type: object
      description: PUT /…/auto-top-up/ request body.
      properties:
        enabled:
          type: boolean
        threshold_usd:
          type: string
          minLength: 1
        amount_usd:
          type: string
          minLength: 1
        monthly_cap_usd:
          type: string
          nullable: true
          minLength: 1
      required:
      - amount_usd
      - enabled
      - monthly_cap_usd
      - threshold_usd
    AutoTopUpConfigResponse:
      type: object
      description: GET /…/auto-top-up/ response shape; also returned by PUT.
      properties:
        enabled:
          type: boolean
        threshold_usd:
          type: string
          nullable: true
        amount_usd:
          type: string
          nullable: true
        monthly_cap_usd:
          type: string
          nullable: true
        has_payment_method:
          type: boolean
        payment_method_brand:
          type: string
          nullable: true
        payment_method_last4:
          type: string
          nullable: true
        payment_method_exp_month:
          type: integer
          nullable: true
        payment_method_exp_year:
          type: integer
          nullable: true
        billing_address:
          allOf:
          - $ref: '#/components/schemas/BillingAddress'
          nullable: true
        stripe_payment_method_updated_at:
          type: string
          format: date-time
          nullable: true
        last_charge_at:
          type: string
          format: date-time
          nullable: true
        last_failure_at:
          type: string
          format: date-time
          nullable: true
        last_failure_reason:
          type: string
          nullable: true
        paused_until:
          type: string
          format: date-time
          nullable: true
        current_month_credits_purchased_usd:
          type: string
        current_month_charged_usd:
          type: string
        next_trigger_amount_usd:
          type: string
          nullable: true
        disabled_due_to_repeated_failures:
          type: boolean
        stubbed:
          type: boolean
      required:
      - amount_usd
      - billing_address
      - current_month_charged_usd
      - current_month_credits_purchased_usd
      - disabled_due_to_repeated_failures
      - enabled
      - has_payment_method
      - last_charge_at
      - last_failure_at
      - last_failure_reason
      - monthly_cap_usd
      - next_trigger_amount_usd
      - paused_until
      - payment_method_brand
      - payment_method_exp_month
      - payment_method_exp_year
      - payment_method_last4
      - stripe_payment_method_updated_at
      - stubbed
      - threshold_usd
    AutoTopUpConfirmSetupIntentRequestRequest:
      type: object
      description: POST /…/auto-top-up/confirm-setup-intent/ request body.
      properties:
        setup_intent_id:
          type: string
          minLength: 1
          description: Stripe SetupIntent id returned by the client-side confirmSetup
            call.
          maxLength: 255
      required:
      - setup_intent_id
    AutoTopUpDisableResponse:
      type: object
      properties:
        enabled:
          type: boolean
        stubbed:
          type: boolean
        message:
          type: string
      required:
      - enabled
      - message
      - stubbed
    AutoTopUpHistoryEntry:
      type: object
      properties:
        id:
          type: string
        requested_amount_usd:
          type: string
        status:
          $ref: '#/components/schemas/AutoTopUpHistoryEntryStatusEnum'
        stripe_decline_code:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
      required:
      - created_at
      - id
      - requested_amount_usd
      - status
      - stripe_decline_code
    AutoTopUpHistoryEntryStatusEnum:
      enum:
      - initiated
      - paid
      - failed
      type: string
      description: |-
        * `initiated` - initiated
        * `paid` - paid
        * `failed` - failed
    AutoTopUpHistoryResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/AutoTopUpHistoryEntry'
        count:
          type: integer
          minimum: 0
        stubbed:
          type: boolean
      required:
      - count
      - results
      - stubbed
    AutoTopUpSetupIntentResponse:
      type: object
      description: POST /…/auto-top-up/setup-intent/ response shape.
      properties:
        client_secret:
          type: string
          description: Stripe SetupIntent client_secret for use with Stripe Elements.
      required:
      - client_secret
    BasePlan:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/BasePlanIdEnum'
        name:
          type: string
        price_cents:
          type: integer
          minimum: 0
        billing_interval:
          $ref: '#/components/schemas/BillingIntervalEnum'
        included_features:
          type: array
          items:
            type: string
      required:
      - billing_interval
      - id
      - included_features
      - name
      - price_cents
    BasePlanIdEnum:
      enum:
      - base
      type: string
      description: '* `base` - base'
    BillingAddress:
      type: object
      description: Billing address saved on the Stripe PaymentMethod.
      properties:
        line1:
          type: string
          nullable: true
        line2:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        postal_code:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
      required:
      - city
      - country
      - line1
      - line2
      - postal_code
      - state
    BillingIntervalEnum:
      enum:
      - month
      type: string
      description: '* `month` - month'
    BillingPortalSessionResponse:
      type: object
      properties:
        portal_url:
          type: string
          format: uri
      required:
      - portal_url
    BillingSummaryResponse:
      type: object
      description: |-
        Response body for the billing summary endpoint.

        All monetary values are returned as decimal strings (not floats).
      properties:
        settled_balance:
          type: string
          description: Settled (on-ledger) credit balance as a decimal string.
        minimum_top_up:
          type: string
          description: Minimum allowed top-up amount as a decimal string.
        maximum_top_up:
          type: string
          description: Maximum allowed top-up amount as a decimal string.
        maximum_balance:
          type: string
          description: Maximum allowed account credit balance as a decimal string.
        allowed_top_up_amounts:
          type: array
          items:
            type: string
          description: Ordered list of allowed top-up amounts in USD as decimal strings.
        settled_balance_usd:
          type: string
          description: Settled (on-ledger) balance in USD as a decimal string.
        minimum_top_up_usd:
          type: string
          description: Minimum allowed top-up amount in USD as a decimal string.
        maximum_top_up_usd:
          type: string
          description: Maximum allowed top-up amount in USD as a decimal string.
        maximum_balance_usd:
          type: string
          description: Maximum allowed account balance in USD as a decimal string.
        pending_compute:
          type: string
          description: Estimated pending compute charges not yet settled, as a decimal
            string.
        pending_compute_usd:
          type: string
          description: Estimated pending compute charges not yet settled, as a decimal
            string.
        effective_balance:
          type: string
          description: Effective credit balance (settled minus pending) as a decimal
            string.
        effective_balance_usd:
          type: string
          description: Effective balance (settled minus pending) in USD as a decimal
            string.
        is_degraded:
          type: boolean
          description: True when pending-compute data may be stale or unavailable.
        daily_credit_limit_usd:
          type: string
          nullable: true
          description: Per-org daily credit spend limit as a decimal string, or null
            when no daily limit is set.
        daily_spend_usd:
          type: string
          description: Today's (UTC) credit spend counted against the daily limit,
            as a decimal string. Spend covered by plan-included credits (initial credit,
            Pro credit bundle) is excluded. Reported as "0.00" when the stored counter
            is from a prior UTC day.
        daily_limit_reached:
          type: boolean
          description: True when a daily limit is set, today's spend has reached it,
            and the limit is being enforced. False while the limit is skipped for
            the day (see daily_limit_snoozed) or while plan-included credits (initial
            credit, Pro credit bundle) still hold unexpired balance. Drives the in-app
            daily-limit banner.
        daily_limit_snoozed:
          type: boolean
          description: True when the daily limit has been skipped for the current
            UTC day, so it is not enforced until the next reset. Auto top-up is unaffected
            and keeps charging.
        free_tier_daily_limit_enrolled:
          type: boolean
          description: True when the organization was enrolled at signup in the free-tier
            daily usage-credit limit cohort.
        free_tier_daily_limit_enforced:
          type: boolean
          description: 'True when the free-tier daily limit currently applies: enrolled,
            no active Pro subscription, and the platform kill switch is on.'
        free_tier_daily_limit_usd:
          type: string
          description: Per-UTC-day cap on usage-credit spend (initial credit, Pro
            bundle, conversion incentive) as a decimal string. Only meaningful when
            free_tier_daily_limit_enforced.
        free_tier_daily_spend_usd:
          type: string
          description: Today's (UTC) spend drawn from usage-credit grants as a decimal
            string. Reported as "0.00" when the stored counter is from a prior UTC
            day. Purchased/extra credit spend is never included.
        free_tier_daily_limit_reached:
          type: boolean
          description: True when the free-tier daily limit is enforced and today's
            usage-credit spend has reached it, so usage credit is unspendable until
            the next UTC day while purchased/extra credit remains spendable. Drives
            the in-app free-tier banner.
        low_balance_threshold_usd:
          type: string
          description: Effective low-balance alert threshold in USD as a decimal string
            (per-org override when set, else the global default). Same threshold that
            gates the low-balance warning email.
        low_balance_warning:
          type: boolean
          description: True when the balance is above zero but below the low-balance
            threshold and auto-top-up is not enabled. Drives the in-app low-credits
            banner.
        credits_expiring_soon_usd:
          type: string
          description: Unexpired remaining credit (USD, decimal string) from grants
            whose expiry falls within the next 30 days. Already-expired remainders
            are excluded.
        next_credit_expiry_at:
          type: string
          format: date-time
          nullable: true
          description: Earliest upcoming expiry across grants that still hold credit,
            or null when no unexpired credit remains.
        available_usage_balance:
          type: string
          description: Unused credit (USD, decimal string) remaining on unexpired
            initial-credit and subscription (Pro bundle) grants.
        total_usage_balance:
          type: string
          description: Total granted credit (USD, decimal string) across unexpired
            initial-credit and subscription (Pro bundle) grants, including amounts
            already used but net of refunded credit.
      required:
      - allowed_top_up_amounts
      - credits_expiring_soon_usd
      - daily_credit_limit_usd
      - daily_limit_reached
      - daily_limit_snoozed
      - daily_spend_usd
      - effective_balance
      - effective_balance_usd
      - free_tier_daily_limit_enforced
      - free_tier_daily_limit_enrolled
      - free_tier_daily_limit_reached
      - free_tier_daily_limit_usd
      - free_tier_daily_spend_usd
      - is_degraded
      - low_balance_threshold_usd
      - low_balance_warning
      - maximum_balance
      - maximum_balance_usd
      - maximum_top_up
      - maximum_top_up_usd
      - minimum_top_up
      - minimum_top_up_usd
      - next_credit_expiry_at
      - pending_compute
      - pending_compute_usd
      - settled_balance
      - settled_balance_usd
    BlankEnum:
      enum:
      - ''
    CancellationFeedbackEnum:
      enum:
      - customer_service
      - low_quality
      - missing_features
      - other
      - switched_service
      - too_complex
      - too_expensive
      - unused
      type: string
      description: |-
        * `customer_service` - customer_service
        * `low_quality` - low_quality
        * `missing_features` - missing_features
        * `other` - other
        * `switched_service` - switched_service
        * `too_complex` - too_complex
        * `too_expensive` - too_expensive
        * `unused` - unused
    CheckoutBonusClaimResponse:
      type: object
      description: POST /…/checkout-bonus/ response shape.
      properties:
        status:
          $ref: '#/components/schemas/CheckoutBonusClaimResponseStatusEnum'
        amount_usd:
          type: string
        balance_usd:
          type: string
      required:
      - amount_usd
      - balance_usd
      - status
    CheckoutBonusClaimResponseStatusEnum:
      enum:
      - granted
      - already_claimed
      - ineligible
      type: string
      description: |-
        * `granted` - granted
        * `already_claimed` - already_claimed
        * `ineligible` - ineligible
    CheckoutBonusEligibilityResponse:
      type: object
      description: GET /…/checkout-bonus/ response shape.
      properties:
        eligible:
          type: boolean
        amount_usd:
          type: string
      required:
      - amount_usd
      - eligible
    ClassificationEnum:
      enum:
      - something_broken
      - app_crash
      - performance
      - connection
      - feature_request
      - other
      - bug_report
      type: string
      description: |-
        * `something_broken` - Something Broken
        * `app_crash` - App Crash
        * `performance` - Performance
        * `connection` - Connection
        * `feature_request` - Feature Request
        * `other` - Other
        * `bug_report` - Bug Report
    ClientEnum:
      enum:
      - macos
      - ios
      - android
      - web
      - cli
      - electron
      type: string
      description: |-
        * `macos` - macOS
        * `ios` - iOS
        * `android` - Android
        * `web` - Web
        * `cli` - CLI
        * `electron` - Electron
    ClientFeatureFlagsResponse:
      type: object
      properties:
        flags:
          type: object
          additionalProperties:
            oneOf:
            - type: boolean
            - type: string
      required:
      - flags
    CodeEnum:
      enum:
      - denied
      - state_invalid
      - state_expired
      - exchange_failed
      - identity_failed
      - internal_error
      - credential_required
      - credential_expired
      - token_refresh_failed
      - provider_request_rejected
      - provider_unreachable
      - invalid_proxy_request
      - multiple_connections
      - connection_not_found
      - oauth_start_failed
      - insufficient_balance
      - daily_limit_reached
      - free_tier_daily_limit_reached
      - missing_price
      - assistant_not_live
      type: string
      description: |-
        * `denied` - denied
        * `state_invalid` - state_invalid
        * `state_expired` - state_expired
        * `exchange_failed` - exchange_failed
        * `identity_failed` - identity_failed
        * `internal_error` - internal_error
        * `credential_required` - credential_required
        * `credential_expired` - credential_expired
        * `token_refresh_failed` - token_refresh_failed
        * `provider_request_rejected` - provider_request_rejected
        * `provider_unreachable` - provider_unreachable
        * `invalid_proxy_request` - invalid_proxy_request
        * `multiple_connections` - multiple_connections
        * `connection_not_found` - connection_not_found
        * `oauth_start_failed` - oauth_start_failed
        * `insufficient_balance` - insufficient_balance
        * `daily_limit_reached` - daily_limit_reached
        * `free_tier_daily_limit_reached` - free_tier_daily_limit_reached
        * `missing_price` - missing_price
        * `assistant_not_live` - assistant_not_live
    ComputeTierChangeRequestRequest:
      type: object
      properties:
        machine_tier:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/MachineTierEnum'
          - $ref: '#/components/schemas/NullEnum'
      required:
      - machine_tier
    ComputeTierChangeResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/TierChangeStatusEnum'
        machine_tier:
          type: string
          nullable: true
      required:
      - machine_tier
      - status
    ConnectionStatus:
      type: object
      description: Serializer describing the live reachability of an assistant pod.
      properties:
        state:
          allOf:
          - $ref: '#/components/schemas/ConnectionStatusStateEnum'
          description: |-
            Coarse reachability bucket. 'ready' means the pod is serving traffic; 'waking' means it is scaling up from idle-sleep; 'crash_loop' means the pod is reporting an error; 'unreachable' means the probe itself failed and the caller should retry.

            * `ready` - ready
            * `waking` - waking
            * `crash_loop` - crash_loop
            * `not_found` - not_found
            * `unreachable` - unreachable
        is_awake:
          type: boolean
        pod_status:
          type: string
          nullable: true
        waking_since:
          type: string
          format: date-time
          nullable: true
        last_ready_at:
          type: string
          format: date-time
          nullable: true
        crash_loop_since:
          type: string
          format: date-time
          nullable: true
        detail:
          type: string
          nullable: true
        pod_error_kind:
          type: string
          nullable: true
          description: Classified root cause of a CRASH_LOOP, when vembda was able
            to infer one (e.g. 'out_of_storage' when the pod has run out of disk space).
            Clients can branch on this to show targeted remediation UI such as a link
            to the storage doctor.
      required:
      - crash_loop_since
      - detail
      - is_awake
      - last_ready_at
      - pod_status
      - state
      - waking_since
    ConnectionStatusEnum:
      enum:
      - ACTIVE
      - REVOKED
      - ERROR
      type: string
      description: |-
        * `ACTIVE` - Active
        * `REVOKED` - Revoked
        * `ERROR` - Error
    ConnectionStatusStateEnum:
      enum:
      - ready
      - waking
      - crash_loop
      - not_found
      - unreachable
      type: string
      description: |-
        * `ready` - ready
        * `waking` - waking
        * `crash_loop` - crash_loop
        * `not_found` - not_found
        * `unreachable` - unreachable
    CreateAssistantDomainRequest:
      type: object
      properties:
        subdomain:
          type: string
          minLength: 1
          description: Subdomain to register (e.g. 'velly'). Defaults to the assistant's
            handle.
          maxLength: 63
        email_username:
          type: string
          minLength: 1
          description: If provided, also create an email address <username>@<subdomain>.<root_domain>
            after domain registration.
          maxLength: 255
    CreateEmailAddressRequest:
      type: object
      properties:
        username:
          type: string
          writeOnly: true
          minLength: 1
          maxLength: 255
      required:
      - username
    CreditTier:
      type: object
      properties:
        tier:
          type: string
        label:
          type: string
        credits_usd:
          type: integer
          minimum: 0
        price_cents:
          type: integer
          minimum: 0
        lookup_key:
          type: string
        legacy:
          type: boolean
          description: 'True only for a grandfathered tier: no longer offered, present
            in the catalog solely because it is the org''s current tier.'
      required:
      - credits_usd
      - label
      - legacy
      - lookup_key
      - price_cents
      - tier
    CreditTierChangeRequestRequest:
      type: object
      properties:
        credit_tier:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/CreditTierEnum'
          - $ref: '#/components/schemas/NullEnum'
      required:
      - credit_tier
    CreditTierChangeResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/TierChangeStatusEnum'
        credit_tier:
          type: string
          nullable: true
        charged_usd:
          type: string
          nullable: true
        granted_credits_usd:
          type: string
          nullable: true
      required:
      - credit_tier
      - status
    CreditTierEnum:
      enum:
      - credits_10
      - credits_25
      - credits_45
      - credits_50
      - credits_100
      - credits_115
      - credits_200
      type: string
      description: |-
        * `credits_10` - credits_10
        * `credits_25` - credits_25
        * `credits_45` - credits_45
        * `credits_50` - credits_50
        * `credits_100` - credits_100
        * `credits_115` - credits_115
        * `credits_200` - credits_200
    CustomPlanChangeRequestRequest:
      type: object
      description: |-
        The custom-plan arm of the ``change-package`` request: explicit tiers.

        ``machine_tier`` / ``credit_tier`` ``None`` mean no line item for that
        dimension (the small baseline machine; no credit bundle). The
        ChoiceFields keep the FULL tier dicts (OpenAPI enum stability); the view
        rejects retired/legacy targets that differ from the current tier,
        mirroring the per-dimension tier endpoints. A custom plan always carries
        the base platform fee; the fee-less configuration is only sold as the
        Mighty package.
      properties:
        machine_tier:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/MachineTierEnum'
          - $ref: '#/components/schemas/NullEnum'
        storage_tier:
          $ref: '#/components/schemas/StorageTierEnum'
        credit_tier:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/CreditTierEnum'
          - $ref: '#/components/schemas/NullEnum'
      required:
      - storage_tier
      additionalProperties: false
    DailyCreditLimitRequestRequest:
      type: object
      description: PUT /…/daily-credit-limit/ request body. ``null`` clears the limit.
      properties:
        daily_credit_limit_usd:
          type: string
          nullable: true
          minLength: 1
      required:
      - daily_credit_limit_usd
    DailyCreditLimitResponse:
      type: object
      description: GET/PUT /…/daily-credit-limit/ response shape.
      properties:
        daily_credit_limit_usd:
          type: string
          nullable: true
        current_day_spent_usd:
          type: string
        day_bucket:
          type: string
          nullable: true
        daily_limit_snoozed:
          type: boolean
        daily_limit_snoozed_day_bucket:
          type: string
          nullable: true
      required:
      - current_day_spent_usd
      - daily_credit_limit_usd
      - daily_limit_snoozed
      - daily_limit_snoozed_day_bucket
      - day_bucket
    DebugBundleUploadUrl:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: Signed PUT URL. Upload the debug bundle here with Content-Type
            application/octet-stream.
        bundle_key:
          type: string
        expires_at:
          type: string
          format: date-time
      required:
      - bundle_key
      - expires_at
      - url
    DetailResponse:
      type: object
      properties:
        detail:
          type: string
      required:
      - detail
    DevicePushTokenUpsert:
      type: object
      properties:
        token:
          type: string
          maxLength: 512
        platform:
          $ref: '#/components/schemas/DevicePushTokenUpsertPlatformEnum'
        bundle_id:
          type: string
          maxLength: 128
        apns_environment:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/ApnsEnvironmentEnum'
          - $ref: '#/components/schemas/NullEnum'
        capabilities:
          type: array
          items:
            type: string
            maxLength: 64
          description: 'What the shell registering this token can render. Known values:
            native-notification-render. An unknown value is dropped and the rest of
            the registration succeeds, so a client can advertise a capability this
            server does not know yet. Omitting the field resets the stored list to
            [].'
          maxItems: 16
      required:
      - apns_environment
      - bundle_id
      - capabilities
      - platform
      - token
    DevicePushTokenUpsertPlatformEnum:
      enum:
      - ios
      - android
      type: string
      description: |-
        * `ios` - ios
        * `android` - android
    DevicePushTokenUpsertRequest:
      oneOf:
      - $ref: '#/components/schemas/IosDevicePushTokenUpsertRequest'
      - $ref: '#/components/schemas/AndroidDevicePushTokenUpsertRequest'
      discriminator:
        propertyName: platform
        mapping:
          ios: '#/components/schemas/IosDevicePushTokenUpsertRequest'
          android: '#/components/schemas/AndroidDevicePushTokenUpsertRequest'
    DoctorMessage:
      type: object
      description: Serializer for a single persisted Doctor message ledger entry.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        kind:
          allOf:
          - $ref: '#/components/schemas/DoctorMessageKindEnum'
          readOnly: true
          description: |-
            What kind of UI event this entry represents.

            * `user` - User
            * `assistant` - Assistant
            * `tool_call` - Tool Call
            * `tool_result` - Tool Result
            * `approval` - Approval
            * `status` - Status
            * `error` - Error
        content:
          type: string
          readOnly: true
          description: Human-readable content (may be empty for status/tool events).
        metadata:
          readOnly: true
          description: Structured payload describing the event (e.g. tool args).
        sequence:
          type: integer
          readOnly: true
          description: Monotonic per-session ordering, allocated atomically on write.
        source_event_id:
          type: string
          readOnly: true
          nullable: true
          description: Optional upstream Doctor event ID used for idempotent replay.
        occurred_at:
          type: string
          format: date-time
          readOnly: true
          description: When the event actually occurred (caller-supplied).
      required:
      - content
      - id
      - kind
      - metadata
      - occurred_at
      - sequence
      - source_event_id
    DoctorMessageKindEnum:
      enum:
      - user
      - assistant
      - tool_call
      - tool_result
      - approval
      - status
      - error
      type: string
      description: |-
        * `user` - User
        * `assistant` - Assistant
        * `tool_call` - Tool Call
        * `tool_result` - Tool Result
        * `approval` - Approval
        * `status` - Status
        * `error` - Error
    DoctorSessionCreateResponse:
      type: object
      description: Response from creating a new Doctor session.
      properties:
        session_id:
          type: string
      required:
      - session_id
    DoctorSessionDetail:
      type: object
      description: |-
        Detail serializer for a persisted Doctor session with its messages.

        ``messages`` is a nested list of :class:`DoctorMessageSerializer`
        rows.  Callers are expected to preload the related messages with
        ``prefetch_related("messages")`` and pass a queryset ordered by
        ``sequence`` so the output is deterministic.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        status:
          allOf:
          - $ref: '#/components/schemas/DoctorSessionStatusEnum'
          readOnly: true
          description: |-
            Lifecycle status of the session.

            * `active` - Active
            * `completed` - Completed
            * `error` - Error
        user_outcome:
          readOnly: true
          nullable: true
          description: |-
            User-reported outcome: whether the Doctor solved their problem. Null until the user answers the outcome prompt.

            * `resolved` - Resolved
            * `not_resolved` - Not resolved
          oneOf:
          - $ref: '#/components/schemas/UserOutcomeEnum'
          - $ref: '#/components/schemas/NullEnum'
        last_message_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Timestamp of the most recently appended message, if any.
        ended_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: When the session reached a terminal state.
        total_input_tokens:
          type: integer
          readOnly: true
          description: Total input-side LLM tokens used by the Doctor session.
        total_output_tokens:
          type: integer
          readOnly: true
          description: Total output LLM tokens used by the Doctor session.
        total_cache_creation_input_tokens:
          type: integer
          readOnly: true
          description: Total prompt-cache write input tokens used by the Doctor session.
        total_cache_read_input_tokens:
          type: integer
          readOnly: true
          description: Total prompt-cache read input tokens used by the Doctor session.
        total_estimated_cost_usd:
          type: number
          format: double
          readOnly: true
          description: Estimated LLM cost in USD for the Doctor session.
        created:
          type: string
          format: date-time
          readOnly: true
        modified:
          type: string
          format: date-time
          readOnly: true
        message_count:
          type: integer
          readOnly: true
        messages:
          type: array
          items:
            $ref: '#/components/schemas/DoctorMessage'
          readOnly: true
      required:
      - created
      - ended_at
      - id
      - last_message_at
      - message_count
      - messages
      - modified
      - status
      - total_cache_creation_input_tokens
      - total_cache_read_input_tokens
      - total_estimated_cost_usd
      - total_input_tokens
      - total_output_tokens
      - user_outcome
    DoctorSessionList:
      type: object
      description: |-
        List-item serializer for persisted Doctor sessions.

        ``message_count`` is sourced from an annotation on the queryset
        (``Count("messages")``) so the list endpoint does not have to
        issue a per-row query.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        status:
          allOf:
          - $ref: '#/components/schemas/DoctorSessionStatusEnum'
          readOnly: true
          description: |-
            Lifecycle status of the session.

            * `active` - Active
            * `completed` - Completed
            * `error` - Error
        user_outcome:
          readOnly: true
          nullable: true
          description: |-
            User-reported outcome: whether the Doctor solved their problem. Null until the user answers the outcome prompt.

            * `resolved` - Resolved
            * `not_resolved` - Not resolved
          oneOf:
          - $ref: '#/components/schemas/UserOutcomeEnum'
          - $ref: '#/components/schemas/NullEnum'
        last_message_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: Timestamp of the most recently appended message, if any.
        ended_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: When the session reached a terminal state.
        total_input_tokens:
          type: integer
          readOnly: true
          description: Total input-side LLM tokens used by the Doctor session.
        total_output_tokens:
          type: integer
          readOnly: true
          description: Total output LLM tokens used by the Doctor session.
        total_cache_creation_input_tokens:
          type: integer
          readOnly: true
          description: Total prompt-cache write input tokens used by the Doctor session.
        total_cache_read_input_tokens:
          type: integer
          readOnly: true
          description: Total prompt-cache read input tokens used by the Doctor session.
        total_estimated_cost_usd:
          type: number
          format: double
          readOnly: true
          description: Estimated LLM cost in USD for the Doctor session.
        created:
          type: string
          format: date-time
          readOnly: true
        modified:
          type: string
          format: date-time
          readOnly: true
        message_count:
          type: integer
          readOnly: true
      required:
      - created
      - ended_at
      - id
      - last_message_at
      - message_count
      - modified
      - status
      - total_cache_creation_input_tokens
      - total_cache_read_input_tokens
      - total_estimated_cost_usd
      - total_input_tokens
      - total_output_tokens
      - user_outcome
    DoctorSessionMessageRequestRequest:
      type: object
      description: Request body for sending a message to a Doctor session.
      properties:
        content:
          type: string
          minLength: 1
        source_event_id:
          type: string
          nullable: true
          maxLength: 128
      required:
      - content
    DoctorSessionStatusEnum:
      enum:
      - active
      - completed
      - error
      type: string
      description: |-
        * `active` - Active
        * `completed` - Completed
        * `error` - Error
    DoctorSessionUserOutcomeRequestRequest:
      type: object
      description: Request body for recording whether the Doctor solved the user's
        problem.
      properties:
        resolved:
          type: boolean
      required:
      - resolved
    DoctorSessionUserOutcomeResponse:
      type: object
      description: Response after recording a Doctor session user outcome.
      properties:
        user_outcome:
          type: string
      required:
      - user_outcome
    DomainVerificationStatus:
      type: object
      properties:
        domain:
          type: string
        status:
          $ref: '#/components/schemas/DomainVerificationStatusStatusEnum'
        message:
          type: string
      required:
      - domain
      - message
      - status
    DomainVerificationStatusStatusEnum:
      enum:
      - verified
      - pending
      - not_started
      - failed
      - unknown
      type: string
      description: |-
        * `verified` - verified
        * `pending` - pending
        * `not_started` - not_started
        * `failed` - failed
        * `unknown` - unknown
    EmailAddressStatus:
      type: object
      properties:
        address:
          type: string
          format: email
        status:
          type: string
        usage:
          $ref: '#/components/schemas/EmailAddressUsage'
        created_at:
          type: string
          format: date-time
      required:
      - address
      - created_at
      - status
      - usage
    EmailAddressUsage:
      type: object
      properties:
        sent_today:
          type: integer
        daily_limit:
          type: integer
        received_today:
          type: integer
        sent_this_month:
          type: integer
        received_this_month:
          type: integer
      required:
      - daily_limit
      - received_this_month
      - received_today
      - sent_this_month
      - sent_today
    EmailMessage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        direction:
          type: string
        from_address:
          type: string
          format: email
        to_addresses:
          type: array
          items:
            type: string
            format: email
        subject:
          type: string
        created_at:
          type: string
          format: date-time
      required:
      - created_at
      - direction
      - from_address
      - id
      - subject
      - to_addresses
    EnsureProvisionedReasonEnum:
      enum:
      - no_active_pro
      - no_targets
      - no_provisionable_assistants
      type: string
      description: |-
        * `no_active_pro` - no_active_pro
        * `no_targets` - no_targets
        * `no_provisionable_assistants` - no_provisionable_assistants
    EnsureProvisionedResponse:
      type: object
      description: |-
        Response from POST /onboarding/ensure-provisioned/.

        ``state`` is the reconcile verdict; ``started`` means a background
        grow-only resize was just submitted, while ``in_progress`` means resize
        work is already underway (an active per-assistant resize operation —
        including a machine/PVC rollout still completing after the targets already
        read as satisfied — or a submission still in flight from an earlier call).
        ``already_done`` is terminal: every target is satisfied and no resize
        rollout remains active. ``reason`` is set only for ``not_applicable``, and
        ``no_provisionable_assistants`` means the org holds the entitlement but has
        no settled platform-hosted assistant to apply it to — nothing to converge,
        so nothing was provisioned.
      properties:
        state:
          $ref: '#/components/schemas/EnsureProvisionedResponseStateEnum'
        reason:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/EnsureProvisionedReasonEnum'
          - $ref: '#/components/schemas/NullEnum'
        targets:
          $ref: '#/components/schemas/EnsureProvisionedTargets'
      required:
      - reason
      - state
      - targets
    EnsureProvisionedResponseStateEnum:
      enum:
      - already_done
      - in_progress
      - started
      - not_applicable
      type: string
      description: |-
        * `already_done` - already_done
        * `in_progress` - in_progress
        * `started` - started
        * `not_applicable` - not_applicable
    EnsureProvisionedTargets:
      type: object
      description: Resolved resize ceilings the org's Pro subscription grants.
      properties:
        machine_size:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/MachineSizeEnum'
          - $ref: '#/components/schemas/NullEnum'
        storage_gib:
          type: integer
          nullable: true
      required:
      - machine_size
      - storage_gib
    EnsureProvisionedUnavailable:
      type: object
      description: |-
        503 body from POST /onboarding/ensure-provisioned/.

        The verdict was ``needs_provisioning`` but the background resize
        submission could not be queued (e.g. the executor is shutting down during
        a rolling deploy). Nothing was queued; the request is safe to retry.
      properties:
        error:
          type: string
          description: Always "provisioning_submission_failed".
      required:
      - error
    EventStatusEnum:
      enum:
      - started
      - succeeded
      - failed
      - in_progress
      type: string
      description: |-
        * `started` - Started
        * `succeeded` - Succeeded
        * `failed` - Failed
        * `in_progress` - In Progress
    FeedbackIngestRequestRequest:
      type: object
      properties:
        message:
          type: string
          minLength: 1
          maxLength: 50000
        classification:
          $ref: '#/components/schemas/ClassificationEnum'
        email:
          type: string
          format: email
          default: ''
        device_id:
          type: string
          default: ''
          maxLength: 255
        assistant_id:
          type: string
          default: ''
          description: Raw assistant ID from the client; used to resolve the assistant
            FK.
        doctor_session_id:
          type: string
          default: ''
          description: Raw Doctor session ID from the client; used to resolve the
            Doctor session FK.
          maxLength: 64
        client_version:
          type: string
          default: ''
          maxLength: 100
        client:
          default: ''
          oneOf:
          - $ref: '#/components/schemas/ClientEnum'
          - $ref: '#/components/schemas/BlankEnum'
        assistant_version:
          type: string
          default: ''
          maxLength: 100
        logs_file:
          type: string
          format: binary
        attachments:
          type: array
          items:
            type: string
            format: binary
          maxItems: 10
      required:
      - classification
      - message
    FeedbackIngestResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
      required:
      - id
    FormatEnum:
      enum:
      - mp3
      - wav_8000
      - pcm_16000
      type: string
      description: |-
        * `mp3` - mp3
        * `wav_8000` - wav_8000
        * `pcm_16000` - pcm_16000
    FreeTierDailyLimitResponse:
      type: object
      description: |-
        GET /…/free-tier-daily-limit/ response shape.

        Daily information only: the cohort's larger initial-credit grant is the
        "lifetime" allowance and is reported through the credits/summary APIs.
      properties:
        enrolled:
          type: boolean
          description: True when the organization was enrolled at signup in the free-tier
            daily usage-credit limit cohort. Sticky for the life of the organization.
        enforced:
          type: boolean
          description: 'True when the limit currently applies: enrolled, no active
            Pro subscription, and the platform kill switch is on. False for every
            non-enrolled organization.'
        daily_limit_usd:
          type: string
          description: Per-UTC-day cap on usage-credit spend as a decimal string.
            Reported for every organization; only meaningful when enforced.
        current_day_spent_usd:
          type: string
          description: Today's (UTC) spend drawn from usage-credit grants (initial
            credit, Pro bundle, conversion incentive) as a decimal string. Reported
            as "0.00" when the stored counter is from a prior UTC day. Purchased/extra
            credit spend is never included.
        day_bucket:
          type: string
          nullable: true
          description: The UTC day the stored counter belongs to ('YYYY-MM-DD'), or
            null when no usage-credit spend has been recorded yet.
        limit_reached:
          type: boolean
          description: True when the limit is enforced and today's usage-credit spend
            has reached it, so usage credit is unspendable until the next UTC day.
            Purchased/extra credit remains spendable. Drives the in-app free-tier
            daily-limit banner.
      required:
      - current_day_spent_usd
      - daily_limit_usd
      - day_bucket
      - enforced
      - enrolled
      - limit_reached
    FrequencyEnum:
      enum:
      - daily
      - weekly
      - monthly
      type: string
      description: |-
        * `daily` - daily
        * `weekly` - weekly
        * `monthly` - monthly
    HatchAssistantRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          default: New Assistant
          maxLength: 255
        description:
          type: string
        version:
          type: string
          nullable: true
          minLength: 1
    Invoice:
      type: object
      description: A single Stripe invoice, trimmed to fields a billing-history UI
        needs.
      properties:
        id:
          type: string
          description: Stripe Invoice ID (e.g. in_xxx).
        number:
          type: string
          nullable: true
          description: Human-readable invoice number (e.g. INV-0001); null for drafts.
        status:
          type: string
          nullable: true
          description: 'Invoice status: draft, open, paid, uncollectible, or void.'
        currency:
          type: string
          description: Three-letter ISO currency code (e.g. usd).
        amount_due:
          type: integer
          description: Amount owed in the currency's minor units (e.g. cents).
        amount_paid:
          type: integer
          description: Amount paid in the currency's minor units (e.g. cents).
        amount_remaining:
          type: integer
          description: Amount still owed in the currency's minor units (e.g. cents).
        created:
          type: integer
          description: Invoice creation time as a Unix timestamp (seconds).
        hosted_invoice_url:
          type: string
          format: uri
          nullable: true
          description: Stripe-hosted invoice page URL; null if not yet finalized.
        invoice_pdf:
          type: string
          format: uri
          nullable: true
          description: URL to download the invoice PDF; null if not yet finalized.
      required:
      - amount_due
      - amount_paid
      - amount_remaining
      - created
      - currency
      - hosted_invoice_url
      - id
      - invoice_pdf
      - number
      - status
    InvoiceListResponse:
      type: object
      description: Response body for listing a customer's invoices.
      properties:
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/Invoice'
        has_more:
          type: boolean
          description: True if older invoices exist beyond this page. Pass the last
            invoice's id as ?starting_after= to fetch the next page.
      required:
      - has_more
      - invoices
    IosDevicePushTokenUpsertPlatformEnum:
      enum:
      - ios
      type: string
      description: '* `ios` - ios'
    IosDevicePushTokenUpsertRequest:
      type: object
      properties:
        token:
          type: string
          minLength: 1
          maxLength: 512
        platform:
          $ref: '#/components/schemas/IosDevicePushTokenUpsertPlatformEnum'
        bundle_id:
          type: string
          minLength: 1
          maxLength: 128
        apns_environment:
          $ref: '#/components/schemas/ApnsEnvironmentEnum'
      required:
      - apns_environment
      - bundle_id
      - platform
      - token
    LiveActivityTokenUpsert:
      type: object
      description: |-
        Request/response body for registering one activity's update token.

        ``labels`` must cover every phase this activity can be pushed into: a
        dispatch for a phase with no label has nothing to render, and the server is
        deliberately not allowed to invent wording of its own (see the model).
        Validating it here makes that a 400 at registration rather than a silently
        dropped push mid-session.

        ``accent_hex`` and ``muted`` ride along for a related reason: they are
        ``ContentState`` fields only the client can observe, and every push replaces
        that state wholesale. The client re-registers when either changes, so the
        newest registration is always what a dispatch composes from.
      properties:
        token:
          type: string
          maxLength: 512
        bundle_id:
          type: string
          maxLength: 128
        apns_environment:
          $ref: '#/components/schemas/ApnsEnvironmentEnum'
        conversation_id:
          type: string
          maxLength: 64
        labels: {}
        accent_hex:
          type: string
          maxLength: 9
        muted:
          type: boolean
      required:
      - apns_environment
      - bundle_id
      - conversation_id
      - token
    LiveActivityTokenUpsertRequest:
      type: object
      description: |-
        Request/response body for registering one activity's update token.

        ``labels`` must cover every phase this activity can be pushed into: a
        dispatch for a phase with no label has nothing to render, and the server is
        deliberately not allowed to invent wording of its own (see the model).
        Validating it here makes that a 400 at registration rather than a silently
        dropped push mid-session.

        ``accent_hex`` and ``muted`` ride along for a related reason: they are
        ``ContentState`` fields only the client can observe, and every push replaces
        that state wholesale. The client re-registers when either changes, so the
        newest registration is always what a dispatch composes from.
      properties:
        token:
          type: string
          minLength: 1
          maxLength: 512
        bundle_id:
          type: string
          minLength: 1
          maxLength: 128
        apns_environment:
          $ref: '#/components/schemas/ApnsEnvironmentEnum'
        conversation_id:
          type: string
          minLength: 1
          maxLength: 64
        labels: {}
        accent_hex:
          type: string
          maxLength: 9
        muted:
          type: boolean
      required:
      - apns_environment
      - bundle_id
      - conversation_id
      - token
    LiveVoiceTokenRequestRequest:
      type: object
      properties:
        assistantId:
          type: string
          format: uuid
      required:
      - assistantId
    LiveVoiceTokenResponse:
      type: object
      properties:
        token:
          type: string
        expiresAt:
          type: string
          format: date-time
      required:
      - expiresAt
      - token
    LowBalanceAlertRequestRequest:
      type: object
      description: PUT /…/low-balance-alert/ request body. ``null`` clears the override.
      properties:
        threshold_usd:
          type: string
          nullable: true
          minLength: 1
      required:
      - threshold_usd
    LowBalanceAlertResponse:
      type: object
      description: GET/PUT /…/low-balance-alert/ response shape.
      properties:
        threshold_usd:
          type: string
          nullable: true
        effective_threshold_usd:
          type: string
        default_threshold_usd:
          type: string
      required:
      - default_threshold_usd
      - effective_threshold_usd
      - threshold_usd
    MachineSizeEnum:
      enum:
      - small
      - medium
      - large
      - extra_large
      type: string
      description: |-
        * `small` - Small
        * `medium` - Medium
        * `large` - Large
        * `extra_large` - Extra Large
    MachineTier:
      type: object
      properties:
        tier:
          type: string
        label:
          type: string
        price_cents:
          type: integer
          minimum: 0
        lookup_key:
          type: string
        cpu_limit:
          type: string
        memory_gib:
          type: integer
          minimum: 0
        description:
          type: string
      required:
      - cpu_limit
      - description
      - label
      - lookup_key
      - memory_gib
      - price_cents
      - tier
    MachineTierEnum:
      enum:
      - medium
      - large
      - xl
      type: string
      description: |-
        * `medium` - medium
        * `large` - large
        * `xl` - xl
    MaintenanceMode:
      type: object
      properties:
        enabled:
          type: boolean
        debug_pod_name:
          type: string
          nullable: true
      required:
      - debug_pod_name
      - enabled
    ManagedSearchProxyErrorResponse:
      type: object
      properties:
        code:
          type: string
        detail:
          type: string
      required:
      - code
      - detail
    ManagedSearchProxyRequestBodyRequest:
      type: object
      properties:
        method:
          type: string
          minLength: 1
        path:
          type: string
          minLength: 1
        query:
          type: object
          additionalProperties: {}
        headers:
          type: object
          additionalProperties: {}
        body:
          nullable: true
      required:
      - method
      - path
    ManagedSearchProxyRequestRequest:
      type: object
      properties:
        request:
          $ref: '#/components/schemas/ManagedSearchProxyRequestBodyRequest'
      required:
      - request
    ManagedSearchProxyResponse:
      type: object
      properties:
        status:
          type: integer
        headers:
          type: object
          additionalProperties: {}
        body:
          nullable: true
      required:
      - body
      - headers
      - status
    ManagedSpeechErrorResponse:
      type: object
      description: Error envelope shared by the managed speech STT/TTS endpoints.
      properties:
        code:
          type: string
        detail:
          type: string
      required:
      - code
      - detail
    ManagedSpeechSTTRequestRequest:
      type: object
      description: Request body for the managed speech STT (speech-to-text) endpoint.
      properties:
        audioBase64:
          type: string
          minLength: 1
        mimeType:
          type: string
          minLength: 1
        source:
          type: string
        language:
          type: string
          minLength: 1
          maxLength: 32
      required:
      - audioBase64
      - mimeType
    ManagedSpeechSTTResponse:
      type: object
      description: Response body for the managed speech STT endpoint.
      properties:
        text:
          type: string
        providerId:
          type: string
        model:
          type: string
        durationSeconds:
          type: number
          format: double
      required:
      - durationSeconds
      - model
      - providerId
      - text
    ManagedSpeechTTSRequestRequest:
      type: object
      description: Request body for the managed speech TTS (text-to-speech) endpoint.
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 2000
        format:
          allOf:
          - $ref: '#/components/schemas/FormatEnum'
          default: mp3
        model:
          type: string
          minLength: 1
          maxLength: 64
      required:
      - text
    ManagedSpeechTTSVoice:
      type: object
      description: One voice offered by the managed TTS voice picker.
      properties:
        model:
          type: string
        label:
          type: string
        description:
          type: string
        sampleUrl:
          type: string
          format: uri
        source:
          type: string
      required:
      - description
      - label
      - model
      - sampleUrl
      - source
    ManagedSpeechTTSVoicesResponse:
      type: object
      description: Response body for the managed speech TTS voices endpoint.
      properties:
        voices:
          type: array
          items:
            $ref: '#/components/schemas/ManagedSpeechTTSVoice'
        defaultModel:
          type: string
          nullable: true
      required:
      - defaultModel
      - voices
    MfaEnrollResponse:
      type: object
      properties:
        factor_id:
          type: string
        challenge_id:
          type: string
        qr_code:
          type: string
        secret:
          type: string
        uri:
          type: string
        issuer:
          type: string
        user:
          type: string
        created_at:
          type: string
          format: date-time
      required:
      - challenge_id
      - created_at
      - factor_id
      - issuer
      - qr_code
      - secret
      - uri
      - user
    MfaFactor:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        issuer:
          type: string
        user:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
      - created_at
      - id
      - issuer
      - type
      - updated_at
      - user
    MfaVerifyRequestRequest:
      type: object
      properties:
        challenge_id:
          type: string
          minLength: 1
          maxLength: 256
        code:
          type: string
          minLength: 1
          maxLength: 6
          pattern: ^\d{6}$
      required:
      - challenge_id
      - code
    MfaVerifyResponse:
      type: object
      properties:
        valid:
          type: boolean
      required:
      - valid
    ModeEnum:
      enum:
      - restore_backup
      - standard_upgrade
      type: string
      description: |-
        * `restore_backup` - restore_backup
        * `standard_upgrade` - standard_upgrade
    MyReferralCodeResponse:
      type: object
      properties:
        code:
          type: string
        referral_url:
          type: string
        referred_count:
          type: integer
        total_earned_usd:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        earning_cap_usd:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        total_earned:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        earning_cap:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        credit_amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        referrer_credit_amount:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
        is_eligible_for_credits:
          type: boolean
      required:
      - code
      - credit_amount
      - earning_cap
      - earning_cap_usd
      - is_eligible_for_credits
      - referral_url
      - referred_count
      - referrer_credit_amount
      - total_earned
      - total_earned_usd
    NamedPackageChangeRequestRequest:
      type: object
      description: The named-package arm of the ``change-package`` request.
      properties:
        package:
          type: string
          minLength: 1
          pattern: ^[-a-zA-Z0-9_]+$
      required:
      - package
      additionalProperties: false
    NotificationList:
      type: object
      description: Read serializer for listing notifications.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        notification_type:
          allOf:
          - $ref: '#/components/schemas/NotificationTypeEnum'
          readOnly: true
        dedupe_key:
          type: string
          readOnly: true
          description: Stable key derived from the triggering condition. Used to merge
            repeat triggers into a single open notification.
        title:
          type: string
          readOnly: true
        body:
          type: string
          readOnly: true
        metadata:
          readOnly: true
          description: Arbitrary producer-supplied context.
        first_seen_at:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp of the first trigger event.
        last_seen_at:
          type: string
          format: date-time
          readOnly: true
          description: Timestamp of the most recent trigger event.
        occurrence_count:
          type: integer
          readOnly: true
          description: Number of times this condition has been triggered while open.
        resolved_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: When the condition was resolved; NULL means still open.
        last_notified_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: When we last delivered an outbound notification for this row.
        is_resolved:
          type: boolean
          readOnly: true
        is_read:
          type: boolean
          readOnly: true
        snoozed_until:
          type: string
          nullable: true
          readOnly: true
      required:
      - body
      - dedupe_key
      - first_seen_at
      - id
      - is_read
      - is_resolved
      - last_notified_at
      - last_seen_at
      - metadata
      - notification_type
      - occurrence_count
      - resolved_at
      - snoozed_until
      - title
    NotificationSummary:
      type: object
      description: Serializer for notification badge counts.
      properties:
        unread_count:
          type: integer
        active_count:
          type: integer
      required:
      - active_count
      - unread_count
    NotificationTypeEnum:
      enum:
      - alert
      type: string
      description: '* `alert` - Alert'
    NullEnum:
      enum:
      - null
    OAuthConnection:
      type: object
      properties:
        id:
          type: string
          format: uuid
        provider:
          $ref: '#/components/schemas/OAuthProviderEnum'
        status:
          $ref: '#/components/schemas/ConnectionStatusEnum'
        connected:
          type: boolean
        account_label:
          type: string
          nullable: true
        scopes_granted:
          type: array
          items:
            type: string
        expires_at:
          type: string
          format: date-time
          nullable: true
        provider_params:
          type: object
          additionalProperties:
            type: string
      required:
      - account_label
      - connected
      - expires_at
      - id
      - provider
      - scopes_granted
      - status
    OAuthDisconnectResponse:
      type: object
      properties:
        success:
          type: boolean
      required:
      - success
    OAuthErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          default: false
        code:
          $ref: '#/components/schemas/CodeEnum'
        detail:
          type: string
      required:
      - code
      - detail
    OAuthProviderEnum:
      enum:
      - twitter
      - google
      - outlook
      - linear
      - github
      - asana
      - notion
      - todoist
      - dropbox
      - discord
      - airtable
      - hubspot
      - salesforce
      - eventbrite
      - calendly
      - monday
      - figma
      - stripe_link
      - shopify
      - quickbooks
      type: string
      description: |-
        * `twitter` - twitter
        * `google` - google
        * `outlook` - outlook
        * `linear` - linear
        * `github` - github
        * `asana` - asana
        * `notion` - notion
        * `todoist` - todoist
        * `dropbox` - dropbox
        * `discord` - discord
        * `airtable` - airtable
        * `hubspot` - hubspot
        * `salesforce` - salesforce
        * `eventbrite` - eventbrite
        * `calendly` - calendly
        * `monday` - monday
        * `figma` - figma
        * `stripe_link` - stripe_link
        * `shopify` - shopify
        * `quickbooks` - quickbooks
    OAuthStartRequestRequest:
      type: object
      properties:
        requested_scopes:
          type: array
          items:
            type: string
            minLength: 1
        redirect_after_connect:
          type: string
          minLength: 1
          default: /
        tenant_host:
          type: string
          default: ''
          maxLength: 253
    OAuthStartResponse:
      type: object
      properties:
        success:
          type: boolean
        deferred:
          type: boolean
        provider:
          $ref: '#/components/schemas/OAuthProviderEnum'
        connect_url:
          type: string
          format: uri
        state_id:
          type: string
          format: uuid
      required:
      - connect_url
      - deferred
      - provider
      - state_id
      - success
    OnboardingDomainRequestRequest:
      type: object
      properties:
        subdomain:
          type: string
          minLength: 1
          maxLength: 63
        skipped:
          type: boolean
          default: false
        email_username:
          type: string
          minLength: 1
          maxLength: 255
    OnboardingDomainResponse:
      type: object
      description: |-
        Response from POST /onboarding/domain/.

        Either reports a skipped wizard step or echoes the registered subdomain.
      properties:
        skipped:
          type: boolean
        id:
          type: string
          format: uuid
        subdomain:
          type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    OnboardingStateResponse:
      type: object
      properties:
        max_machine_tier:
          type: string
          nullable: true
        selected_storage_tier:
          type: string
          nullable: true
        selected_storage_gib:
          type: integer
          nullable: true
        pvc_ready:
          type: boolean
        domain_setup_available:
          type: boolean
        primary_assistant_id:
          type: string
          format: uuid
          nullable: true
      required:
      - domain_setup_available
      - max_machine_tier
      - primary_assistant_id
      - pvc_ready
      - selected_storage_gib
      - selected_storage_tier
    OperationalStatus:
      type: object
      properties:
        state:
          $ref: '#/components/schemas/OperationalStatusStateEnum'
        detail_state:
          type: string
        poll_after_ms:
          type: integer
        updated_at:
          type: string
          format: date-time
        state_started_at:
          type: string
          format: date-time
          nullable: true
        active_operation:
          allOf:
          - $ref: '#/components/schemas/OperationalStatusOperation'
          nullable: true
        assistant:
          $ref: '#/components/schemas/OperationalStatusAssistant'
        pod:
          $ref: '#/components/schemas/OperationalStatusPod'
        runtime:
          $ref: '#/components/schemas/OperationalStatusRuntime'
        storage:
          type: object
          additionalProperties: {}
          nullable: true
        detail:
          $ref: '#/components/schemas/OperationalStatusDetail'
      required:
      - active_operation
      - assistant
      - detail
      - detail_state
      - pod
      - poll_after_ms
      - runtime
      - state
      - state_started_at
      - storage
      - updated_at
    OperationalStatusAssistant:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
        machine_id:
          type: string
          nullable: true
        vembda_cluster_id:
          type: string
          nullable: true
      required:
      - id
      - machine_id
      - status
      - vembda_cluster_id
    OperationalStatusDetail:
      type: object
      properties:
        reason:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
      required:
      - message
      - reason
    OperationalStatusOperation:
      type: object
      properties:
        operation:
          type: string
        operation_id:
          type: string
        phase:
          type: string
        started_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        target:
          type: object
          additionalProperties: {}
      required:
      - operation
      - operation_id
      - phase
      - started_at
      - target
      - updated_at
    OperationalStatusPod:
      type: object
      properties:
        statefulset_found:
          type: boolean
          nullable: true
        spec_replicas:
          type: integer
          nullable: true
        ready_replicas:
          type: integer
          nullable: true
        pod_name:
          type: string
          nullable: true
        pod_phase:
          type: string
          nullable: true
        has_restart_history:
          type: boolean
        max_restart_count:
          type: integer
          nullable: true
        fatal_reason:
          type: string
          nullable: true
      required:
      - fatal_reason
      - has_restart_history
      - max_restart_count
      - pod_name
      - pod_phase
      - ready_replicas
      - spec_replicas
      - statefulset_found
    OperationalStatusRuntime:
      type: object
      properties:
        healthz_ok:
          type: boolean
        assistant_version:
          type: string
          nullable: true
        checked_at:
          type: string
          format: date-time
          nullable: true
      required:
      - assistant_version
      - checked_at
      - healthz_ok
    OperationalStatusStateEnum:
      enum:
      - initializing
      - migrating
      - provisioning
      - active
      - sleeping
      - waking
      - restarting
      - restoring_backup
      - upgrading_assistant_version
      - resizing_machine
      - resizing_storage
      - maintenance_mode
      - crash_loop
      - unreachable
      - not_found
      - retiring
      type: string
      description: |-
        * `initializing` - initializing
        * `migrating` - migrating
        * `provisioning` - provisioning
        * `active` - active
        * `sleeping` - sleeping
        * `waking` - waking
        * `restarting` - restarting
        * `restoring_backup` - restoring_backup
        * `upgrading_assistant_version` - upgrading_assistant_version
        * `resizing_machine` - resizing_machine
        * `resizing_storage` - resizing_storage
        * `maintenance_mode` - maintenance_mode
        * `crash_loop` - crash_loop
        * `unreachable` - unreachable
        * `not_found` - not_found
        * `retiring` - retiring
    OrganizationRead:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 255
      required:
      - id
      - name
    OwnerConsent:
      type: object
      description: |-
        Share-preference toggles exposed to assistant-key callers (the daemon).

        Each toggle is accompanied by the version and timestamp of the consent the
        owner accepted, so the daemon can tell *which* policy version a preference
        was recorded against. The versioned legal-consent fields (ToS, privacy
        policy, AI data sharing) are intentionally excluded — the daemon only needs
        the share preferences.

        Released daemons parse the share toggles as strict booleans, so this
        projection must stay additive: telemetry is opt-out, so a never-chosen
        (null) value is coerced to ``True`` (enabled by default) and the
        explicit-choice fact is surfaced separately via the ``*_chosen`` fields.
        PII trace eligibility is unaffected by the coercion: it also requires
        ``share_diagnostics_accepted_version``, which is reported as ``""`` until
        an explicit diagnostics value is recorded — even if a version-only write
        stamped one — so a never-chose owner can never pass the daemon's
        trace-disclosure gate.
      properties:
        share_analytics:
          type: boolean
          readOnly: true
        share_analytics_chosen:
          type: boolean
          readOnly: true
        share_analytics_accepted_version:
          type: string
          readOnly: true
        share_analytics_accepted_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        share_diagnostics:
          type: boolean
          readOnly: true
        share_diagnostics_chosen:
          type: boolean
          readOnly: true
        share_diagnostics_accepted_version:
          type: string
          readOnly: true
        share_diagnostics_accepted_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
      required:
      - share_analytics
      - share_analytics_accepted_at
      - share_analytics_accepted_version
      - share_analytics_chosen
      - share_diagnostics
      - share_diagnostics_accepted_at
      - share_diagnostics_accepted_version
      - share_diagnostics_chosen
    PackageChangeRequestRequest:
      oneOf:
      - $ref: '#/components/schemas/NamedPackageChangeRequestRequest'
      - $ref: '#/components/schemas/CustomPlanChangeRequestRequest'
    PackageChangeResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/TierChangeStatusEnum'
        package:
          allOf:
          - $ref: '#/components/schemas/SubscriptionPackage'
          nullable: true
        credit_charged_usd:
          type: string
          nullable: true
        credit_granted_usd:
          type: string
          nullable: true
      required:
      - package
      - status
    PaginatedAssistantDomainList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/AssistantDomain'
    PaginatedAssistantEmailAddressList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/AssistantEmailAddress'
    PaginatedAssistantList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/Assistant'
    PaginatedAssistantSystemEventList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/AssistantSystemEvent'
    PaginatedDoctorSessionListList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/DoctorSessionList'
    PaginatedEmailMessageList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/EmailMessage'
    PaginatedNotificationListList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/NotificationList'
    PaginatedOrganizationReadList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        results:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationRead'
    PatchedAccessConsentRequest:
      type: object
      description: Serializer for the user-controlled staff access consent toggle.
      properties:
        access_consented:
          type: boolean
          description: 'When True, Vellum staff may access this assistant and its
            data for debugging: daemon log files, an admin terminal on the running
            assistant, and a disposable clone of its disk. Defaults to False; the
            owner can revoke at any time, which blocks new access and further commands
            in open admin terminal sessions. A grant lapses on its own at access_consent_expires_at;
            reads report False once it has.'
        never_expires:
          type: boolean
          writeOnly: true
          description: 'Only with access_consented=true: keep access on until the
            owner turns it off, instead of for expires_in_hours.'
        expires_in_hours:
          type: integer
          maximum: 168
          minimum: 1
          writeOnly: true
          description: 'Only with access_consented=true: how long the grant lasts,
            1 to 168 hours. Defaults to 24. Enabling again resets the clock.'
    PatchedAssistantPartialUpdateRequest:
      type: object
      description: |-
        Write surface for ``PATCH /v1/assistants/{id}/``.

        Accepts a narrow allowlist (``name``, ``description``, ``handle``,
        ``avatar_base64``, ``notification_avatar_base64``) and delegates handle
        format validation to :func:`app.assistant.handle_validation.validate_handle`.
        Uniqueness is enforced at the database layer via the case-insensitive
        functional unique index on ``LOWER(handle)``; the view converts the
        resulting ``IntegrityError`` to a 409 (see
        :meth:`AssistantViewSet.partial_update`).

        ``avatar_base64`` and ``notification_avatar_base64`` are write-only,
        non-model fields: the daemon sends the raw images inline, and
        :meth:`AssistantViewSet.partial_update` pops the decoded payloads out of
        ``validated_data`` before the model save.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          nullable: true
        handle:
          type: string
          minLength: 1
          maxLength: 150
        avatar_base64:
          type: string
          writeOnly: true
          nullable: true
          description: Base64-encoded avatar image (PNG, JPEG, GIF, or WebP), at most
            524288 bytes (512 KiB) decoded. Send null or an empty string to remove
            the current avatar; omit the field to leave it alone.
        notification_avatar_base64:
          type: string
          writeOnly: true
          nullable: true
          description: Base64-encoded notification avatar image (PNG only), square
            and at most 512 pixels per side, at most 131072 bytes (128 KiB) decoded.
            Send null or an empty string to remove the current notification avatar;
            omit the field to leave it alone.
    PatchedSleepPolicyRequest:
      type: object
      description: Serializer for the assistant sleep/wake policy.
      properties:
        idle_timeout_seconds:
          type: integer
          minimum: 0
          description: Seconds of inactivity before the assistant is put to sleep.
            0 = never sleep.
    PatchedUpgradePolicyRequest:
      type: object
      properties:
        enabled:
          type: boolean
        timezone:
          type: string
          minLength: 1
          maxLength: 64
        schedule:
          $ref: '#/components/schemas/UpgradePolicyScheduleRequest'
    PauseRuleCreateRequest:
      type: object
      description: Serializer for creating a pause/mute rule.
      properties:
        notification_type:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/NotificationTypeEnum'
          - $ref: '#/components/schemas/NullEnum'
        dedupe_key_prefix:
          type: string
          description: If set, rule applies only to notifications whose dedupe_key
            starts with this value.
          maxLength: 255
        reason:
          type: string
          description: Human-readable explanation for the mute rule.
          maxLength: 255
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: When this rule expires; NULL means it never expires.
    PauseRuleRead:
      type: object
      description: Read serializer for a pause/mute rule.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        notification_type:
          readOnly: true
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/NotificationTypeEnum'
          - $ref: '#/components/schemas/NullEnum'
        dedupe_key_prefix:
          type: string
          readOnly: true
          description: If set, rule applies only to notifications whose dedupe_key
            starts with this value.
        reason:
          type: string
          readOnly: true
          description: Human-readable explanation for the mute rule.
        expires_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
          description: When this rule expires; NULL means it never expires.
        created:
          type: string
          format: date-time
          readOnly: true
      required:
      - created
      - dedupe_key_prefix
      - expires_at
      - id
      - notification_type
      - reason
    PlanCatalogEntry:
      oneOf:
      - $ref: '#/components/schemas/BasePlan'
      - $ref: '#/components/schemas/ProPlan'
      discriminator:
        propertyName: id
        mapping:
          base: '#/components/schemas/BasePlan'
          pro: '#/components/schemas/ProPlan'
    PlanIdEnum:
      enum:
      - base
      - pro
      type: string
      description: |-
        * `base` - base
        * `pro` - pro
    PlanListResponse:
      type: object
      properties:
        plans:
          type: array
          items:
            $ref: '#/components/schemas/PlanCatalogEntry'
          description: Plan catalog entries. Each entry is either a BasePlan or a
            ProPlan, discriminated by ``id``.
      required:
      - plans
    PreviewChannelOptInResult:
      type: object
      properties:
        detail:
          type: string
        release_channel:
          type: string
        version:
          type: string
        backup:
          $ref: '#/components/schemas/PreviewSafetyBackup'
      required:
      - backup
      - detail
      - release_channel
      - version
    PreviewChannelOptOutRequestRequest:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/ModeEnum'
        snapshot_name:
          type: string
          minLength: 1
      required:
      - mode
    PreviewChannelOptOutResult:
      type: object
      properties:
        detail:
          type: string
        release_channel:
          type: string
        version:
          type: string
          nullable: true
        backup:
          $ref: '#/components/schemas/PreviewSafetyBackup'
        restore:
          type: object
          additionalProperties: {}
      required:
      - detail
      - release_channel
      - version
    PreviewSafetyBackup:
      type: object
      properties:
        snapshot_name:
          type: string
        pvc:
          type: string
        created_at:
          type: string
          format: date-time
        ready_to_use:
          type: boolean
        backup_type:
          type: string
        source_release_channel:
          type: string
          nullable: true
        source_release_version:
          type: string
          nullable: true
        expires_at:
          type: string
          format: date-time
          nullable: true
      required:
      - backup_type
      - ready_to_use
      - snapshot_name
    ProMachineResizeRequestRequest:
      type: object
      properties:
        machine_size:
          $ref: '#/components/schemas/MachineSizeEnum'
      required:
      - machine_size
    ProMachineResizeResponse:
      type: object
      properties:
        machine_size:
          $ref: '#/components/schemas/MachineSizeEnum'
        updated:
          type: integer
        skipped:
          type: integer
        failures:
          type: integer
      required:
      - failures
      - machine_size
      - skipped
      - updated
    ProPackage:
      type: object
      description: |-
        A named Pro package preset (Mighty/Super/Ultra) at its current version.

        Component prices mirror the tier entries above; ``total_price_cents`` is
        the sum of the four ``*_price_cents`` components.
      properties:
        key:
          type: string
        name:
          type: string
        description:
          type: string
        version:
          type: integer
          minimum: 1
        machine_tier:
          type: string
          nullable: true
        storage_tier:
          type: string
        credit_tier:
          type: string
          nullable: true
        machine_size:
          type: string
          nullable: true
        storage_gib:
          type: integer
          minimum: 0
        credits_usd:
          type: integer
          minimum: 0
          nullable: true
        usage_label:
          type: string
          nullable: true
          description: 'Customer-facing name for the included-usage line item, e.g.
            "Mighty Usage". Render verbatim rather than composing a string from credits_usd:
            this is the same wording the Stripe product carries, so the plan card
            and the invoice line agree. Null exactly when credits_usd is — a package
            with no credit bundle has no usage line item to name.'
        include_platform_fee:
          type: boolean
        base_price_cents:
          type: integer
          minimum: 0
        machine_price_cents:
          type: integer
          minimum: 0
        storage_price_cents:
          type: integer
          minimum: 0
        credit_price_cents:
          type: integer
          minimum: 0
        total_price_cents:
          type: integer
          minimum: 0
      required:
      - base_price_cents
      - credit_price_cents
      - credit_tier
      - credits_usd
      - description
      - include_platform_fee
      - key
      - machine_price_cents
      - machine_size
      - machine_tier
      - name
      - storage_gib
      - storage_price_cents
      - storage_tier
      - total_price_cents
      - usage_label
      - version
    ProPlan:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ProPlanIdEnum'
        name:
          type: string
        base_price_cents:
          type: integer
          minimum: 0
        base_lookup_key:
          type: string
        billing_interval:
          $ref: '#/components/schemas/BillingIntervalEnum'
        machine_tiers:
          type: array
          items:
            $ref: '#/components/schemas/MachineTier'
        storage_tiers:
          type: array
          items:
            $ref: '#/components/schemas/StorageTier'
        included_features:
          type: array
          items:
            type: string
        credit_tiers:
          type: array
          items:
            $ref: '#/components/schemas/CreditTier'
        packages:
          type: array
          items:
            $ref: '#/components/schemas/ProPackage'
      required:
      - base_lookup_key
      - base_price_cents
      - billing_interval
      - id
      - included_features
      - machine_tiers
      - name
      - packages
      - storage_tiers
    ProPlanIdEnum:
      enum:
      - pro
      type: string
      description: '* `pro` - pro'
    ReleaseChannelEnum:
      enum:
      - stable
      - preview
      type: string
      description: |-
        * `stable` - Stable
        * `preview` - Preview
    ReleaseChannelRelease:
      type: object
      properties:
        version:
          type: string
        released_at:
          type: string
          format: date-time
      required:
      - released_at
      - version
    ReleaseChannelStatus:
      type: object
      properties:
        feature_enabled:
          type: boolean
        current_channel:
          type: string
        latest_stable_release:
          allOf:
          - $ref: '#/components/schemas/ReleaseChannelRelease'
          nullable: true
        latest_preview_release:
          allOf:
          - $ref: '#/components/schemas/ReleaseChannelRelease'
          nullable: true
        preview_backups:
          type: array
          items:
            $ref: '#/components/schemas/PreviewSafetyBackup'
        preview_backup_count:
          type: integer
        preview_backup_limit:
          type: integer
        preview_backup_limit_reached:
          type: boolean
        standard_upgrade_available:
          type: boolean
      required:
      - current_channel
      - feature_enabled
      - latest_preview_release
      - latest_stable_release
      - preview_backup_count
      - preview_backup_limit
      - preview_backup_limit_reached
      - preview_backups
      - standard_upgrade_available
    ReleaseListItem:
      type: object
      properties:
        version:
          type: string
          maxLength: 64
        released_at:
          type: string
          format: date-time
        is_stable:
          type: boolean
        assistant_image_ref:
          type: string
          readOnly: true
        gateway_image_ref:
          type: string
          readOnly: true
        credential_executor_image_ref:
          type: string
          nullable: true
          readOnly: true
        description:
          type: string
          nullable: true
          readOnly: true
        url:
          type: string
          readOnly: true
        commit_sha:
          type: string
          nullable: true
          readOnly: true
      required:
      - assistant_image_ref
      - commit_sha
      - credential_executor_image_ref
      - description
      - gateway_image_ref
      - released_at
      - url
      - version
    ReturnTargetEnum:
      enum:
      - web
      - native
      type: string
      description: |-
        * `web` - web
        * `native` - native
    RollbackRequestRequest:
      type: object
      properties:
        version:
          type: string
          nullable: true
          minLength: 1
    RollbackResult:
      type: object
      properties:
        detail:
          type: string
        version:
          type: string
          nullable: true
      required:
      - detail
      - version
    SleepPolicy:
      type: object
      description: Serializer for the assistant sleep/wake policy.
      properties:
        idle_timeout_seconds:
          type: integer
          minimum: 0
          description: Seconds of inactivity before the assistant is put to sleep.
            0 = never sleep.
    SnoozeRequest:
      type: object
      description: Serializer for snooze-until action.
      properties:
        snoozed_until:
          type: string
          format: date-time
          nullable: true
      required:
      - snoozed_until
    SnoozeResponse:
      type: object
      description: Response serializer for snooze action.
      properties:
        id:
          type: string
          format: uuid
        snoozed_until:
          type: string
          format: date-time
          nullable: true
      required:
      - id
      - snoozed_until
    SourceEnum:
      enum:
      - django
      - vembda
      type: string
      description: |-
        * `django` - Django
        * `vembda` - Vembda
    StorageTier:
      type: object
      properties:
        tier:
          type: string
        label:
          type: string
        storage_gib:
          type: integer
          minimum: 0
        price_cents:
          type: integer
          minimum: 0
        lookup_key:
          type: string
        legacy:
          type: boolean
          description: 'True only for a grandfathered tier: no longer offered, present
            in the catalog solely because it is the org''s current tier.'
      required:
      - label
      - legacy
      - lookup_key
      - price_cents
      - storage_gib
      - tier
    StorageTierChangeRequestRequest:
      type: object
      properties:
        storage_tier:
          $ref: '#/components/schemas/StorageTierEnum'
      required:
      - storage_tier
    StorageTierChangeResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/TierChangeStatusEnum'
        storage_tier:
          $ref: '#/components/schemas/StorageTierEnum'
      required:
      - status
      - storage_tier
    StorageTierEnum:
      enum:
      - xs
      - s
      - m
      - l
      - xl
      - xxl
      type: string
      description: |-
        * `xs` - xs
        * `s` - s
        * `m` - m
        * `l` - l
        * `xl` - xl
        * `xxl` - xxl
    SubscriptionCancelRequestRequest:
      type: object
      description: |-
        Optional cancel survey forwarded to Stripe as ``cancellation_details``.

        Both fields are optional and additive: the endpoint historically took no
        body, and older native clients still post an empty one. ``feedback`` is
        Stripe's fixed vocabulary (the same set the Customer Portal's cancel
        survey offers; send ``null`` or omit it for "no answer"); ``comment`` is
        free text, and a blank/whitespace-only comment is treated as not
        provided so a client that submits an empty form sends nothing to Stripe.
      properties:
        feedback:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/CancellationFeedbackEnum'
          - $ref: '#/components/schemas/NullEnum'
        comment:
          type: string
          nullable: true
          maxLength: 1000
    SubscriptionCancelResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/TierChangeStatusEnum'
        cancel_at:
          type: string
          format: date-time
          nullable: true
      required:
      - cancel_at
      - status
    SubscriptionEntitlements:
      type: object
      description: |-
        Plan-gated feature entitlements for the current org.

        Mirrors app.billing.entitlements.has_entitlement(), so admin
        EntitlementOverride grants are reflected here regardless of plan.
        Scope matches ADMIN_GRANTABLE_FEATURES.
      properties:
        managed_email:
          type: boolean
        phone_number:
          type: boolean
      required:
      - managed_email
      - phone_number
    SubscriptionPackage:
      type: object
      description: The named Pro package the org subscribed under (its account pin).
      properties:
        key:
          type: string
        name:
          type: string
        version:
          type: integer
          minimum: 1
        customized:
          type: boolean
      required:
      - customized
      - key
      - name
      - version
    SubscriptionReactivateResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/TierChangeStatusEnum'
        current_period_end:
          type: string
          format: date-time
          nullable: true
      required:
      - current_period_end
      - status
    SubscriptionResponse:
      type: object
      properties:
        plan_id:
          $ref: '#/components/schemas/PlanIdEnum'
        status:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/SubscriptionStatusEnum'
          - $ref: '#/components/schemas/NullEnum'
        renewal_date:
          type: string
          format: date-time
          nullable: true
        current_period_start:
          type: string
          format: date-time
          nullable: true
        current_period_end:
          type: string
          format: date-time
          nullable: true
        cancel_at_period_end:
          type: boolean
        cancel_at:
          type: string
          format: date-time
          nullable: true
        selected_credit_tier:
          type: string
          nullable: true
        package:
          allOf:
          - $ref: '#/components/schemas/SubscriptionPackage'
          nullable: true
        has_platform_fee:
          type: boolean
        entitlements:
          $ref: '#/components/schemas/SubscriptionEntitlements'
      required:
      - cancel_at
      - cancel_at_period_end
      - current_period_end
      - entitlements
      - plan_id
      - renewal_date
      - status
    SubscriptionStatusEnum:
      enum:
      - active
      - trialing
      - past_due
      - canceled
      - incomplete
      - incomplete_expired
      - unpaid
      - paused
      type: string
      description: |-
        * `active` - active
        * `trialing` - trialing
        * `past_due` - past_due
        * `canceled` - canceled
        * `incomplete` - incomplete
        * `incomplete_expired` - incomplete_expired
        * `unpaid` - unpaid
        * `paused` - paused
    SubscriptionUpgradeRequestRequest:
      type: object
      properties:
        machine_tier:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/MachineTierEnum'
          - $ref: '#/components/schemas/NullEnum'
        storage_tier:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/StorageTierEnum'
          - $ref: '#/components/schemas/NullEnum'
        package:
          type: string
          nullable: true
          minLength: 1
          pattern: ^[-a-zA-Z0-9_]+$
        target_plan_id:
          $ref: '#/components/schemas/PlanIdEnum'
        confirm:
          type: boolean
        credit_tier:
          nullable: true
          oneOf:
          - $ref: '#/components/schemas/CreditTierEnum'
          - $ref: '#/components/schemas/NullEnum'
        include_platform_fee:
          type: boolean
          default: true
        return_target:
          allOf:
          - $ref: '#/components/schemas/ReturnTargetEnum'
          default: web
      required:
      - confirm
      - target_plan_id
    SubscriptionUpgradeResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/SubscriptionUpgradeResponseStatusEnum'
        checkout_url:
          type: string
          nullable: true
        message:
          type: string
      required:
      - checkout_url
      - message
      - status
    SubscriptionUpgradeResponseStatusEnum:
      enum:
      - redirect
      - no_op
      type: string
      description: |-
        * `redirect` - redirect
        * `no_op` - no_op
    SystemEventTypeEnum:
      enum:
      - lifecycle
      - upgrade
      - rollback
      - crash
      - idle_sleep
      - wake
      - profiler
      - other
      type: string
      description: |-
        * `lifecycle` - Lifecycle
        * `upgrade` - Upgrade
        * `rollback` - Rollback
        * `crash` - Crash
        * `idle_sleep` - Idle Sleep
        * `wake` - Wake
        * `profiler` - Profiler
        * `other` - Other
    TelemetryIngestRequestRequest:
      type: object
      properties:
        device_id:
          type: string
          minLength: 1
          maxLength: 255
        installation_id:
          type: string
          minLength: 1
          maxLength: 255
        assistant_version:
          type: string
          nullable: true
          minLength: 1
          maxLength: 64
        events:
          type: array
          items:
            type: object
            additionalProperties: {}
      required:
      - events
    TelemetryIngestResponse:
      type: object
      properties:
        accepted:
          type: integer
        persisted:
          type: integer
        dropped:
          type: object
          additionalProperties:
            type: integer
      required:
      - accepted
      - dropped
      - persisted
    TierChangeStatusEnum:
      enum:
      - ok
      - no_op
      type: string
      description: |-
        * `ok` - ok
        * `no_op` - no_op
    TopUpCheckoutRequestRequest:
      type: object
      description: |-
        Validates the incoming top-up checkout request.

        Exactly one of ``amount`` or ``amount_usd`` must be provided. If both are
        provided, ``amount`` takes precedence.  The resolved value is normalised
        into ``amount_usd`` in validated data so downstream code is unchanged.
      properties:
        amount:
          type: string
          minLength: 1
          description: Amount as a decimal string (e.g. '25.00'). Must have exactly
            two decimal places. Preferred over amount_usd.
        amount_usd:
          type: string
          minLength: 1
          description: Deprecated. Amount in USD as a decimal string (e.g. '25.00').
            Must have exactly two decimal places. Use 'amount' instead.
        return_path:
          type: string
          minLength: 1
          default: /assistant/settings/billing
          description: Client-side path to redirect to after checkout completes. Ignored
            when return_target is 'native'.
        return_target:
          allOf:
          - $ref: '#/components/schemas/ReturnTargetEnum'
          default: web
    TopUpCheckoutResponse:
      type: object
      description: Response body for a successfully created top-up checkout session.
      properties:
        billing_top_up_id:
          type: string
          format: uuid
        checkout_url:
          type: string
          format: uri
        requested_amount:
          type: string
        requested_amount_usd:
          type: string
      required:
      - billing_top_up_id
      - checkout_url
      - requested_amount
      - requested_amount_usd
    UpgradePolicy:
      type: object
      properties:
        enabled:
          type: boolean
        timezone:
          type: string
          maxLength: 64
        schedule:
          $ref: '#/components/schemas/UpgradePolicySchedule'
    UpgradePolicySchedule:
      type: object
      properties:
        frequency:
          $ref: '#/components/schemas/FrequencyEnum'
        days_of_week:
          type: array
          items:
            type: integer
            maximum: 6
            minimum: 0
        days_of_month:
          type: array
          items:
            type: integer
            maximum: 31
            minimum: 1
        window:
          $ref: '#/components/schemas/UpgradePolicyWindow'
      required:
      - frequency
      - window
    UpgradePolicyScheduleRequest:
      type: object
      properties:
        frequency:
          $ref: '#/components/schemas/FrequencyEnum'
        days_of_week:
          type: array
          items:
            type: integer
            maximum: 6
            minimum: 0
        days_of_month:
          type: array
          items:
            type: integer
            maximum: 31
            minimum: 1
        window:
          $ref: '#/components/schemas/UpgradePolicyWindowRequest'
      required:
      - frequency
      - window
    UpgradePolicyWindow:
      type: object
      properties:
        start:
          type: string
          pattern: ^([01]\d|2[0-3]):([0-5]\d)$
        end:
          type: string
          pattern: ^([01]\d|2[0-3]):([0-5]\d)$
      required:
      - end
      - start
    UpgradePolicyWindowRequest:
      type: object
      properties:
        start:
          type: string
          minLength: 1
          pattern: ^([01]\d|2[0-3]):([0-5]\d)$
        end:
          type: string
          minLength: 1
          pattern: ^([01]\d|2[0-3]):([0-5]\d)$
      required:
      - end
      - start
    UpgradeRequestRequest:
      type: object
      properties:
        version:
          type: string
          nullable: true
          minLength: 1
    UpgradeResult:
      type: object
      properties:
        detail:
          type: string
        version:
          type: string
          nullable: true
      required:
      - detail
      - version
    UpgradeStatus:
      type: object
      description: |-
        Response shape for the upgrade-status read endpoint.

        `in_progress` reflects whether the `assistant:update-lifecycle:<id>`
        Redis lock is currently held by an in-flight upgrade or rollback.
        Clients use this to proactively disable the Upgrade button rather
        than only soft-handling a 409 from POST /upgrade/.
      properties:
        in_progress:
          type: boolean
      required:
      - in_progress
    UsageBucket:
      type: object
      properties:
        date:
          type: string
          description: Bucket start date in YYYY-MM-DD format.
        groups:
          type: array
          items:
            $ref: '#/components/schemas/UsageGroup'
          description: Usage groups within this bucket.
      required:
      - date
      - groups
    UsageGroup:
      type: object
      properties:
        group_key:
          type: string
          description: Raw grouping value (e.g. 'runtime_proxy_api', 'claude-opus-4-6').
        group_label:
          type: string
          description: Human-readable display label.
        total_usd:
          type: string
          description: Total spend in USD as a decimal string.
        event_count:
          type: integer
          description: Number of usage events.
      required:
      - event_count
      - group_key
      - group_label
      - total_usd
    UsageSeriesResponse:
      type: object
      properties:
        buckets:
          type: array
          items:
            $ref: '#/components/schemas/UsageBucket'
          description: Time-ordered usage buckets.
      required:
      - buckets
    UsageTotalsResponse:
      type: object
      properties:
        total_usd:
          type: string
          description: Total spend in USD as a decimal string.
        event_count:
          type: integer
          description: Number of usage events.
      required:
      - event_count
      - total_usd
    UserConsent:
      type: object
      properties:
        tos_accepted_version:
          type: string
          maxLength: 32
        tos_accepted_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        privacy_policy_accepted_version:
          type: string
          maxLength: 32
        privacy_policy_accepted_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        ai_data_sharing_accepted_version:
          type: string
          maxLength: 32
        ai_data_sharing_accepted_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        share_analytics:
          type: boolean
          nullable: true
        share_diagnostics:
          type: boolean
          nullable: true
        share_analytics_effective:
          type: boolean
          readOnly: true
        share_diagnostics_effective:
          type: boolean
          readOnly: true
        share_analytics_accepted_version:
          type: string
          maxLength: 32
        share_analytics_accepted_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        share_diagnostics_accepted_version:
          type: string
          maxLength: 32
        share_diagnostics_accepted_at:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        required_versions:
          type: object
          additionalProperties:
            type: string
          readOnly: true
      required:
      - ai_data_sharing_accepted_at
      - privacy_policy_accepted_at
      - required_versions
      - share_analytics_accepted_at
      - share_analytics_effective
      - share_diagnostics_accepted_at
      - share_diagnostics_effective
      - tos_accepted_at
    UserConsentRequest:
      type: object
      properties:
        tos_accepted_version:
          type: string
          maxLength: 32
        privacy_policy_accepted_version:
          type: string
          maxLength: 32
        ai_data_sharing_accepted_version:
          type: string
          maxLength: 32
        share_analytics:
          type: boolean
          nullable: true
        share_diagnostics:
          type: boolean
          nullable: true
        share_analytics_accepted_version:
          type: string
          maxLength: 32
        share_diagnostics_accepted_version:
          type: string
          maxLength: 32
    UserOutcomeEnum:
      enum:
      - resolved
      - not_resolved
      type: string
      description: |-
        * `resolved` - Resolved
        * `not_resolved` - Not resolved
  securitySchemes:
    AssistantAPIKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key passed as 'Api-Key <key>' in the Authorization header.
    SDKCompatibleAssistantKey:
      type: apiKey
      in: header
      name: Authorization
      description: Assistant API key via 'Api-Key <key>', 'Bearer <key>', X-Api-Key
        header, or ?key= query parameter.
    VellumAPIKey:
      type: http
      scheme: bearer
      description: Platform API key passed as 'Bearer vak_...' in the Authorization
        header.
    XSessionTokenAuth:
      type: apiKey
      in: header
      name: X-Session-Token
      description: X-Session-Token authentication
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid