# Generated by scripts/build-specs.ts from specs/. Edit the sources, then run `npm run specs`.
openapi: 3.1.1
info:
  title: orgasm.dev API
  version: 1.0.0
  summary: Orgasm imminence, onset, peak and end from a front-facing camera.
  description: |
    orgasm.dev turns a live camera stream or a recorded video of a person's
    face into events about their orgasm: how likely it is to begin within the
    next 30 and 60 seconds (`imminence.updated`), when it begins
    (`orgasm.onset`), peaks (`orgasm.peak`) and ends (`orgasm.end`), and
    whether the face reads as a woman's or a man's (`subject.identified`),
    which decides the detectors that apply. You never have to say which.

    There are two ways in, and they are separate endpoints:

    - **Live sessions** (`POST /v1/live-sessions`): the end user's device
      publishes its front camera, and the microphone when it can, over WHIP.
      Events arrive within seconds over server-sent events, a WebSocket, or
      webhooks.
    - **Recordings** (`POST /v1/recordings`): you upload a video file or give
      a URL to fetch, and receive the same events as a timeline once the
      recording has been processed.

    The face is the minimum. Imminence and the subject read come from the face
    alone; onset, peak and end also need the microphone; a second camera that
    sees the body is optional. Every signal event says how complete its input
    was (`confidence`).

    Video and audio are analysed inside a confidential-computing enclave and
    are never stored; only the numbers in these events leave it. Every person
    on camera must be an adult who has agreed to the analysis, and every
    request that starts one says so (`consent`).

    **Status:** the sandbox is open: any key that starts with `sk_test_`
    reaches it, and it plays deterministic scenarios through the same
    contract. Keys that start with `sk_live_` run live sessions on attested
    enclaves; recorded videos are analysed in the sandbox only for now
    (`createRecording` with a live key answers `live_mode_unavailable`).

    **Credits:** live sessions draw on your company's prepaid credits: an
    orgasm or a ruin is a credit, an edge (`edge.completed`) half a credit, and
    a session that counts none of them half a credit. Each session reports its
    `charges`, and `getCredits` the balance. Every company domain starts with
    20 free credits; the sandbox is free. See
    <https://orgasm.dev/docs/credits>.

    **Costs:** create each session with a `userReference` (a pseudonymous id
    of yours for the person, never their email or name) and a
    `clientReferenceId` (your own id for the session), and `listCharges`
    returns what each charge cost in dollars with them, so your Finance team
    can break your costs down by person, session and `metadata` value.

    Events are described in full in the AsyncAPI document,
    <https://orgasm.dev/asyncapi.json>.
  contact:
    name: orgasm.dev
    url: https://orgasm.dev/docs
  license:
    name: Proprietary
servers:
  - url: https://orgasm.dev
    description: "`sk_test_` keys reach the sandbox. `sk_live_` keys are refused until live analysis is available."
  - url: http://localhost:3000
    description: The docs site running locally (`npm run dev`), which serves the sandbox.
  - url: http://localhost:4010
    description: The standalone sandbox (`npm run mock`), which also serves the WebSocket channel.
security:
  - secretKey: []
externalDocs:
  description: Guides, concepts and the event reference
  url: https://orgasm.dev/docs
tags:
  - name: live-sessions
    x-displayName: Live sessions
    description: A live camera stream from the end user's device, analysed as it arrives.
  - name: recordings
    x-displayName: Recordings
    description: A recorded video, analysed after upload. Same events, delivered as a timeline.
  - name: webhooks
    x-displayName: Webhooks
    description: Endpoints on your server that receive events as signed HTTP POSTs.
  - name: account
    x-displayName: Account
    description: Usage, credits, charges, models and API keys.
  - name: trust
    x-displayName: Trust
    description: What a device verifies before it sends any media.
  - name: sandbox
    x-displayName: Sandbox
    description: Endpoints that exist only in test mode.
paths:
  /v1/live-sessions:
    post:
      operationId: createLiveSession
      tags:
        - live-sessions
      summary: Create a live session
      description: |
        Starts analysis capacity for one person's live camera stream and
        returns where their device publishes (`ingest`) and where events
        arrive (`results`).

        Call this from your server with a secret key. Pass the SHA-256 of a
        capability the device generated (`capabilityHash`), so that only that
        device can publish and orgasm.dev's servers never hold the capability
        itself. Hand `ingest` and `results.clientToken` to the device; it
        verifies the enclave's attestation, then publishes over WHIP.

        Next: read events from `results.streamUrl` (server-sent events) or
        `results.websocketUrl`, or poll `listLiveSessionEvents` with `wait`.
        Call `endLiveSession` when the experience is over.

        A live session draws on your company's credits as it counts orgasms,
        ruins and edges (`charges`). With none left it is refused with
        `credits_exhausted` (402); sessions already running finish. Check the
        balance with `getCredits`.

        So that your costs break down by person and by your own session, pass
        `userReference` and `clientReferenceId`: `listCharges` returns them
        with what each charge cost. Make `userReference` pseudonymous, for
        example the HMAC-SHA256 of your user id under a key only you hold.

        In the sandbox no media is published: the session moves through its
        statuses on its own and plays `sandbox.scenario`. It is free: it counts
        `charges` as a live session would, with no credits drawn.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        description: The consent attestation, the inputs the device will publish, and options.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LiveSessionCreateRequest"
            examples:
              sandbox:
                summary: Sandbox session that plays a woman's onset and end
                value:
                  consent:
                    subjectIsAdult: true
                    subjectConsented: true
                    ageVerification: document
                    consentedAt: 2026-10-16T13:58:00Z
                  inputs:
                    audio: true
                  sandbox:
                    scenario: woman-onset-end
                    speed: 10
                  userReference: 9f2c41ab7e05d3a86b1c
                  clientReferenceId: round_1842
                  metadata:
                    plan: premium
              live:
                summary: Live session with a device capability
                value:
                  consent:
                    subjectIsAdult: true
                    subjectConsented: true
                    ageVerification: third_party_service
                    consentedAt: 2026-10-16T13:58:00Z
                    consentRecordId: cr_77120
                  inputs:
                    audio: true
                    body: false
                  capabilityHash: 3f9a4c1be0d28e7a56b1c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718
                  maxDurationS: 3600
                  retentionDays: 7
                  userReference: 9f2c41ab7e05d3a86b1c
                  clientReferenceId: round_1842
                  metadata:
                    plan: premium
      responses:
        "201":
          description: The session was created. Its status starts at `starting`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiveSession"
              examples:
                sandbox:
                  $ref: "#/components/examples/LiveSessionStarting"
          headers:
            Request-Id: &a1
              $ref: "#/components/headers/RequestId"
            RateLimit-Limit: &a2
              $ref: "#/components/headers/RateLimitLimit"
            RateLimit-Remaining: &a3
              $ref: "#/components/headers/RateLimitRemaining"
            RateLimit-Reset: &a4
              $ref: "#/components/headers/RateLimitReset"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
    get:
      operationId: listLiveSessions
      tags:
        - live-sessions
      summary: List live sessions
      description: Lists your company's live sessions, newest first.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: status
          in: query
          description: Only sessions with this status.
          schema:
            $ref: "#/components/schemas/LiveSessionStatus"
        - $ref: "#/components/parameters/UserReferenceFilter"
        - $ref: "#/components/parameters/ClientReferenceIdFilter"
      responses:
        "200":
          description: A page of sessions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiveSessionList"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/live-sessions/purge:
    post:
      operationId: purgeLiveSessionsByUserReference
      tags:
        - live-sessions
      summary: Purge a person's live sessions
      description: |
        Purges every live session created with this `userReference`, as
        `purgeLiveSession` does one: each is ended if it is still running,
        then deleted with all its events. Its `userReference`,
        `clientReferenceId` and metadata are erased from your company's
        charges, which stay, unattributed, for your accounts and ours. Use it
        to honour a person's request to delete their data. Webhook deliveries
        already made are not recalled. Cannot be undone.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        description: The person's `userReference`.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LiveSessionPurgeRequest"
            examples:
              person:
                summary: Every session of one person
                value:
                  userReference: 9f2c41ab7e05d3a86b1c
      responses:
        "200":
          description: The sessions that were purged, possibly none.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiveSessionPurgeResult"
              examples:
                purged:
                  $ref: "#/components/examples/LiveSessionsPurged"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/live-sessions/{sessionId}:
    parameters:
      - $ref: "#/components/parameters/SessionId"
    get:
      operationId: getLiveSession
      tags:
        - live-sessions
      summary: Get a live session
      description: |
        Returns the session's status, which inputs are arriving, the subject
        read once it is made, and the latest imminence (`latestImminence`).
        Works with the session's client token as well as a secret key.
      security:
        - secretKey: []
        - clientToken: []
      responses:
        "200":
          description: The session.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiveSession"
              examples:
                analyzing:
                  $ref: "#/components/examples/LiveSessionAnalyzing"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    delete:
      operationId: endLiveSession
      tags:
        - live-sessions
      summary: End a live session
      description: |
        Ends the session now: the device's connection is closed, a final
        `session.status` with `endedReason: client_ended` is emitted, and the
        analysis capacity is released. Ending an ended session returns it
        unchanged. The session's events stay readable until
        `resultsExpireAt`.
      responses:
        "200":
          description: The ended session.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LiveSession"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/live-sessions/{sessionId}/purge:
    parameters:
      - $ref: "#/components/parameters/SessionId"
    post:
      operationId: purgeLiveSession
      tags:
        - live-sessions
      summary: Purge a live session
      description: |
        Ends the session if it is still running, then deletes it and all its
        events now rather than at `resultsExpireAt`, and erases its
        `userReference`, `clientReferenceId` and metadata from your company's
        charges, which stay, unattributed. Use it to honour a person's request
        to delete their data; `purgeLiveSessionsByUserReference` does it for
        every session of one person. Webhook deliveries already made are not
        recalled. Cannot be undone.
      responses:
        "200":
          description: The session and its events were deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deleted"
              examples:
                purged:
                  value:
                    id: ls_8f3kq2m7x9w4c1n6t5ra
                    object: live_session
                    deleted: true
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/live-sessions/{sessionId}/events:
    parameters:
      - $ref: "#/components/parameters/SessionId"
    get:
      operationId: listLiveSessionEvents
      tags:
        - live-sessions
      summary: List a live session's events
      description: |
        Returns the session's events in order, oldest first. Pass the last
        event `id` you have as `after` to receive only newer ones, and `wait`
        to hold the request open until at least one arrives (long polling).
        This is the simplest way for an agent or a server without a stream
        client to follow a session.
      security:
        - secretKey: []
        - clientToken: []
        - viewToken: []
      parameters:
        - $ref: "#/components/parameters/EventsAfter"
        - $ref: "#/components/parameters/EventTypes"
        - $ref: "#/components/parameters/EventsLimit"
        - $ref: "#/components/parameters/Wait"
      responses:
        "200":
          description: A page of events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventList"
              examples:
                onset:
                  $ref: "#/components/examples/EventListOnset"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/live-sessions/{sessionId}/stream:
    parameters:
      - $ref: "#/components/parameters/SessionId"
    get:
      operationId: streamLiveSessionEvents
      tags:
        - live-sessions
      summary: Stream a live session's events
      description: |
        A server-sent events stream of the session's events. Each event is
        sent with `id:` set to the event's `id`, `event:` set to its `type`,
        and `data:` set to the event as JSON; a comment line is sent every 15
        seconds to keep the connection open. The stream closes after the
        session's final `session.status`.

        To resume after a dropped connection, reconnect with
        `Last-Event-ID` (browsers do this for you) or `after`; events you
        missed are replayed first. Browsers cannot set headers on an
        `EventSource`, so pass the client token as `token` instead, or read
        the stream with `fetch`, as `@orgasm-dev/device`'s `subscribe` does.
        A view token is accepted in the header only, never in the URL.

        A session serves at most 12 streams at once, whoever reads them,
        sockets included; another is refused with 429 `rate_limited` until
        one closes.

        With `frames=face` the stream also carries `face.frame` messages about
        five times a second: the face's channels for a display that draws it,
        between the once-a-second `signals.updated`. They have no `id:` line,
        are never stored or replayed, and a reader that falls behind skips to
        the newest. A view token gets them only when made with `includeFace`.

        The message schemas are in the AsyncAPI document
        (`liveSessionStream` channel).
      security:
        - secretKey: []
        - clientToken: []
        - clientTokenQuery: []
        - viewToken: []
      x-mcp-exclude: true
      parameters:
        - $ref: "#/components/parameters/EventsAfter"
        - $ref: "#/components/parameters/EventTypes"
        - $ref: "#/components/parameters/Frames"
        - name: Last-Event-ID
          in: header
          description: The `id` of the last event you received; events after it are replayed.
          schema:
            type: string
            pattern: ^evt_[0-9a-z]{20}$
      responses:
        "200":
          description: The stream.
          content:
            text/event-stream:
              schema:
                type: string
              example: |+
                id: evt_1ayxm16hy930duw499dv
                event: imminence.updated
                data: {"id":"evt_1ayxm16hy930duw499dv","object":"event","type":"imminence.updated","mode":"test","sessionId":"ls_8f3kq2m7x9w4c1n6t5ra","sequence":967,"streamTimeS":542,"confidence":"high","data":{"p30":0.868,"p60":0.983,"logit30":1.89,"logit60":4.04,"featuresPresent":0.95,"faceVisible":true,"baselineReady":true,"stimulationAware":false,"recentCalls":[]},"wallTime":"2026-10-16T14:00:55.200Z"}

                id: evt_2099smltv0t2c2wzzyzq
                event: orgasm.onset
                data: {"id":"evt_2099smltv0t2c2wzzyzq","object":"event","type":"orgasm.onset","mode":"test","sessionId":"ls_8f3kq2m7x9w4c1n6t5ra","sequence":969,"streamTimeS":542.6,"confidence":"high","data":{"orgasmIndex":1,"eventAtS":538,"calledAtS":542.6,"lagS":4.6,"detector":"onset_end","score":0.71,"threshold":0.5},"wallTime":"2026-10-16T14:00:55.260Z"}

          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/live-sessions/{sessionId}/view-tokens:
    parameters:
      - $ref: "#/components/parameters/SessionId"
    post:
      operationId: createViewToken
      tags:
        - live-sessions
      summary: Create a view token
      description: |
        A read-only token for one session's events, for a screen other than
        the person's device: a heads-up display drawn into a stream, a
        coach's view, a second monitor. It reads the session's events through
        the stream and the event list, in the `Authorization` header only, and
        nothing else: it cannot report stimulation, and it cannot read the
        session object with its metadata and references.

        `subject.identified` is left out unless `includeSubject` is true: the
        face read is the person's, and a display others watch should not show
        it unasked. For the same reason the face's channels, in
        `signals.updated` and in `face.frame`, are left out unless
        `includeFace` is true. The token stops working at `expiresAt`, or five
        minutes after the session ends, whichever comes first. Make one per
        screen.
      security:
        - secretKey: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        description: What the token may read, and for how long.
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateViewTokenRequest"
            examples:
              overlay:
                summary: For a stream overlay, for three hours
                value:
                  expiresInS: 10800
              coach:
                summary: For a coach who also sees the face read and the face
                value:
                  includeSubject: true
                  includeFace: true
      responses:
        "201":
          description: The token. It is shown only here.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewToken"
              examples:
                created:
                  $ref: "#/components/examples/ViewTokenCreated"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/live-sessions/{sessionId}/stimulation:
    parameters:
      - $ref: "#/components/parameters/SessionId"
    post:
      operationId: reportStimulation
      tags:
        - live-sessions
      summary: Report stimulation
      description: |
        Tells the analysis when stimulation starts, stops or changes, if your
        product controls it (a device, an e-stim unit, a scene). Imminence
        read from the face alone does not know how long the person has been
        stimulated; once you report it, imminence accounts for that, and
        `imminence.updated` carries `stimulationAware: true`.

        Report the device too, and a heads-up display can show it beside the
        person's signals: its level and the most it will go to, each
        channel's level, its mode, and who sets the level. A report updates
        the fields it carries and keeps the ones it omits; send `null` to
        clear one. Each report reaches the session's readers as
        `stimulation.updated`, at most four a second, reports in between
        merged into the next.

        Report every change, not a heartbeat. Optional; works with the
        session's client token, so a device can report for itself. A device
        that changes often can send the same report as a `stimulation`
        message on the socket (`results.websocketUrl`) instead.

        Stopping is how orgasm.dev tells a ruin from an orgasm: an orgasm that
        begins within 30 seconds of an `off` reported while `p30` was at 0.75
        or above is a ruin, and its `orgasm.end` says `ruined: true`.
      security:
        - secretKey: []
        - clientToken: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        description: The new stimulation state.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StimulationReport"
            examples:
              on:
                summary: Stimulation started at 40 % intensity
                value:
                  state: on
                  intensity: 0.4
              device:
                summary: A two-channel unit in its waves mode, set by your product
                value:
                  state: on
                  level: 31
                  levelMax: 60
                  channels:
                    - id: a
                      level: 31
                      levelMax: 60
                    - id: b
                      level: 24
                      levelMax: 60
                  mode: waves
                  modeLabel: Waves
                  device:
                    label: Unit
                    connected: true
                  drive: auto
              level:
                summary: Only the level changed
                value:
                  state: on
                  level: 34
              off:
                summary: Stimulation stopped
                value:
                  state: off
      responses:
        "200":
          description: The report was recorded.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StimulationReceipt"
              example:
                object: stimulation_report
                sessionId: ls_8f3kq2m7x9w4c1n6t5ra
                streamTimeS: 300
                state: on
                intensity: null
                stimulationAware: true
                stimulation:
                  state: on
                  intensity: null
                  level: 34
                  levelMax: 60
                  channels:
                    - id: a
                      level: 34
                      levelMax: 60
                    - id: b
                      level: 27
                      levelMax: 60
                  mode: waves
                  modeLabel: Waves
                  device:
                    label: Unit
                    connected: true
                  drive: auto
                  changedAtS: 300
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/recordings:
    post:
      operationId: submitRecording
      tags:
        - recordings
      summary: Submit a recording
      description: |
        Submits a recorded video for analysis. Either upload the file
        (`source.type: upload`; `PUT` it to `uploads.face.url`, and to
        `uploads.body.url` if you declared a body view) or let the enclave
        fetch it (`source.type: url`).

        The video must show the person's face, in H.264 or H.265, between two
        minutes and four hours long; keep its audio track if you want onset,
        peak and end. Processing takes about as long as the recording. The
        file is deleted once it has been analysed.

        Next: wait for the `recording.completed` webhook, or poll
        `getRecording` until `status` is `completed`, then read
        `result` or `listRecordingEvents`.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        description: The consent attestation, where the video comes from, and options.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecordingCreateRequest"
            examples:
              upload:
                summary: Upload a file (sandbox)
                value:
                  consent:
                    subjectIsAdult: true
                    subjectConsented: true
                    ageVerification: document
                    consentedAt: 2026-10-16T13:58:00Z
                  source:
                    type: upload
                  sandbox:
                    scenario: man-peak
                    speed: 60
              url:
                summary: Let the enclave fetch a file
                value:
                  consent:
                    subjectIsAdult: true
                    subjectConsented: true
                    ageVerification: payment_card
                    consentedAt: 2026-10-16T13:58:00Z
                  source:
                    type: url
                    url: https://storage.example.com/sessions/1842.mp4?signature=abc
                  subjectHint: woman
                  retentionDays: 30
                  userReference: 9f2c41ab7e05d3a86b1c
                  clientReferenceId: video_1842
      responses:
        "201":
          description: "The recording was created: `awaiting_upload` for uploads, `queued` for URLs."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Recording"
              examples:
                awaitingUpload:
                  $ref: "#/components/examples/RecordingAwaitingUpload"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    get:
      operationId: listRecordings
      tags:
        - recordings
      summary: List recordings
      description: Lists your company's recordings, newest first.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: status
          in: query
          description: Only recordings with this status.
          schema:
            $ref: "#/components/schemas/RecordingStatus"
        - $ref: "#/components/parameters/UserReferenceFilter"
        - $ref: "#/components/parameters/ClientReferenceIdFilter"
      responses:
        "200":
          description: A page of recordings.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecordingList"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/recordings/{recordingId}:
    parameters:
      - $ref: "#/components/parameters/RecordingId"
    get:
      operationId: getRecording
      tags:
        - recordings
      summary: Get a recording
      description: |
        Returns the recording's status and progress and, once `completed`, its
        `result`: the subject read, a summary of each orgasm, and the timeline
        of discrete events. Imminence, sampled every second, is in
        `listRecordingEvents`.
      responses:
        "200":
          description: The recording.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Recording"
              examples:
                completed:
                  $ref: "#/components/examples/RecordingCompleted"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    delete:
      operationId: deleteRecording
      tags:
        - recordings
      summary: Delete a recording
      description: |
        Deletes the recording's results and events now and stops processing if
        it is still running. The video itself is never kept past analysis.
        Deletion cannot be undone.
      responses:
        "200":
          description: The recording was deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deleted"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/recordings/{recordingId}/events:
    parameters:
      - $ref: "#/components/parameters/RecordingId"
    get:
      operationId: listRecordingEvents
      tags:
        - recordings
      summary: List a recording's events
      description: |
        Returns the recording's full event timeline in order, including
        `imminence.updated` for every second of analysed face. Filter with
        `types` (for example `orgasm.onset,orgasm.peak,orgasm.end`) and page
        with `after`. Events appear while the recording is processing.
      parameters:
        - $ref: "#/components/parameters/EventsAfter"
        - $ref: "#/components/parameters/EventTypes"
        - $ref: "#/components/parameters/EventsLimit"
      responses:
        "200":
          description: A page of the recording's events.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventList"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/webhook-endpoints:
    post:
      operationId: createWebhookEndpoint
      tags:
        - webhooks
      summary: Create a webhook endpoint
      description: |
        Registers an HTTPS URL on your server to receive events as POSTs,
        signed per the Standard Webhooks specification (`webhook-id`,
        `webhook-timestamp`, `webhook-signature`). The response carries the
        signing `secret` once; store it.

        Every event type except `imminence.updated`, `signals.updated` and
        `stimulation.updated` can be delivered; those arrive often and are
        only streamed.
        Deliveries are at least once: deduplicate on the event `id`.

        Next: call `sendTestWebhook` to check your receiver verifies the
        signature.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        description: The URL and the event types to deliver.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookEndpointCreateRequest"
            examples:
              orgasmEvents:
                summary: Orgasm calls and session status
                value:
                  url: https://api.example.com/hooks/orgasm-dev
                  events:
                    - orgasm.onset
                    - orgasm.peak
                    - orgasm.end
                    - subject.identified
                    - session.status
                  description: Production receiver
      responses:
        "201":
          description: The endpoint, with its signing secret.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
              examples:
                created:
                  $ref: "#/components/examples/WebhookEndpointCreated"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    get:
      operationId: listWebhookEndpoints
      tags:
        - webhooks
      summary: List webhook endpoints
      description: Lists your company's webhook endpoints for the key's mode, newest first, without their secrets.
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of endpoints. Secrets are not included.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpointList"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/webhook-endpoints/{webhookEndpointId}:
    parameters:
      - $ref: "#/components/parameters/WebhookEndpointId"
    get:
      operationId: getWebhookEndpoint
      tags:
        - webhooks
      summary: Get a webhook endpoint
      description: Returns one webhook endpoint and the event types it receives, without its secret.
      responses:
        "200":
          description: The endpoint. Its secret is not included.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    patch:
      operationId: updateWebhookEndpoint
      tags:
        - webhooks
      summary: Update a webhook endpoint
      description: |
        Changes an endpoint's URL, the event types it receives, its
        description, or whether it is enabled. What you leave out stays as it
        is. Deliveries already queued go to the URL they were queued for; its
        signing secret does not change (`rollWebhookSecret` replaces it).
      requestBody:
        description: The fields to change.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookEndpointUpdateRequest"
            examples:
              pause:
                summary: Stop deliveries for now
                value:
                  enabled: false
              events:
                summary: Receive edges as well
                value:
                  events:
                    - orgasm.onset
                    - orgasm.peak
                    - orgasm.end
                    - edge.completed
                    - session.status
      responses:
        "200":
          description: The endpoint as it now is. Its secret is not included.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    delete:
      operationId: deleteWebhookEndpoint
      tags:
        - webhooks
      summary: Delete a webhook endpoint
      description: Stops all deliveries to the endpoint, including retries in flight.
      responses:
        "200":
          description: The endpoint was deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deleted"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/webhook-endpoints/{webhookEndpointId}/roll-secret:
    parameters:
      - $ref: "#/components/parameters/WebhookEndpointId"
    post:
      operationId: rollWebhookSecret
      tags:
        - webhooks
      summary: Roll a webhook endpoint's secret
      description: |
        Replaces the endpoint's signing secret and returns the new one, once.
        For the next 24 hours (`previousSecretExpiresAt`) every delivery
        carries two signatures in `webhook-signature`, one made with each
        secret, so your receiver can switch to the new secret at any moment
        in that window; after it, only the new secret signs. Rolling again
        within the window ends the old secret at once.
      responses:
        "200":
          description: The endpoint, with its new signing secret.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookEndpoint"
              examples:
                rolled:
                  $ref: "#/components/examples/WebhookEndpointSecretRolled"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/webhook-endpoints/{webhookEndpointId}/test:
    parameters:
      - $ref: "#/components/parameters/WebhookEndpointId"
    post:
      operationId: sendTestWebhook
      tags:
        - webhooks
      summary: Send a test webhook
      description: |
        Sends one signed sample event of the given type to the endpoint now
        and reports how your server answered. The sample is marked `test`
        mode and belongs to no real session. Use it to check signature
        verification before going live.
      requestBody:
        description: Optionally, the event type of the sample.
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TestWebhookRequest"
      responses:
        "200":
          description: The delivery attempt. `delivered` is true when your server answered with a 2xx status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestWebhookResult"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/usage:
    get:
      operationId: getUsage
      tags:
        - account
      summary: Get usage
      description: Your company's live-session and recording minutes per day for the key's mode, and the orgasms, ruins, edges and session minimums counted, with the credits they drew (always 0 in test mode). Defaults to the last 30 days. A billing key reads live usage.
      security:
        - secretKey: []
        - billingKey: []
      parameters:
        - name: from
          in: query
          description: First day, inclusive (UTC).
          schema:
            type: string
            format: date
        - name: to
          in: query
          description: Last day, inclusive (UTC).
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Usage per day, and totals.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Usage"
              examples:
                threeDays:
                  $ref: "#/components/examples/UsageThreeDays"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/credits:
    get:
      operationId: getCredits
      tags:
        - account
      summary: Get credits
      description: |
        Your company's credit balance: what is available, what is left of the
        20 free credits, and each package with its price per credit, what it
        has left and when it expires. Credits are shared by your company's
        members and keys and are drawn only by live sessions; a test key and
        a billing key read the same balance.

        At zero, `createLiveSession` with a live key is refused with
        `credits_exhausted` (402) while `enforced` is true. To buy credits,
        talk to sales@orgasm.dev; a package's credits post once its invoice is
        paid.
      security:
        - secretKey: []
        - billingKey: []
      responses:
        "200":
          description: The balance.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditBalance"
              examples:
                growth:
                  $ref: "#/components/examples/CreditsGrowth"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/charges:
    get:
      operationId: listCharges
      tags:
        - account
      summary: List charges
      description: |
        Every orgasm, ruin, edge and session minimum your company's live
        sessions were charged for, newest first, with what each cost in US
        dollars and the session's `userReference`, `clientReferenceId`,
        metadata and key, so that you can break your costs down by person,
        by your own session or by any metadata value. `totals` covers every
        charge the filters match, across all pages.

        A charge's paid credits cost their package's price per credit; free
        credits cost nothing; credits used past zero are `pendingCredits`
        until a package posts and covers them, at that package's price.
        Credits that expire unused belong to no charge. In test mode every
        charge is counted with no credits drawn. A billing key reads live
        charges.
      security:
        - secretKey: []
        - billingKey: []
      parameters:
        - name: from
          in: query
          description: First day, inclusive (UTC). Defaults to 30 days ago.
          schema:
            type: string
            format: date
        - name: to
          in: query
          description: Last day, inclusive (UTC). Defaults to today.
          schema:
            type: string
            format: date
        - name: sessionId
          in: query
          description: Only this session's charges.
          schema:
            type: string
            pattern: ^ls_[0-9a-z]{20}$
        - $ref: "#/components/parameters/UserReferenceFilter"
        - $ref: "#/components/parameters/ClientReferenceIdFilter"
        - name: metadata
          in: query
          description: Only charges whose session has these metadata values, as `metadata[plan]=premium`.
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
        - name: limit
          in: query
          description: How many charges to return.
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of charges, and the totals of every charge that matches.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChargeList"
              examples:
                oneOrgasm:
                  $ref: "#/components/examples/ChargeListOne"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/models:
    get:
      operationId: listModels
      tags:
        - account
      summary: List models
      description: "The models behind each signal: what each produces, which inputs it needs, who it applies to, and where it is available. No key needed."
      security: []
      responses:
        "200":
          description: The models.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelList"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/api-keys:
    post:
      operationId: createApiKey
      tags:
        - account
      summary: Create an API key
      description: |
        Creates a key for your company. The secret is returned once; store it.

        A `secret` key (`sk_test_…`, `sk_live_…`) can do everything in this
        API. A `billing` key (`rk_live_…`, live mode only) can only read
        `getCredits`, `getUsage` and `listCharges`, for a finance system.
      x-mcp-exclude: true
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        description: The new key's name and mode.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApiKeyCreateRequest"
      responses:
        "201":
          description: The key, with its secret.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKey"
              examples:
                created:
                  $ref: "#/components/examples/ApiKeyCreated"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
    get:
      operationId: listApiKeys
      tags:
        - account
      summary: List API keys
      description: Lists your company's API keys, newest first, with only their prefix and last four characters, who made each, and when a rolled key stops working.
      x-mcp-exclude: true
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: A page of keys. Secrets are not included.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyList"
              examples:
                oneKey:
                  $ref: "#/components/examples/ApiKeyListOne"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/api-keys/{apiKeyId}/roll:
    parameters:
      - $ref: "#/components/parameters/ApiKeyId"
    post:
      operationId: rollApiKey
      tags:
        - account
      summary: Roll an API key
      description: |
        Makes a replacement for a key, with the same name, mode and type, and
        returns its secret once. The old key stops working when you say: at
        once (the default, for a key that leaked), or in an hour, a day or a
        week, so that your servers can switch to the new key first. Until
        then both work, and the old key shows its `expiresAt`.
      x-mcp-exclude: true
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        description: When the old key stops working.
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApiKeyRollRequest"
            examples:
              aDay:
                summary: Keep the old key for a day
                value:
                  expiresInS: 86400
      responses:
        "201":
          description: The new key, with its secret.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKey"
              examples:
                rolled:
                  $ref: "#/components/examples/ApiKeyRolled"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/UnprocessableContent"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/api-keys/{apiKeyId}:
    parameters:
      - $ref: "#/components/parameters/ApiKeyId"
    delete:
      operationId: deleteApiKey
      tags:
        - account
      summary: Delete an API key
      description: Revokes the key immediately. Requests with it fail from then on.
      x-mcp-exclude: true
      responses:
        "200":
          description: The key was deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Deleted"
              examples:
                deleted:
                  value:
                    id: key_9d2f5g8h1j4k7l0z3x6c
                    object: api_key
                    deleted: true
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/attestation-policy:
    get:
      operationId: getAttestationPolicy
      tags:
        - trust
      summary: Get the attestation policy
      description: |
        What a device must check in an enclave's attestation before it
        publishes media: the token issuer, the confidential-computing hardware,
        the enclave image's source and minimum release, and the sealing scheme.
        The SDK checks it for you. No key needed.
      security: []
      parameters:
        - name: mode
          in: query
          description: The policy for test or live sessions.
          schema:
            type: string
            enum:
              - test
              - live
            default: live
      responses:
        "200":
          description: The policy.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttestationPolicy"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "429":
          $ref: "#/components/responses/TooManyRequests"
  /v1/sandbox/uploads/{uploadToken}:
    parameters:
      - name: uploadToken
        in: path
        required: true
        description: The token in a sandbox `uploads.*.url`.
        schema:
          type: string
          pattern: ^up_[0-9a-z]{24}$
    put:
      operationId: uploadSandboxRecording
      tags:
        - sandbox
      summary: Upload a sandbox recording
      description: |
        The target of `uploads.face.url` and `uploads.body.url` in test mode.
        The sandbox reads and discards the bytes without storing them, then
        starts the recording's scenario. Do not upload real recordings of
        people to the sandbox; any small video file works. In live mode the
        upload URL points at the enclave instead.
      security: []
      x-mcp-exclude: true
      requestBody:
        description: The video file. Its bytes are read and discarded.
        required: true
        content:
          video/mp4:
            schema:
              type: string
              contentMediaType: video/mp4
          video/quicktime:
            schema:
              type: string
              contentMediaType: video/quicktime
          application/octet-stream:
            schema:
              type: string
              contentMediaType: application/octet-stream
      responses:
        "200":
          description: The upload was accepted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadReceipt"
          headers:
            Request-Id: *a1
            RateLimit-Limit: *a2
            RateLimit-Remaining: *a3
            RateLimit-Reset: *a4
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "413":
          $ref: "#/components/responses/ContentTooLarge"
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: sk_test_… or sk_live_…
      description: "A secret key, sent as `Authorization: Bearer sk_test_…`. Keep it on your server. Test keys reach the sandbox; live keys reach live analysis. In the sandbox any key that starts with `sk_test_` works."
    clientToken:
      type: http
      scheme: bearer
      bearerFormat: ct_…
      description: "A live session's client token (`results.clientToken`), sent as `Authorization: Bearer ct_…`. It reads one session's events and reports its stimulation, and nothing else, so it is safe to hand to the end user's device. It stops working five minutes after the session ends, time enough to read the final events."
    viewToken:
      type: http
      scheme: bearer
      bearerFormat: vt_…
      description: "A read-only view token (`createViewToken`), sent as `Authorization: Bearer vt_…`, never in a URL. It reads one live session's events through the stream and the event list, and nothing else: not the session, its metadata or its references, and it cannot report stimulation. For a second screen, such as a display drawn into a stream. It stops working at its `expiresAt`, or five minutes after the session ends."
    clientTokenQuery:
      type: apiKey
      in: query
      name: token
      description: The client token as a `token` query parameter, for the event stream in a browser, where an `EventSource` cannot set headers.
    billingKey:
      type: http
      scheme: bearer
      bearerFormat: rk_live_…
      description: "A read-only billing key, sent as `Authorization: Bearer rk_live_…`. It reads your company's credits, usage and charges and nothing else: it cannot start a session, read events or change a key or a webhook, so it can live in a finance system. An Admin or Billing member of your company makes one in the console, or a secret key with `createApiKey`."
  parameters:
    SessionId:
      name: sessionId
      in: path
      required: true
      description: The live session's `id`.
      schema:
        type: string
        pattern: ^ls_[0-9a-z]{20}$
      example: ls_8f3kq2m7x9w4c1n6t5ra
    RecordingId:
      name: recordingId
      in: path
      required: true
      description: The recording's `id`.
      schema:
        type: string
        pattern: ^rec_[0-9a-z]{20}$
      example: rec_2n5v8c1x4m7q0w3e6r9t
    WebhookEndpointId:
      name: webhookEndpointId
      in: path
      required: true
      description: The webhook endpoint's `id`.
      schema:
        type: string
        pattern: ^we_[0-9a-z]{20}$
      example: we_5h8j1k4l7z0x3c6v9b2n
    ApiKeyId:
      name: apiKeyId
      in: path
      required: true
      description: The API key's `id`.
      schema:
        type: string
        pattern: ^key_[0-9a-z]{20}$
      example: key_9d2f5g8h1j4k7l0z3x6c
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: "A unique value, such as a UUID, that makes retrying this request safe: a retry with the same key and body within 24 hours returns the first response (with `Idempotent-Replayed: true`) instead of acting twice. The same key with a different body is refused with `idempotency_key_reused`."
      schema:
        type: string
        minLength: 1
        maxLength: 255
    Limit:
      name: limit
      in: query
      description: How many items to return.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Cursor:
      name: cursor
      in: query
      description: The `nextCursor` of the previous page.
      schema:
        type: string
    UserReferenceFilter:
      name: userReference
      in: query
      description: Only those created with this `userReference`.
      schema:
        $ref: "#/components/schemas/UserReference"
    ClientReferenceIdFilter:
      name: clientReferenceId
      in: query
      description: Only those created with this `clientReferenceId`.
      schema:
        $ref: "#/components/schemas/ClientReferenceId"
    EventsAfter:
      name: after
      in: query
      description: Return only events after the event with this `id`.
      schema:
        type: string
        pattern: ^evt_[0-9a-z]{20}$
    EventTypes:
      name: types
      in: query
      description: Return only events of these types, comma-separated, for example `orgasm.onset,orgasm.peak,orgasm.end`.
      style: form
      explode: false
      schema:
        type: array
        items:
          $ref: "#/components/schemas/EventType"
    Frames:
      name: frames
      in: query
      description: "Messages besides the events to receive, comma-separated: `face`, the face about five times a second (`face.frame`)."
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
          enum:
            - face
    EventsLimit:
      name: limit
      in: query
      description: How many events to return.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
    Wait:
      name: wait
      in: query
      description: When no events match yet, hold the request open up to this many seconds until one does. `0` answers at once.
      schema:
        type: integer
        minimum: 0
        maximum: 30
        default: 0
  headers:
    RequestId:
      description: Identifies the request; include it when you contact support.
      schema:
        type: string
        pattern: ^req_[0-9a-z]{20}$
    RateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimitReset:
      description: Seconds until the window resets.
      schema:
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    IdempotentReplayed:
      description: "`true` when the response is a replay of an earlier request with the same `Idempotency-Key`."
      schema:
        type: boolean
  responses:
    PaymentRequired:
      description: Your company's credits are used up, so no new live session starts. Sessions already running finish, and test keys are unaffected.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://orgasm.dev/docs/guides/errors#credits_exhausted
            title: No credits left
            status: 402
            code: credits_exhausted
            detail: "studio.example has no credits left. Live sessions start again once a package posts: write to sales@orgasm.dev. Test keys still reach the sandbox."
            requestId: req_3k6m9q2t5w8z1c4f7h0j
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
    BadRequest:
      description: The request was malformed, or a parameter was invalid.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://orgasm.dev/docs/guides/errors#invalid_request
            title: The request is invalid
            status: 400
            code: invalid_request
            detail: limit must be <= 100
            param: limit
            requestId: req_3k6m9q2t5w8z1c4f7h0j
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
    Unauthorized:
      description: The key is missing, malformed or revoked.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://orgasm.dev/docs/guides/errors#invalid_api_key
            title: The API key is not valid
            status: 401
            code: invalid_api_key
            detail: "Send a secret key as `Authorization: Bearer sk_test_…`. In the sandbox any key that starts with sk_test_ works."
            requestId: req_3k6m9q2t5w8z1c4f7h0j
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
    Forbidden:
      description: The key cannot do this, or live mode is not available yet.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://orgasm.dev/docs/guides/errors#live_mode_unavailable
            title: Live analysis is not available yet
            status: 403
            code: live_mode_unavailable
            detail: Live keys are not accepted yet. Use a key that starts with sk_test_ to reach the sandbox.
            requestId: req_3k6m9q2t5w8z1c4f7h0j
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
    NotFound:
      description: No such resource for this key's mode.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://orgasm.dev/docs/guides/errors#not_found
            title: Not found
            status: 404
            code: not_found
            detail: No live session ls_8f3kq2m7x9w4c1n6t5ra in test mode.
            requestId: req_3k6m9q2t5w8z1c4f7h0j
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
    Conflict:
      description: The request conflicts with the resource's state, or an idempotency key was reused.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://orgasm.dev/docs/guides/errors#session_ended
            title: The session has ended
            status: 409
            code: session_ended
            detail: ls_8f3kq2m7x9w4c1n6t5ra ended at 2026-10-16T14:12:00Z.
            requestId: req_3k6m9q2t5w8z1c4f7h0j
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
    UnprocessableContent:
      description: The body did not match the contract, or consent was not attested.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://orgasm.dev/docs/guides/errors#consent_required
            title: Consent is required
            status: 422
            code: consent_required
            detail: consent.subjectIsAdult and consent.subjectConsented must both be true.
            param: consent
            requestId: req_3k6m9q2t5w8z1c4f7h0j
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
    ContentTooLarge:
      description: The upload is larger than `maxBytes`.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
    TooManyRequests:
      description: Too many requests; wait `Retry-After` seconds.
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://orgasm.dev/docs/guides/errors#rate_limited
            title: Too many requests
            status: 429
            code: rate_limited
            detail: Retry after 2 seconds.
            requestId: req_3k6m9q2t5w8z1c4f7h0j
    ServiceUnavailable:
      description: No analysis capacity is available right now; retry after `Retry-After` seconds.
      headers:
        Request-Id: *a1
        RateLimit-Limit: *a2
        RateLimit-Remaining: *a3
        RateLimit-Reset: *a4
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
          example:
            type: https://orgasm.dev/docs/guides/errors#capacity_unavailable
            title: No analysis capacity is available
            status: 503
            code: capacity_unavailable
            detail: Retry in 30 seconds.
            requestId: req_3k6m9q2t5w8z1c4f7h0j
  schemas:
    EventType:
      title: EventType
      description: The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
      type: string
      enum:
        - imminence.updated
        - signals.updated
        - stimulation.updated
        - orgasm.onset
        - orgasm.peak
        - orgasm.end
        - edge.completed
        - subject.identified
        - session.status
        - input.warning
        - recording.completed
        - recording.failed
    Confidence:
      title: Confidence
      description: "How complete the input behind this event was. `high`: the face was tracked throughout the window the signal reads and every input it uses was present. `medium`: an input was missing or partial for part of that window. `low`: the event rests on degraded input, or comes from a detector that ran while the subject was undetermined. `null` on events that are not signals (`session.status`, `input.warning`, `recording.*`). Confidence describes the input, not a calibrated probability that the event is right."
      type:
        - string
        - "null"
      enum:
        - high
        - medium
        - low
        - null
    Detector:
      title: Detector
      description: Which detector made a call. `onset_end` calls the start and the end of an orgasm and applies to women. `peak` calls a single peak and applies to men. `face_end` calls the end of a man's orgasm from the face alone.
      type: string
      enum:
        - onset_end
        - peak
        - face_end
    EventBase:
      title: EventBase
      description: "The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them."
      type: object
      required:
        - id
        - object
        - type
        - mode
        - sequence
        - streamTimeS
        - wallTime
        - confidence
        - data
      properties:
        id:
          description: Unique and stable. A redelivered event carries the same `id`, so deduplicate on it.
          type: string
          pattern: ^evt_[0-9a-z]{20}$
          examples:
            - evt_4q7m2k9x8w1c3n6b5v0z
        object:
          type: string
          const: event
        type:
          $ref: "#/components/schemas/EventType"
        mode:
          description: "`test` for sandbox events, `live` for live analysis."
          type: string
          enum:
            - test
            - live
        sessionId:
          description: The live session the event belongs to. Absent on recording events.
          type: string
          pattern: ^ls_[0-9a-z]{20}$
          examples:
            - ls_8f3kq2m7x9w4c1n6t5ra
        recordingId:
          description: The recording the event belongs to. Absent on live-session events.
          type: string
          pattern: ^rec_[0-9a-z]{20}$
          examples:
            - rec_2n5v8c1x4m7q0w3e6r9t
        sequence:
          description: Position of the event in its session or recording, starting at 1 and increasing by one. Use it to order events and to notice a gap.
          type: integer
          minimum: 1
        streamTimeS:
          description: When the event was produced, in seconds on the media's own clock (time since the first frame of the live stream, or time into the recording). For an orgasm call this is the moment the call was made, which is later than the moment it names (`data.eventAtS`).
          type: number
          minimum: 0
        wallTime:
          description: When the event was produced, as UTC wall-clock time. For recordings it is when the analysis made the call, not a time in the recording.
          type: string
          format: date-time
        confidence:
          $ref: "#/components/schemas/Confidence"
        data:
          description: The event's own fields; see each event type.
          type: object
      oneOf:
        - required:
            - sessionId
        - required:
            - recordingId
    RecentCall:
      title: RecentCall
      description: An orgasm call, as repeated in every `imminence.updated`.
      type: object
      required:
        - id
        - type
        - eventAtS
      properties:
        id:
          description: The `id` of the call's own event.
          type: string
          pattern: ^evt_[0-9a-z]{20}$
        type:
          type: string
          enum:
            - orgasm.onset
            - orgasm.peak
            - orgasm.end
        eventAtS:
          description: The moment the call names, in stream seconds.
          type: number
    ImminenceData:
      title: ImminenceData
      type: object
      required:
        - p30
        - p60
        - logit30
        - logit60
        - featuresPresent
        - faceVisible
        - baselineReady
        - stimulationAware
        - recentCalls
      properties:
        p30:
          description: Probability that the next orgasm begins within 30 seconds, given that it has not begun yet (the onset for a woman, the peak for a man). A probability over a horizon, not a countdown. `null` while the face is not visible or its baseline is not ready.
          type:
            - number
            - "null"
          minimum: 0
          maximum: 1
        p60:
          description: The same probability over 60 seconds. Never lower than `p30`.
          type:
            - number
            - "null"
          minimum: 0
          maximum: 1
        logit30:
          description: "`p30` as a logit, ln(p / (1 - p)). Add your own prior on this scale to combine it with what your product knows."
          type:
            - number
            - "null"
        logit60:
          description: "`p60` as a logit."
          type:
            - number
            - "null"
        featuresPresent:
          description: Share of the model's inputs that were available this second, from 0 to 1. Lower values mean the face was turned away, occluded or too far for part of the second.
          type: number
          minimum: 0
          maximum: 1
        faceVisible:
          description: Whether a face was tracked in the last second.
          type: boolean
        baselineReady:
          description: Whether the person's own resting baseline is in. It takes about a minute of visible face after the stream starts; imminence is `null` before.
          type: boolean
        stimulationAware:
          description: Whether you have reported stimulation for this session (see `reportStimulation`). When `true`, imminence also accounts for how long the person has been stimulated; when `false`, it reads the face alone.
          type: boolean
        recentCalls:
          description: The last orgasm calls of the session, oldest first, at most eight, repeated in every update so that a call whose own event you missed is still seen within a second.
          type: array
          maxItems: 8
          items:
            $ref: "#/components/schemas/RecentCall"
    OrgasmOnsetData:
      title: OrgasmOnsetData
      type: object
      required:
        - orgasmIndex
        - eventAtS
        - calledAtS
        - lagS
        - detector
        - score
        - threshold
      properties:
        orgasmIndex:
          description: Which orgasm of the session this is, from 1. The onset and the end of the same orgasm share it.
          type: integer
          minimum: 1
        eventAtS:
          description: The moment the orgasm began, in stream seconds.
          type: number
        calledAtS:
          description: The moment the detector made the call, in stream seconds.
          type: number
        lagS:
          description: "`calledAtS - eventAtS`: how late the call is."
          type: number
          minimum: 0
        detector:
          type: string
          const: onset_end
        score:
          description: The detector's score for the call, on the scale of `threshold`.
          type: number
          minimum: 0
          maximum: 1
        threshold:
          description: The level the detector calls at. A score at or above it made the call.
          type: number
          minimum: 0
          maximum: 1
    OrgasmPeakData:
      title: OrgasmPeakData
      type: object
      required:
        - orgasmIndex
        - eventAtS
        - calledAtS
        - lagS
        - detector
        - score
        - threshold
      properties:
        orgasmIndex:
          description: Which orgasm of the session this is, from 1. The peak and the face-based end of the same orgasm share it.
          type: integer
          minimum: 1
        eventAtS:
          description: The moment of the peak, in stream seconds.
          type: number
        calledAtS:
          description: The moment the detector made the call, in stream seconds.
          type: number
        lagS:
          description: "`calledAtS - eventAtS`."
          type: number
          minimum: 0
        detector:
          type: string
          const: peak
        score:
          type: number
          minimum: 0
          maximum: 1
        threshold:
          type: number
          minimum: 0
          maximum: 1
    OrgasmEndData:
      title: OrgasmEndData
      type: object
      required:
        - orgasmIndex
        - eventAtS
        - startedAtS
        - durationS
        - calledAtS
        - lagS
        - detector
        - score
        - threshold
        - ruined
      properties:
        orgasmIndex:
          description: Which orgasm of the session ended.
          type: integer
          minimum: 1
        eventAtS:
          description: The moment the orgasm ended, in stream seconds.
          type: number
        startedAtS:
          description: "When the same orgasm began: its onset (`onset_end`) or its peak (`face_end`)."
          type: number
        durationS:
          description: "`eventAtS - startedAtS`."
          type: number
          minimum: 0
        calledAtS:
          description: The moment the detector made the call, in stream seconds.
          type: number
        lagS:
          description: "`calledAtS - eventAtS`."
          type: number
          minimum: 0
        detector:
          type: string
          enum:
            - onset_end
            - face_end
        score:
          description: The detector's score, or `null` for `face_end`, which has none.
          type:
            - number
            - "null"
          minimum: 0
          maximum: 1
        threshold:
          description: The detector's calling level, or `null` for `face_end`.
          type:
            - number
            - "null"
          minimum: 0
          maximum: 1
        ruined:
          description: "Whether the orgasm was ruined: the last stimulation report before it began was `off`, sent within the 30 seconds before while `p30` was at 0.75 or above (the ruin preset's stop). Charged as a ruin, at the price of an orgasm. Always `false` for a recording, which takes no stimulation reports."
          type: boolean
    EdgeCompletedData:
      title: EdgeCompletedData
      type: object
      required:
        - edgeIndex
        - startedAtS
        - eventAtS
        - durationS
        - peakP30
      properties:
        edgeIndex:
          description: Which edge of the session this is, from 1.
          type: integer
          minimum: 1
        startedAtS:
          description: When `p30` reached 0.6, the edge preset's back-off level, in stream seconds.
          type: number
        eventAtS:
          description: When `p30` fell back below 0.3, the preset's resume level, which made the approach an edge, in stream seconds.
          type: number
        durationS:
          description: "`eventAtS - startedAtS`."
          type: number
          minimum: 0
        peakP30:
          description: The highest `p30` of the approach.
          type: number
          minimum: 0.6
          maximum: 1
    SubjectIdentifiedData:
      title: SubjectIdentifiedData
      type: object
      required:
        - sex
        - pWoman
        - secondsObserved
        - decidedAtS
        - hint
        - detectors
      properties:
        sex:
          description: "Whether the face reads as a woman's or a man's, which decides the detectors that apply. `undetermined` is common: the read is made once, from the first 30 seconds of visible face, and only decides when it is clear. It is an estimate for choosing detectors, not a statement about the person's sex or gender identity."
          type: string
          enum:
            - woman
            - man
            - undetermined
        pWoman:
          description: The read's probability that the face is a woman's, or `null` when the face could not be read.
          type:
            - number
            - "null"
          minimum: 0
          maximum: 1
        secondsObserved:
          description: Seconds of visible face the read was made from (at most 30).
          type: integer
          minimum: 0
          maximum: 30
        decidedAtS:
          description: When the read was made, in stream seconds.
          type: number
        hint:
          description: The `subjectHint` you gave when you created the session, or `null`.
          type:
            - string
            - "null"
          enum:
            - woman
            - man
            - null
        detectors:
          description: "The detectors that apply from now on. A hint decides them when given; otherwise the read does; while undetermined, all of them run and their calls arrive with `confidence: low`."
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: "#/components/schemas/Detector"
    InputsPresence:
      title: InputsPresence
      description: Which inputs are arriving right now.
      type: object
      required:
        - face
        - audio
        - body
      properties:
        face:
          type: object
          required:
            - present
            - baselineReady
          properties:
            present:
              description: A face was tracked in the last second.
              type: boolean
            baselineReady:
              description: The person's resting baseline is in.
              type: boolean
        audio:
          type: object
          required:
            - declared
            - present
          properties:
            declared:
              description: You said the stream would carry the microphone.
              type: boolean
            present:
              description: Audio is arriving.
              type: boolean
        body:
          type: object
          required:
            - declared
            - present
          properties:
            declared:
              description: You said a body view would be published.
              type: boolean
            present:
              description: The body view is arriving.
              type: boolean
    SessionStatusData:
      title: SessionStatusData
      type: object
      required:
        - status
        - previousStatus
        - degraded
        - inputs
        - endedReason
      properties:
        status:
          description: "`starting`: analysis capacity is being prepared (a few minutes when none is warm). `ready`: the device can publish. `calibrating`: media is arriving and the person's baseline is being taken. `analyzing`: every signal the inputs allow is running. `ended`: no more events follow."
          type: string
          enum:
            - starting
            - ready
            - calibrating
            - analyzing
            - ended
        previousStatus:
          type:
            - string
            - "null"
          enum:
            - starting
            - ready
            - calibrating
            - analyzing
            - ended
            - null
        degraded:
          description: An input the session declared is missing, or the face is not visible. The open `input.warning` events say which.
          type: boolean
        inputs:
          $ref: "#/components/schemas/InputsPresence"
        endedReason:
          description: "Why the session ended, once `status` is `ended`. `client_ended`: you ended it. `media_ended`: the device stopped publishing. `media_timeout`: no frames arrived for too long. `max_duration`: `maxDurationS` elapsed. `interrupted`: the analysis capacity was lost; create a new session. `policy`: the session broke the acceptable use policy. `error`: an internal failure."
          type:
            - string
            - "null"
          enum:
            - client_ended
            - media_ended
            - media_timeout
            - max_duration
            - interrupted
            - policy
            - error
            - null
    InputWarningData:
      title: InputWarningData
      type: object
      required:
        - code
        - state
        - message
        - sinceS
      properties:
        code:
          description: "`face_not_visible`: no face is tracked. `multiple_faces`: more than one face is in view and the analysis cannot tell which is the subject. `audio_absent`: the stream carries no microphone, so onset, peak and end are unavailable. `baseline_pending`: imminence starts once the baseline is in. `body_stream_absent`: a declared body view is not arriving. `low_confidence`: input quality is too low for confident calls."
          type: string
          enum:
            - face_not_visible
            - multiple_faces
            - audio_absent
            - baseline_pending
            - body_stream_absent
            - low_confidence
        state:
          description: "`raised` when the condition starts, `cleared` when it ends."
          type: string
          enum:
            - raised
            - cleared
        message:
          description: A sentence you can show the person, in English.
          type: string
        sinceS:
          description: When the condition started, in stream seconds.
          type: number
    FaceRegions:
      title: FaceRegions
      description: "How far each region of the face has moved from the person's own baseline, from 0 (as at rest) to 1 (a full movement): the largest of the region's expression channels, left and right together."
      type: object
      required:
        - brows
        - eyes
        - cheeks
        - nose
        - lips
        - corners
        - jaw
      properties:
        brows:
          type: number
          minimum: 0
          maximum: 1
        eyes:
          type: number
          minimum: 0
          maximum: 1
        cheeks:
          type: number
          minimum: 0
          maximum: 1
        nose:
          type: number
          minimum: 0
          maximum: 1
        lips:
          type: number
          minimum: 0
          maximum: 1
        corners:
          type: number
          minimum: 0
          maximum: 1
        jaw:
          type: number
          minimum: 0
          maximum: 1
    FaceExpression:
      title: FaceExpression
      description: The face's expression as 24 channels, each from 0 (as at the person's own rest) to 1 (a full movement). Names ending in `L` and `R` are the person's own left and right. Channels may be added; draw the ones you know.
      type: object
      required:
        - eyeBlinkL
        - eyeBlinkR
        - eyeWideL
        - eyeWideR
        - browDownL
        - browDownR
        - browInnerUp
        - browOuterUpL
        - browOuterUpR
        - jawOpen
        - lipsPart
        - mouthSmileL
        - mouthSmileR
        - mouthStretch
        - mouthPucker
        - noseSneer
        - noseFlare
        - cheekSquintL
        - cheekSquintR
        - chinRaise
        - lidTighten
        - browTogether
        - noseWrinkle
        - lidRaise
      properties:
        eyeBlinkL:
          type: number
          minimum: 0
          maximum: 1
        eyeBlinkR:
          type: number
          minimum: 0
          maximum: 1
        eyeWideL:
          type: number
          minimum: 0
          maximum: 1
        eyeWideR:
          type: number
          minimum: 0
          maximum: 1
        browDownL:
          type: number
          minimum: 0
          maximum: 1
        browDownR:
          type: number
          minimum: 0
          maximum: 1
        browInnerUp:
          type: number
          minimum: 0
          maximum: 1
        browOuterUpL:
          type: number
          minimum: 0
          maximum: 1
        browOuterUpR:
          type: number
          minimum: 0
          maximum: 1
        jawOpen:
          type: number
          minimum: 0
          maximum: 1
        lipsPart:
          type: number
          minimum: 0
          maximum: 1
        mouthSmileL:
          type: number
          minimum: 0
          maximum: 1
        mouthSmileR:
          type: number
          minimum: 0
          maximum: 1
        mouthStretch:
          type: number
          minimum: 0
          maximum: 1
        mouthPucker:
          type: number
          minimum: 0
          maximum: 1
        noseSneer:
          type: number
          minimum: 0
          maximum: 1
        noseFlare:
          type: number
          minimum: 0
          maximum: 1
        cheekSquintL:
          type: number
          minimum: 0
          maximum: 1
        cheekSquintR:
          type: number
          minimum: 0
          maximum: 1
        chinRaise:
          type: number
          minimum: 0
          maximum: 1
        lidTighten:
          type: number
          minimum: 0
          maximum: 1
        browTogether:
          type: number
          minimum: 0
          maximum: 1
        noseWrinkle:
          type: number
          minimum: 0
          maximum: 1
        lidRaise:
          type: number
          minimum: 0
          maximum: 1
      additionalProperties:
        type: number
        minimum: 0
        maximum: 1
    HeadPose:
      title: HeadPose
      description: How far the head has turned from the person's own resting pose, in degrees, as someone facing them sees it.
      type: object
      required:
        - yawDeg
        - pitchDeg
        - rollDeg
      properties:
        yawDeg:
          description: Positive turns the face toward the viewer's right, the person's own left.
          type: number
          minimum: -90
          maximum: 90
        pitchDeg:
          description: Positive raises the chin; negative lowers it.
          type: number
          minimum: -90
          maximum: 90
        rollDeg:
          description: Positive tips the top of the head toward the viewer's right.
          type: number
          minimum: -90
          maximum: 90
    CameraHeadPose:
      title: CameraHeadPose
      description: "The head's own angles against a face square to the camera, in degrees, as someone facing the person sees them, with HeadPose's senses. Not its turn from the resting pose: a head held tilted, or lying on its side, reads as it is."
      type: object
      required:
        - yawDeg
        - pitchDeg
        - rollDeg
      properties:
        yawDeg:
          description: Positive turns the face toward the viewer's right, the person's own left.
          type: number
          minimum: -180
          maximum: 180
        pitchDeg:
          description: Positive raises the chin; negative lowers it.
          type: number
          minimum: -90
          maximum: 90
        rollDeg:
          description: Positive tips the top of the head toward the viewer's right; a head lying on its side reads about 90 either way.
          type: number
          minimum: -180
          maximum: 180
    FaceChannels:
      title: FaceChannels
      description: "How the face is moving: its expression and the head's turn, measured against the person's own resting baseline. Drawn on a generic face, they show what the face is doing and nothing of what it looks like."
      type: object
      required:
        - expression
        - head
      properties:
        expression:
          $ref: "#/components/schemas/FaceExpression"
        head:
          $ref: "#/components/schemas/HeadPose"
    SignalsData:
      title: SignalsData
      description: The body's other signals, as a heads-up display shows them. Each is `null` while its input is absent or still calibrating; none is a call, and none is charged.
      type: object
      required:
        - vocalizationsPerMin
        - loudnessAboveBaselineDb
        - contractionsPerMin
        - movement
        - faceRegions
        - face
      properties:
        vocalizationsPerMin:
          description: Vocalizations a minute, from the microphone; null without it.
          type:
            - number
            - "null"
          minimum: 0
        loudnessAboveBaselineDb:
          description: How much louder the voice is than at the baseline, in decibels; null without the microphone or before its baseline.
          type:
            - number
            - "null"
        contractionsPerMin:
          description: Pelvic floor contractions a minute, from the body view; null without it.
          type:
            - number
            - "null"
          minimum: 0
        movement:
          description: How still the body is, from the body view; null without it.
          type:
            - string
            - "null"
          enum:
            - settled
            - shifting
            - unsettled
            - null
        faceRegions:
          description: Null while the face is out of view or before the baseline is in.
          oneOf:
            - $ref: "#/components/schemas/FaceRegions"
            - type: "null"
        face:
          description: The face's expression channels and the head's turn, once a second, for a display that draws a face; `face.frame` carries the same about five times a second to readers that ask. Null while the face is out of view or before the baseline is in. A view token reads it only when made with `includeFace`.
          oneOf:
            - $ref: "#/components/schemas/FaceChannels"
            - type: "null"
    StimulationChannel:
      title: StimulationChannel
      description: One output of a device with more than one, such as an e-stim unit's channels.
      type: object
      required:
        - id
        - level
        - levelMax
      properties:
        id:
          description: The output's name, such as `a` or `b`.
          type: string
          pattern: ^[a-z0-9]{1,8}$
        level:
          description: The output's level now, on the device's own scale.
          type: number
          minimum: 0
        levelMax:
          description: The highest level the output will go to now, on the same scale; null when your product did not say.
          type:
            - number
            - "null"
          exclusiveMinimum: 0
    StimulationDevice:
      title: StimulationDevice
      description: The device your product drives, as a display names it.
      type: object
      required:
        - label
        - connected
      properties:
        label:
          description: What a display calls the device, such as `Wand` or `Unit`; null when your product did not say. Never the person's name.
          type:
            - string
            - "null"
          maxLength: 40
        connected:
          description: False while your product cannot reach the device; a display shows it as disconnected.
          type: boolean
    StimulationData:
      title: StimulationData
      description: "The stimulation your product last reported, merged across its reports: a report updates the fields it carries and keeps the rest. Fields your product never reported are null."
      type: object
      required:
        - state
        - intensity
        - level
        - levelMax
        - channels
        - mode
        - modeLabel
        - device
        - drive
        - changedAtS
      properties:
        state:
          description: Whether stimulation is on or off.
          type: string
          enum:
            - on
            - off
        intensity:
          description: The intensity from 0 to 1 on your product's own scale.
          type:
            - number
            - "null"
          minimum: 0
          maximum: 1
        level:
          description: The device's level on its own scale, such as 0 to 100.
          type:
            - number
            - "null"
          minimum: 0
        levelMax:
          description: The highest level the device will go to now, on the same scale.
          type:
            - number
            - "null"
          exclusiveMinimum: 0
        channels:
          description: Each output's level, for a device with more than one.
          type:
            - array
            - "null"
          maxItems: 4
          items:
            $ref: "#/components/schemas/StimulationChannel"
        mode:
          description: The device's mode or pattern, as your product names it.
          type:
            - string
            - "null"
          maxLength: 40
        modeLabel:
          description: The mode's name to show; without it a display shows `mode` in words.
          type:
            - string
            - "null"
          maxLength: 40
        device:
          oneOf:
            - $ref: "#/components/schemas/StimulationDevice"
            - type: "null"
        drive:
          description: "Who sets the level: `auto` (your product, following the person's signals), `manual` (the person's own hand), `hold` (held where it is) or `paused`."
          type:
            - string
            - "null"
          enum:
            - auto
            - manual
            - hold
            - paused
            - null
        changedAtS:
          description: When the change happened, in stream seconds. The event's own `streamTimeS` is when orgasm.dev received the report, which can be later.
          type: number
          minimum: 0
    StimulationReportChannel:
      title: StimulationReportChannel
      description: One output's level.
      type: object
      required:
        - id
        - level
      properties:
        id:
          description: The output's name, such as `a` or `b`.
          type: string
          pattern: ^[a-z0-9]{1,8}$
        level:
          type: number
          minimum: 0
        levelMax:
          type:
            - number
            - "null"
          exclusiveMinimum: 0
    StimulationReportDevice:
      title: StimulationReportDevice
      description: The device your product drives.
      type: object
      properties:
        label:
          description: What a display calls it, such as `Wand` or `Unit`. Never the person's name.
          type:
            - string
            - "null"
          maxLength: 40
        connected:
          description: False while your product cannot reach the device. Omitted, it keeps its last value, true at first.
          type: boolean
    FaceFrame:
      title: FaceFrame
      description: "The face, and the head as the camera sees it, about five times a second, for a display that draws them, sent only to readers that ask with `frames=face`, between the once-a-second `signals.updated`. Not an event: it has no `id` or `sequence`, is never stored or replayed, and a reader that falls behind gets the newest frame."
      type: object
      required:
        - type
        - sessionId
        - streamTimeS
        - face
      properties:
        type:
          type: string
          const: face.frame
        sessionId:
          type: string
          pattern: ^ls_[0-9a-z]{20}$
        streamTimeS:
          description: When the frame was measured, in stream seconds.
          type: number
          minimum: 0
        face:
          description: Null while the face is out of view or before the baseline is in.
          oneOf:
            - $ref: "#/components/schemas/FaceChannels"
            - type: "null"
        cameraHead:
          description: The head as the camera sees it, for a display that draws the head as it is rather than by its turn from the resting pose. It needs no baseline, so it is there whenever the face is in view, while `face` is still null too. Null while the face is out of view or when the analysis does not measure it; treat a frame without it the same way.
          oneOf:
            - $ref: "#/components/schemas/CameraHeadPose"
            - type: "null"
    RecordingCompletedData:
      title: RecordingCompletedData
      type: object
      required:
        - durationS
        - orgasmCount
        - subject
      properties:
        durationS:
          description: Length of the recording, in seconds.
          type: number
        orgasmCount:
          description: How many orgasms the analysis called in the recording.
          type: integer
          minimum: 0
        subject:
          type: object
          required:
            - sex
            - pWoman
          properties:
            sex:
              type: string
              enum:
                - woman
                - man
                - undetermined
            pWoman:
              type:
                - number
                - "null"
              minimum: 0
              maximum: 1
    RecordingFailedData:
      title: RecordingFailedData
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: "`unreadable_media`: the file could not be decoded (H.264 or H.265 video is required). `no_face`: no face was visible long enough to analyse. `too_short`: under two minutes. `too_long`: over four hours. `fetch_failed`: `source.url` could not be fetched. `upload_expired`: the upload URL expired before a file arrived. `internal`: an internal failure; submit it again."
          type: string
          enum:
            - unreadable_media
            - no_face
            - too_short
            - too_long
            - fetch_failed
            - upload_expired
            - internal
        message:
          type: string
    ImminenceUpdatedEvent:
      title: imminence.updated
      description: "About once a second while the face is analysed: the probability that the next orgasm begins within 30 and 60 seconds. Streamed only; never sent to webhooks."
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: imminence.updated
            data:
              $ref: "#/components/schemas/ImminenceData"
    SignalsUpdatedEvent:
      title: signals.updated
      description: "Once a second with each `imminence.updated` of a live session: the vocalization rate and loudness from the microphone, the contraction rate and movement from the body view, and how far each region of the face has moved from the baseline. For a heads-up display; not a call, and never charged. Streamed only; never sent to webhooks."
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: signals.updated
            data:
              $ref: "#/components/schemas/SignalsData"
    StimulationUpdatedEvent:
      title: stimulation.updated
      description: "Each time your product reports stimulation, through `reportStimulation` or a `stimulation` message on the socket: the device's state, level, channels and mode as reported, for a display beside the person's signals. At most four a second; reports in between are merged into the next. Streamed only; never sent to webhooks."
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: stimulation.updated
            data:
              $ref: "#/components/schemas/StimulationData"
    OrgasmOnsetEvent:
      title: orgasm.onset
      description: An orgasm began. Applies to women (the `onset_end` detector). Requires the microphone. The call arrives a few seconds after the moment it names.
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: orgasm.onset
            data:
              $ref: "#/components/schemas/OrgasmOnsetData"
    OrgasmPeakEvent:
      title: orgasm.peak
      description: The peak of an orgasm. Applies to men (the `peak` detector). Requires the microphone. The call arrives a few seconds after the moment it names.
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: orgasm.peak
            data:
              $ref: "#/components/schemas/OrgasmPeakData"
    OrgasmEndEvent:
      title: orgasm.end
      description: An orgasm ended. For women it closes the orgasm an `orgasm.onset` opened (`onset_end`, requires the microphone); for men it follows an `orgasm.peak` and is read from the face (`face_end`).
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: orgasm.end
            data:
              $ref: "#/components/schemas/OrgasmEndData"
    EdgeCompletedEvent:
      title: edge.completed
      description: "An edge: imminence (`p30`) reached 0.6 and fell back below 0.3 with no orgasm called in between. orgasm.dev counts it on its side, as the edge preset's back-off and resume levels, and charges half a credit for it in live mode. Sent with the reading that completed it; its `confidence` is the lowest of the approach's readings. Without the microphone no orgasm can be called, so every approach that recedes is an edge."
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: edge.completed
            data:
              $ref: "#/components/schemas/EdgeCompletedData"
    SubjectIdentifiedEvent:
      title: subject.identified
      description: "Once per session or recording, after about 30 seconds of visible face: whether the face reads as a woman's or a man's, and which detectors apply from then on."
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: subject.identified
            data:
              $ref: "#/components/schemas/SubjectIdentifiedData"
    SessionStatusEvent:
      title: session.status
      description: The live session changed status, or its inputs changed.
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: session.status
            data:
              $ref: "#/components/schemas/SessionStatusData"
    InputWarningEvent:
      title: input.warning
      description: An input problem started (`raised`) or stopped (`cleared`). Show `message` to the person when it helps them fix it.
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: input.warning
            data:
              $ref: "#/components/schemas/InputWarningData"
    RecordingCompletedEvent:
      title: recording.completed
      description: A recording finished processing. Fetch its events with `listRecordingEvents`.
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: recording.completed
            data:
              $ref: "#/components/schemas/RecordingCompletedData"
    RecordingFailedEvent:
      title: recording.failed
      description: A recording could not be processed.
      allOf:
        - $ref: "#/components/schemas/EventBase"
        - type: object
          required:
            - type
            - data
          properties:
            type:
              const: recording.failed
            data:
              $ref: "#/components/schemas/RecordingFailedData"
    CreditsLowData:
      title: CreditsLowData
      type: object
      required:
        - domain
        - balance
        - threshold
        - freeRemaining
        - packageId
      properties:
        domain:
          description: The company domain the credits belong to.
          type: string
          examples:
            - studio.example
        balance:
          description: Credits available now, in halves.
          type: number
        threshold:
          description: "The level that sent it: 20% of the credits the latest package posted (4 of the free 20)."
          type: number
        freeRemaining:
          description: How many of the free credits are left.
          type: number
          minimum: 0
        packageId:
          description: The package the threshold is measured against.
          type: string
          pattern: ^(free|pkg_[0-9a-z]{20})$
    CreditsLowEvent:
      title: credits.low
      description: Your company's credit balance fell to 20% or less of its latest package (4 of the free 20). Sent once per package, by webhook only, to the company's live endpoints subscribed to it. It belongs to no session, so it has no `sessionId`, `sequence` or stream time.
      type: object
      required:
        - id
        - object
        - type
        - mode
        - wallTime
        - data
      properties:
        id:
          description: Unique and stable; deduplicate on it.
          type: string
          pattern: ^evt_[0-9a-z]{20}$
        object:
          type: string
          const: event
        type:
          type: string
          const: credits.low
        mode:
          description: Credits are live mode's.
          type: string
          const: live
        wallTime:
          description: When the balance crossed the threshold, as UTC wall-clock time.
          type: string
          format: date-time
        data:
          $ref: "#/components/schemas/CreditsLowData"
    Event:
      title: Event
      description: Any event. Switch on `type`.
      oneOf:
        - $ref: "#/components/schemas/ImminenceUpdatedEvent"
        - $ref: "#/components/schemas/SignalsUpdatedEvent"
        - $ref: "#/components/schemas/StimulationUpdatedEvent"
        - $ref: "#/components/schemas/OrgasmOnsetEvent"
        - $ref: "#/components/schemas/OrgasmPeakEvent"
        - $ref: "#/components/schemas/OrgasmEndEvent"
        - $ref: "#/components/schemas/EdgeCompletedEvent"
        - $ref: "#/components/schemas/SubjectIdentifiedEvent"
        - $ref: "#/components/schemas/SessionStatusEvent"
        - $ref: "#/components/schemas/InputWarningEvent"
        - $ref: "#/components/schemas/RecordingCompletedEvent"
        - $ref: "#/components/schemas/RecordingFailedEvent"
    Problem:
      title: Problem
      description: An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.
      type: object
      required:
        - type
        - title
        - status
        - code
      properties:
        type:
          description: A link to the docs for this error.
          type: string
          format: uri
        title:
          description: A short summary of the error.
          type: string
        status:
          description: The HTTP status code.
          type: integer
        detail:
          description: What went wrong in this request, and what to do.
          type: string
        instance:
          description: The request path.
          type: string
        code:
          $ref: "#/components/schemas/ErrorCode"
        param:
          description: The request field at fault, as a dotted path, when there is one.
          type:
            - string
            - "null"
        requestId:
          type: string
        errors:
          description: Each contract violation, when the body or a parameter did not match the contract.
          type: array
          items:
            type: object
            required:
              - location
              - path
              - message
            properties:
              location:
                type: string
                enum:
                  - path
                  - query
                  - header
                  - cookie
                  - body
              path:
                description: JSON pointer to the value at fault.
                type: string
              message:
                type: string
    ErrorCode:
      title: ErrorCode
      description: A stable, machine-readable error code.
      type: string
      enum:
        - invalid_request
        - consent_required
        - capability_required
        - sandbox_only
        - authentication_required
        - invalid_api_key
        - live_mode_unavailable
        - credits_exhausted
        - permission_denied
        - not_found
        - idempotency_key_reused
        - session_ended
        - sandbox_no_media
        - upload_already_received
        - payload_too_large
        - rate_limited
        - capacity_unavailable
        - internal_error
    Consent:
      title: Consent
      description: "Your attestation that the person on camera is an adult and agreed to this analysis. Set it only when your product has actually done both: it is a statement you are accountable for under the acceptable use policy."
      type: object
      required:
        - subjectIsAdult
        - subjectConsented
        - ageVerification
      properties:
        subjectIsAdult:
          description: The person on camera is 18 or older, or older where their local law requires, and you verified it.
          type: boolean
          const: true
        subjectConsented:
          description: The person on camera was told what is measured and who receives it, agreed to it, and can stop it at any time.
          type: boolean
          const: true
        ageVerification:
          description: How you verified the person's age.
          type: string
          enum:
            - document
            - facial_age_estimation
            - payment_card
            - third_party_service
            - other
        consentedAt:
          description: When the person agreed.
          type: string
          format: date-time
        consentRecordId:
          description: Your reference to the stored consent record, for audits.
          type: string
          maxLength: 255
    DeclaredInputs:
      title: DeclaredInputs
      description: What the device will publish besides the face, which is always required. Declaring an input you do not send raises an `input.warning`.
      type: object
      properties:
        audio:
          description: "The microphone is published with the camera. Recommended: onset, peak and end need it."
          type: boolean
          default: true
        body:
          description: A second camera that sees the person's body is published as well (`ingest.bodyUrl`). Optional; it adds corroboration to onset, peak and end calls.
          type: boolean
          default: false
    ScenarioName:
      title: ScenarioName
      description: "A deterministic sandbox scenario. `woman-onset-end`: a woman's orgasm, onset then end. `man-peak`: a man's peak, then the end read from his face. `undetermined`: the subject read stays undetermined, so every detector runs. `face-only`: no microphone, so imminence and the subject read only. `face-lost`: the face leaves the frame for 20 seconds, then returns. `edge`: imminence rises and falls three times without an orgasm. `ruin`: imminence crosses the point of no return and a peak follows. `finish`: a build-up, an onset and an end."
      type: string
      enum:
        - woman-onset-end
        - man-peak
        - undetermined
        - face-only
        - face-lost
        - edge
        - ruin
        - finish
    SandboxOptions:
      title: SandboxOptions
      description: Test mode only. Refused with `sandbox_only` when sent with a live key.
      type: object
      properties:
        scenario:
          $ref: "#/components/schemas/ScenarioName"
        speed:
          description: "How many times faster than real time the scenario plays: 10 by default for live sessions, 60 for recordings. Stream times in events stay on the scenario's own clock."
          type: number
          minimum: 1
          maximum: 60
    Metadata:
      title: Metadata
      description: "Up to 20 string values of your own, returned on the object and on its charges, where they break your costs down (a plan, a product, a region, a campaign). Do not put personal data in it: a person's pseudonymous id goes in `userReference`."
      type: object
      maxProperties: 20
      additionalProperties:
        type: string
        maxLength: 500
    UserReference:
      title: UserReference
      description: "A pseudonymous id of your choosing for the person on camera, so that your company's costs can be broken down by person. Make it one orgasm.dev cannot trace to them, for example the hex HMAC-SHA256 of your user id under a key only you hold: never their email address, phone number, name or account name. At least one letter, and only letters, digits, `.`, `_`, `:` and `-`. It is erased when the session is purged, and 13 months after the session ends."
      type: string
      minLength: 1
      maxLength: 128
      pattern: ^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$
    ClientReferenceId:
      title: ClientReferenceId
      description: Your own id for the session, for example your session, order or round id, to join orgasm.dev's charges to your records. At least one letter, and only letters, digits, `.`, `_`, `:` and `-`. Erased with the session's `userReference`.
      type: string
      minLength: 1
      maxLength: 128
      pattern: ^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$
    LiveSessionStatus:
      title: LiveSessionStatus
      description: "Where a live session is in its life: `starting`, `ready`, `calibrating`, `analyzing`, `ended`."
      type: string
      enum:
        - starting
        - ready
        - calibrating
        - analyzing
        - ended
    LiveSessionCreateRequest:
      title: LiveSessionCreateRequest
      description: What to create a live session with. Only `consent` is required.
      type: object
      required:
        - consent
      properties:
        consent:
          $ref: "#/components/schemas/Consent"
        inputs:
          $ref: "#/components/schemas/DeclaredInputs"
        subjectHint:
          description: Whether the person is a woman or a man, if they told you. It decides the detectors from the start; the face is still read and reported in `subject.identified`. Leave it out and the face decides.
          type: string
          enum:
            - woman
            - man
        capabilityHash:
          description: Hex SHA-256 of a 32-byte random capability the end user's device generated and kept. Only a publisher holding the capability can publish. Required with live keys.
          type: string
          pattern: ^[0-9a-f]{64}$
        maxDurationS:
          description: The session ends after this many seconds (`max_duration`).
          type: integer
          minimum: 60
          maximum: 14400
          default: 3600
        retentionDays:
          description: "How many days the session's events stay readable after it ends. `0` keeps nothing: events are only delivered as they happen."
          type: integer
          minimum: 0
          maximum: 90
          default: 30
        webhookEndpointId:
          description: Deliver this session's events to this endpoint only. Leave it out to deliver to every enabled endpoint subscribed to each event type.
          type: string
          pattern: ^we_[0-9a-z]{20}$
        userReference:
          $ref: "#/components/schemas/UserReference"
        clientReferenceId:
          $ref: "#/components/schemas/ClientReferenceId"
        metadata:
          $ref: "#/components/schemas/Metadata"
        sandbox:
          $ref: "#/components/schemas/SandboxOptions"
    VideoRequirements:
      title: VideoRequirements
      description: What the video track must be.
      type: object
      required:
        - codecs
        - maxLongEdgePx
        - recommendedFps
      properties:
        codecs:
          type: array
          items:
            type: string
            enum:
              - H264
              - H265
        maxLongEdgePx:
          description: Larger frames are scaled down to this long edge.
          type: integer
        recommendedFps:
          type: integer
    Ingest:
      title: Ingest
      description: Where the end user's device publishes. Only the device that holds the capability can publish, and it should verify `attestationUrl` against the attestation policy first.
      type: object
      required:
        - protocol
        - url
        - bodyUrl
        - attestationUrl
        - seal
        - iceServersUrl
        - expiresAt
        - video
        - audio
      properties:
        protocol:
          type: string
          const: whip
        url:
          description: WHIP endpoint for the face camera (and the microphone). POST the SDP offer here, sealed with the capability.
          type: string
          format: uri
        bodyUrl:
          description: WHIP endpoint for the optional body view, when `inputs.body` is true.
          type:
            - string
            - "null"
          format: uri
        attestationUrl:
          description: The enclave's attestation. Check it before publishing.
          type: string
          format: uri
        seal:
          description: The request-sealing scheme the enclave requires.
          type: string
          const: v1
        iceServersUrl:
          description: STUN and TURN servers for devices on strict networks; read with the client token.
          type: string
          format: uri
        expiresAt:
          description: Publish before this time, or the session ends with `media_timeout`.
          type: string
          format: date-time
        video:
          $ref: "#/components/schemas/VideoRequirements"
        audio:
          type: object
          required:
            - codecs
            - expected
          properties:
            codecs:
              type: array
              items:
                type: string
                enum:
                  - opus
            expected:
              description: Whether the session declared the microphone.
              type: boolean
    Results:
      title: Results
      description: Where the session's events arrive.
      type: object
      required:
        - streamUrl
        - websocketUrl
        - eventsUrl
        - clientToken
        - clientTokenExpiresAt
      properties:
        streamUrl:
          description: Server-sent events (`streamLiveSessionEvents`).
          type: string
          format: uri
        websocketUrl:
          description: The same events over a WebSocket, which also takes `stimulation` reports from your product. Connect with `?token=` and the client token, or an `Authorization` header with the secret key or the client token where your client can set one. View tokens read `streamUrl` instead.
          type: string
          format: uri
        eventsUrl:
          description: The event list, for polling (`listLiveSessionEvents`).
          type: string
          format: uri
        clientToken:
          description: Reads this session's events and reports its stimulation, nothing else. Safe to hand to the end user's device. For another screen, make a read-only view token instead (`createViewToken`).
          type: string
          pattern: ^ct_[0-9a-z]{32}$
        clientTokenExpiresAt:
          description: "The latest the client token can work: the end of the longest the session may run, plus five minutes. It stops sooner, five minutes after the session ends."
          type: string
          format: date-time
    LatestImminence:
      title: LatestImminence
      description: The newest `imminence.updated`, in brief.
      type: object
      required:
        - p30
        - p60
        - streamTimeS
        - eventId
      properties:
        p30:
          type:
            - number
            - "null"
          minimum: 0
          maximum: 1
        p60:
          type:
            - number
            - "null"
          minimum: 0
          maximum: 1
        streamTimeS:
          type: number
        eventId:
          type: string
          pattern: ^evt_[0-9a-z]{20}$
    LiveSession:
      title: LiveSession
      description: One person's live camera stream, from creation to its final status.
      type: object
      required:
        - id
        - object
        - mode
        - status
        - degraded
        - inputs
        - signals
        - subject
        - latestImminence
        - ingest
        - enclave
        - charges
        - results
        - subjectHint
        - maxDurationS
        - retentionDays
        - webhookEndpointId
        - userReference
        - clientReferenceId
        - metadata
        - sandbox
        - createdAt
        - startedAt
        - endedAt
        - endedReason
        - resultsExpireAt
      properties:
        id:
          type: string
          pattern: ^ls_[0-9a-z]{20}$
        object:
          type: string
          const: live_session
        mode:
          type: string
          enum:
            - test
            - live
        status:
          $ref: "#/components/schemas/LiveSessionStatus"
        degraded:
          description: A declared input is missing or the face is not visible.
          type: boolean
        inputs:
          $ref: "#/components/schemas/InputsPresence"
        signals:
          description: The signal events this session can produce, given its declared inputs. Without the microphone it is only `imminence.updated`, `signals.updated`, `subject.identified` and `edge.completed`.
          type: array
          items:
            $ref: "#/components/schemas/EventType"
        subject:
          description: The subject read, once it is made (`subject.identified`).
          oneOf:
            - $ref: "#/components/schemas/SubjectIdentifiedData"
            - type: "null"
        latestImminence:
          oneOf:
            - $ref: "#/components/schemas/LatestImminence"
            - type: "null"
        ingest:
          description: "`null` once the session has ended."
          oneOf:
            - $ref: "#/components/schemas/Ingest"
            - type: "null"
        enclave:
          description: "The enclave this session is analysed in, as orgasm.dev verified it once the session's enclave was attested: the release and the commit it was built from, the hardware, and the token Google's attestation service signed for this session, which you can verify yourself. `null` until then, and in the sandbox, which runs no enclave."
          oneOf:
            - $ref: "#/components/schemas/EnclaveReceipt"
            - type: "null"
        charges:
          $ref: "#/components/schemas/LiveSessionCharges"
        results:
          $ref: "#/components/schemas/Results"
        subjectHint:
          type:
            - string
            - "null"
          enum:
            - woman
            - man
            - null
        maxDurationS:
          type: integer
        retentionDays:
          type: integer
        webhookEndpointId:
          type:
            - string
            - "null"
        userReference:
          description: The `userReference` it was created with, or `null`.
          oneOf:
            - $ref: "#/components/schemas/UserReference"
            - type: "null"
        clientReferenceId:
          description: The `clientReferenceId` it was created with, or `null`.
          oneOf:
            - $ref: "#/components/schemas/ClientReferenceId"
            - type: "null"
        metadata:
          $ref: "#/components/schemas/Metadata"
        sandbox:
          description: The sandbox options the session plays, or `null` in live mode.
          oneOf:
            - $ref: "#/components/schemas/SandboxOptions"
            - type: "null"
        createdAt:
          type: string
          format: date-time
        startedAt:
          description: When media first arrived.
          type:
            - string
            - "null"
          format: date-time
        endedAt:
          type:
            - string
            - "null"
          format: date-time
        endedReason:
          type:
            - string
            - "null"
          enum:
            - client_ended
            - media_ended
            - media_timeout
            - max_duration
            - interrupted
            - policy
            - error
            - null
        resultsExpireAt:
          description: When the session's events are deleted, once it has ended.
          type:
            - string
            - "null"
          format: date-time
    LiveSessionCharges:
      title: LiveSessionCharges
      description: "What the session has been charged so far: each orgasm once by its `orgasmIndex` (a ruin in place of an orgasm when `orgasm.end` says `ruined`), each `edge.completed`, and, when a session with more than a minute of media ends having counted none of them, the session minimum. In test mode everything is counted the same way and `credits` stays 0."
      type: object
      required:
        - orgasms
        - ruins
        - edges
        - sessionMinimum
        - credits
      properties:
        orgasms:
          description: Orgasms charged, a credit each.
          type: integer
          minimum: 0
        ruins:
          description: Ruined orgasms charged, a credit each.
          type: integer
          minimum: 0
        edges:
          description: Edges charged, half a credit each.
          type: integer
          minimum: 0
        sessionMinimum:
          description: The session ended with more than a minute of media and nothing counted, and was charged half a credit. Never for a session that ended `interrupted` or with an `error`.
          type: boolean
        credits:
          description: Credits drawn, in halves.
          type: number
          minimum: 0
          multipleOf: 0.5
    LiveSessionList:
      title: LiveSessionList
      description: A page of live sessions.
      type: object
      required:
        - object
        - data
        - hasMore
        - nextCursor
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/LiveSession"
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - "null"
    LiveSessionPurgeRequest:
      title: LiveSessionPurgeRequest
      description: Whose live sessions to purge.
      type: object
      required:
        - userReference
      properties:
        userReference:
          $ref: "#/components/schemas/UserReference"
    LiveSessionPurgeResult:
      title: LiveSessionPurgeResult
      description: The live sessions a purge deleted.
      type: object
      required:
        - object
        - userReference
        - deleted
        - ids
      properties:
        object:
          type: string
          const: live_session_purge
        userReference:
          $ref: "#/components/schemas/UserReference"
        deleted:
          description: How many sessions were deleted.
          type: integer
          minimum: 0
        ids:
          description: The deleted sessions' ids.
          type: array
          items:
            type: string
            pattern: ^ls_[0-9a-z]{20}$
    EventUnion:
      title: EventUnion
      description: Any event. Switch on `type`.
      oneOf:
        - $ref: "#/components/schemas/ImminenceUpdatedEvent"
        - $ref: "#/components/schemas/SignalsUpdatedEvent"
        - $ref: "#/components/schemas/StimulationUpdatedEvent"
        - $ref: "#/components/schemas/OrgasmOnsetEvent"
        - $ref: "#/components/schemas/OrgasmPeakEvent"
        - $ref: "#/components/schemas/OrgasmEndEvent"
        - $ref: "#/components/schemas/EdgeCompletedEvent"
        - $ref: "#/components/schemas/SubjectIdentifiedEvent"
        - $ref: "#/components/schemas/SessionStatusEvent"
        - $ref: "#/components/schemas/InputWarningEvent"
        - $ref: "#/components/schemas/RecordingCompletedEvent"
        - $ref: "#/components/schemas/RecordingFailedEvent"
      discriminator:
        propertyName: type
        mapping:
          imminence.updated: "#/components/schemas/ImminenceUpdatedEvent"
          signals.updated: "#/components/schemas/SignalsUpdatedEvent"
          stimulation.updated: "#/components/schemas/StimulationUpdatedEvent"
          orgasm.onset: "#/components/schemas/OrgasmOnsetEvent"
          orgasm.peak: "#/components/schemas/OrgasmPeakEvent"
          orgasm.end: "#/components/schemas/OrgasmEndEvent"
          edge.completed: "#/components/schemas/EdgeCompletedEvent"
          subject.identified: "#/components/schemas/SubjectIdentifiedEvent"
          session.status: "#/components/schemas/SessionStatusEvent"
          input.warning: "#/components/schemas/InputWarningEvent"
          recording.completed: "#/components/schemas/RecordingCompletedEvent"
          recording.failed: "#/components/schemas/RecordingFailedEvent"
    EventList:
      title: EventList
      description: A page of events, oldest first.
      type: object
      required:
        - object
        - data
        - hasMore
        - nextCursor
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/EventUnion"
        hasMore:
          description: More events are available now; ask again with `after` set to `nextCursor`.
          type: boolean
        nextCursor:
          description: The `id` of the last event in `data`, to pass as `after`. `null` when `data` is empty.
          type:
            - string
            - "null"
    StimulationReport:
      title: StimulationReport
      description: A change in stimulation, reported by your product. Every field but `state` is optional; one you omit keeps the value you last reported, and `null` clears it.
      type: object
      required:
        - state
      properties:
        state:
          description: Whether stimulation is now on or off. An `off` while `p30` is at 0.75 or above, followed within 30 seconds by an orgasm, makes that orgasm a ruin.
          type: string
          enum:
            - on
            - off
        intensity:
          description: The intensity now, from 0 to 1 on your product's own scale. Omit it if your product has no intensity.
          type:
            - number
            - "null"
          minimum: 0
          maximum: 1
        level:
          description: The device's level now, on its own scale (for example 0 to 100).
          type:
            - number
            - "null"
          minimum: 0
        levelMax:
          description: The highest level the device will go to now, on the same scale; a display fills a bar toward it.
          type:
            - number
            - "null"
          exclusiveMinimum: 0
        channels:
          description: Each output's level, for a device with more than one (at most four).
          type:
            - array
            - "null"
          maxItems: 4
          items:
            $ref: "#/components/schemas/StimulationReportChannel"
        mode:
          description: The device's mode or pattern, as your product names it (for example `waves`).
          type:
            - string
            - "null"
          maxLength: 40
        modeLabel:
          description: The mode's name to show the person; without it a display shows `mode` in words.
          type:
            - string
            - "null"
          maxLength: 40
        device:
          oneOf:
            - $ref: "#/components/schemas/StimulationReportDevice"
            - type: "null"
        drive:
          description: "Who sets the level: `auto` (your product, following the person's signals), `manual` (the person's own hand), `hold` (held where it is) or `paused`."
          type:
            - string
            - "null"
          enum:
            - auto
            - manual
            - hold
            - paused
            - null
        streamTimeS:
          description: When the change happened, in stream seconds. Omit it to mean now.
          type: number
          minimum: 0
    CreateViewTokenRequest:
      title: CreateViewTokenRequest
      description: What a view token may read, and for how long.
      type: object
      additionalProperties: false
      properties:
        includeSubject:
          description: Include `subject.identified`, the face read. False by default.
          type: boolean
          default: false
        includeFace:
          description: "Include the face's channels: `signals.updated` with its `face`, and `face.frame` on a stream that asks for them. False by default."
          type: boolean
          default: false
        expiresInS:
          description: How long the token works, in seconds, up to 24 hours. By default, until five minutes after the longest the session may run; it stops five minutes after the session ends in any case.
          type: integer
          minimum: 60
          maximum: 86400
    ViewToken:
      title: ViewToken
      description: A read-only token for one session's events (`createViewToken`).
      type: object
      required:
        - object
        - token
        - sessionId
        - eventTypes
        - face
        - createdAt
        - expiresAt
      properties:
        object:
          type: string
          const: view_token
        token:
          description: "Sent as `Authorization: Bearer vt_…`. Shown only once."
          type: string
          pattern: ^vt_[0-9a-z]{32}$
        sessionId:
          type: string
          pattern: ^ls_[0-9a-z]{20}$
        eventTypes:
          description: The event types the token reads.
          type: array
          items:
            $ref: "#/components/schemas/EventType"
        face:
          description: Whether the token reads the face's channels (`includeFace`).
          type: boolean
        createdAt:
          type: string
          format: date-time
        expiresAt:
          description: The latest the token works; it stops sooner, five minutes after the session ends.
          type: string
          format: date-time
    StimulationReceipt:
      title: StimulationReceipt
      description: "Confirms a stimulation report, with the stimulation as it now stands: this report merged over the ones before it."
      type: object
      required:
        - object
        - sessionId
        - state
        - intensity
        - streamTimeS
        - stimulationAware
        - stimulation
      properties:
        object:
          type: string
          const: stimulation_report
        sessionId:
          type: string
        state:
          type: string
          enum:
            - on
            - off
        intensity:
          type:
            - number
            - "null"
        streamTimeS:
          type: number
        stimulationAware:
          description: Imminence now accounts for time under stimulation.
          type: boolean
        stimulation:
          $ref: "#/components/schemas/StimulationData"
    RecordingStatus:
      title: RecordingStatus
      description: Where a recording is in processing.
      type: string
      enum:
        - awaiting_upload
        - queued
        - processing
        - completed
        - failed
    RecordingSourceUpload:
      title: RecordingSourceUpload
      description: You upload the file to `uploads.face.url`.
      type: object
      required:
        - type
      properties:
        type:
          type: string
          const: upload
        bodyView:
          description: You will also upload a second video of the person's body, recorded at the same time.
          type: boolean
          default: false
        bodyOffsetS:
          description: The body video starts this many seconds after the face video.
          type: number
          default: 0
    RecordingSourceUrl:
      title: RecordingSourceUrl
      description: The enclave fetches the file from `url`.
      type: object
      required:
        - type
        - url
      properties:
        type:
          type: string
          const: url
        url:
          description: An HTTPS URL the enclave can fetch the face video from, such as a signed URL valid for at least an hour.
          type: string
          format: uri
        bodyUrl:
          description: An HTTPS URL for an optional body video recorded at the same time.
          type: string
          format: uri
        bodyOffsetS:
          description: The body video starts this many seconds after the face video.
          type: number
          default: 0
    RecordingCreateRequest:
      title: RecordingCreateRequest
      description: What to submit a recording with. `consent` and `source` are required.
      type: object
      required:
        - consent
        - source
      properties:
        consent:
          $ref: "#/components/schemas/Consent"
        source:
          oneOf:
            - $ref: "#/components/schemas/RecordingSourceUpload"
            - $ref: "#/components/schemas/RecordingSourceUrl"
          discriminator:
            propertyName: type
            mapping:
              upload: "#/components/schemas/RecordingSourceUpload"
              url: "#/components/schemas/RecordingSourceUrl"
        inputs:
          description: Whether to analyse the recording's audio track (recommended).
          type: object
          properties:
            audio:
              type: boolean
              default: true
        subjectHint:
          type: string
          enum:
            - woman
            - man
        retentionDays:
          type: integer
          minimum: 0
          maximum: 90
          default: 30
        webhookEndpointId:
          type: string
          pattern: ^we_[0-9a-z]{20}$
        userReference:
          $ref: "#/components/schemas/UserReference"
        clientReferenceId:
          $ref: "#/components/schemas/ClientReferenceId"
        metadata:
          $ref: "#/components/schemas/Metadata"
        sandbox:
          $ref: "#/components/schemas/SandboxOptions"
    Upload:
      title: Upload
      description: Where to `PUT` one video file.
      type: object
      required:
        - url
        - method
        - headers
        - maxBytes
        - expiresAt
        - sealed
      properties:
        url:
          type: string
          format: uri
        method:
          type: string
          const: PUT
        headers:
          description: Headers to send with the upload.
          type: object
          additionalProperties:
            type: string
        maxBytes:
          type: integer
        expiresAt:
          type: string
          format: date-time
        sealed:
          description: The body must be sealed to the enclave before upload, as the SDK does, so that only the enclave can read it. Always `false` in the sandbox.
          type: boolean
    OrgasmSummary:
      title: OrgasmSummary
      description: One orgasm in a recording, assembled from its calls.
      type: object
      required:
        - orgasmIndex
        - detectors
        - onsetAtS
        - peakAtS
        - endAtS
        - durationS
        - confidence
      properties:
        orgasmIndex:
          type: integer
          minimum: 1
        detectors:
          type: array
          items:
            $ref: "#/components/schemas/Detector"
        onsetAtS:
          type:
            - number
            - "null"
        peakAtS:
          type:
            - number
            - "null"
        endAtS:
          type:
            - number
            - "null"
        durationS:
          type:
            - number
            - "null"
        confidence:
          $ref: "#/components/schemas/Confidence"
    RecordingResult:
      title: RecordingResult
      description: What the analysis found in a recording.
      type: object
      required:
        - subject
        - summary
        - timeline
      properties:
        subject:
          oneOf:
            - $ref: "#/components/schemas/SubjectIdentifiedData"
            - type: "null"
        summary:
          type: object
          required:
            - durationS
            - orgasmCount
            - orgasms
          properties:
            durationS:
              type: number
            orgasmCount:
              type: integer
              minimum: 0
            orgasms:
              type: array
              items:
                $ref: "#/components/schemas/OrgasmSummary"
        timeline:
          description: "The discrete events, in order: orgasm calls, the subject read and input warnings. Imminence is in `listRecordingEvents`."
          type: array
          items:
            $ref: "#/components/schemas/EventUnion"
    Recording:
      title: Recording
      description: One recorded video, from submission to its result.
      type: object
      required:
        - id
        - object
        - mode
        - status
        - source
        - uploads
        - inputs
        - progress
        - result
        - failure
        - subjectHint
        - retentionDays
        - webhookEndpointId
        - userReference
        - clientReferenceId
        - metadata
        - sandbox
        - createdAt
        - startedAt
        - completedAt
        - resultsExpireAt
      properties:
        id:
          type: string
          pattern: ^rec_[0-9a-z]{20}$
        object:
          type: string
          const: recording
        mode:
          type: string
          enum:
            - test
            - live
        status:
          $ref: "#/components/schemas/RecordingStatus"
        source:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - upload
                - url
            url:
              description: The URL the enclave fetched, without its query string.
              type: string
        uploads:
          description: Where to upload, while `status` is `awaiting_upload`; `null` after.
          oneOf:
            - type: object
              required:
                - face
                - body
              properties:
                face:
                  $ref: "#/components/schemas/Upload"
                body:
                  oneOf:
                    - $ref: "#/components/schemas/Upload"
                    - type: "null"
            - type: "null"
        inputs:
          type: object
          required:
            - audio
            - body
          properties:
            audio:
              type: boolean
            body:
              type: boolean
        progress:
          description: How far processing has got, while `processing`.
          oneOf:
            - type: object
              required:
                - processedS
                - durationS
              properties:
                processedS:
                  type: number
                durationS:
                  type:
                    - number
                    - "null"
            - type: "null"
        result:
          description: Present once `status` is `completed`.
          oneOf:
            - $ref: "#/components/schemas/RecordingResult"
            - type: "null"
        failure:
          description: Present once `status` is `failed`.
          oneOf:
            - $ref: "#/components/schemas/RecordingFailedData"
            - type: "null"
        subjectHint:
          type:
            - string
            - "null"
          enum:
            - woman
            - man
            - null
        retentionDays:
          type: integer
        webhookEndpointId:
          type:
            - string
            - "null"
        userReference:
          description: The `userReference` it was submitted with, or `null`.
          oneOf:
            - $ref: "#/components/schemas/UserReference"
            - type: "null"
        clientReferenceId:
          description: The `clientReferenceId` it was submitted with, or `null`.
          oneOf:
            - $ref: "#/components/schemas/ClientReferenceId"
            - type: "null"
        metadata:
          $ref: "#/components/schemas/Metadata"
        sandbox:
          oneOf:
            - $ref: "#/components/schemas/SandboxOptions"
            - type: "null"
        createdAt:
          type: string
          format: date-time
        startedAt:
          description: When processing started.
          type:
            - string
            - "null"
          format: date-time
        completedAt:
          type:
            - string
            - "null"
          format: date-time
        resultsExpireAt:
          type:
            - string
            - "null"
          format: date-time
    RecordingList:
      title: RecordingList
      description: A page of recordings.
      type: object
      required:
        - object
        - data
        - hasMore
        - nextCursor
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/Recording"
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - "null"
    UploadReceipt:
      title: UploadReceipt
      description: Confirms a sandbox upload.
      type: object
      required:
        - object
        - recordingId
        - view
        - bytesReceived
      properties:
        object:
          type: string
          const: upload_receipt
        recordingId:
          type: string
        view:
          type: string
          enum:
            - face
            - body
        bytesReceived:
          type: integer
    WebhookEventType:
      title: WebhookEventType
      description: Every event type except `imminence.updated`, `signals.updated` and `stimulation.updated`, which are only streamed, and `credits.low`, your company's balance, which only webhooks carry (to live endpoints).
      type: string
      enum:
        - orgasm.onset
        - orgasm.peak
        - orgasm.end
        - edge.completed
        - subject.identified
        - session.status
        - input.warning
        - recording.completed
        - recording.failed
        - credits.low
    WebhookEndpointCreateRequest:
      title: WebhookEndpointCreateRequest
      description: Where to deliver events, and which.
      type: object
      required:
        - url
        - events
      properties:
        url:
          description: An HTTPS URL on your server. In test mode `http://localhost` and `http://127.0.0.1` are accepted too, for local development.
          type: string
          format: uri
          pattern: ^(https://|http://localhost(:[0-9]+)?/|http://127\.0\.0\.1(:[0-9]+)?/)
        events:
          description: The event types to deliver.
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: "#/components/schemas/WebhookEventType"
        description:
          type: string
          maxLength: 500
        enabled:
          type: boolean
          default: true
    WebhookEndpointUpdateRequest:
      title: WebhookEndpointUpdateRequest
      description: What to change on an endpoint. What you leave out stays as it is.
      type: object
      minProperties: 1
      properties:
        url:
          description: An HTTPS URL on your server. In test mode `http://localhost` and `http://127.0.0.1` are accepted too, for local development.
          type: string
          format: uri
          pattern: ^(https://|http://localhost(:[0-9]+)?/|http://127\.0\.0\.1(:[0-9]+)?/)
        events:
          description: The event types to deliver, replacing the current ones.
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: "#/components/schemas/WebhookEventType"
        description:
          type:
            - string
            - "null"
          maxLength: 500
        enabled:
          type: boolean
    WebhookEndpoint:
      title: WebhookEndpoint
      description: A URL on your server that receives events.
      type: object
      required:
        - id
        - object
        - mode
        - url
        - events
        - description
        - enabled
        - secret
        - previousSecretExpiresAt
        - createdAt
      properties:
        id:
          type: string
          pattern: ^we_[0-9a-z]{20}$
        object:
          type: string
          const: webhook_endpoint
        mode:
          type: string
          enum:
            - test
            - live
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEventType"
        description:
          type:
            - string
            - "null"
        enabled:
          type: boolean
        secret:
          description: The signing secret (`whsec_` and base64), only in the response that created the endpoint or rolled its secret; `null` afterwards.
          type:
            - string
            - "null"
        previousSecretExpiresAt:
          description: After `rollWebhookSecret`, until when deliveries are also signed with the previous secret; `null` otherwise.
          type:
            - string
            - "null"
          format: date-time
        createdAt:
          type: string
          format: date-time
    WebhookEndpointList:
      title: WebhookEndpointList
      description: A page of webhook endpoints.
      type: object
      required:
        - object
        - data
        - hasMore
        - nextCursor
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/WebhookEndpoint"
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - "null"
    TestWebhookRequest:
      title: TestWebhookRequest
      description: Which event type to send as the sample. Defaults to `orgasm.onset`.
      type: object
      properties:
        type:
          $ref: "#/components/schemas/WebhookEventType"
    TestWebhookResult:
      title: TestWebhookResult
      description: How your server answered a test delivery.
      type: object
      required:
        - object
        - delivered
        - statusCode
        - durationMs
        - error
        - headers
        - event
      properties:
        object:
          type: string
          const: webhook_test
        delivered:
          type: boolean
        statusCode:
          description: Your server's status code, or `null` when no response arrived.
          type:
            - integer
            - "null"
        durationMs:
          type: integer
        error:
          description: Why the delivery failed, when it did.
          type:
            - string
            - "null"
        headers:
          description: The signature headers that were sent.
          type: object
          required:
            - webhookId
            - webhookTimestamp
            - webhookSignature
          properties:
            webhookId:
              description: The `webhook-id` header.
              type: string
            webhookTimestamp:
              description: The `webhook-timestamp` header.
              type: string
            webhookSignature:
              description: The `webhook-signature` header.
              type: string
        event:
          description: The sample that was sent.
          oneOf:
            - $ref: "#/components/schemas/EventUnion"
            - $ref: "#/components/schemas/CreditsLowEvent"
    UsageDay:
      title: UsageDay
      description: Usage on one UTC day.
      type: object
      required:
        - date
        - liveSessions
        - liveSeconds
        - recordings
        - recordingSeconds
        - orgasms
        - ruins
        - edges
        - sessionMinimums
        - credits
      properties:
        date:
          type: string
          format: date
        liveSessions:
          type: integer
        liveSeconds:
          description: Seconds of analysed live media.
          type: integer
        recordings:
          type: integer
        recordingSeconds:
          description: Seconds of analysed recordings.
          type: integer
        orgasms:
          description: Orgasms counted in live sessions.
          type: integer
        ruins:
          description: Ruined orgasms counted.
          type: integer
        edges:
          description: Edges counted.
          type: integer
        sessionMinimums:
          description: Sessions charged the minimum.
          type: integer
        credits:
          description: Credits drawn; 0 in test mode, which is free.
          type: number
    Usage:
      title: Usage
      description: Usage per day over a range of days.
      type: object
      required:
        - object
        - mode
        - from
        - to
        - days
        - totals
      properties:
        object:
          type: string
          const: usage
        mode:
          type: string
          enum:
            - test
            - live
        from:
          type: string
          format: date
        to:
          type: string
          format: date
        days:
          type: array
          items:
            $ref: "#/components/schemas/UsageDay"
        totals:
          type: object
          required:
            - liveSessions
            - liveSeconds
            - recordings
            - recordingSeconds
            - orgasms
            - ruins
            - edges
            - sessionMinimums
            - credits
          properties:
            liveSessions:
              type: integer
            liveSeconds:
              type: integer
            recordings:
              type: integer
            recordingSeconds:
              type: integer
            orgasms:
              type: integer
            ruins:
              type: integer
            edges:
              type: integer
            sessionMinimums:
              type: integer
            credits:
              type: number
    CreditPackage:
      title: CreditPackage
      description: "Credits your company received: the free 20, or a package bought under a statement of work, posted once its invoice was paid."
      type: object
      required:
        - id
        - object
        - package
        - credits
        - remaining
        - pricePerCredit
        - postedAt
        - expiresAt
      properties:
        id:
          type: string
          pattern: ^(free|pkg_[0-9a-z]{20})$
        object:
          type: string
          const: credit_package
        package:
          description: Which package it is.
          type: string
          enum:
            - free
            - pilot
            - launch
            - growth
            - scale
            - enterprise
        credits:
          description: Credits it posted.
          type: number
        remaining:
          description: Credits it still holds.
          type: number
        pricePerCredit:
          description: The price of each of its credits in US dollars; 0 for the free credits.
          type: number
          minimum: 0
        postedAt:
          type: string
          format: date-time
        expiresAt:
          description: When what it still holds expires, 12 months after it posted; `null` for the free credits, which do not expire.
          type:
            - string
            - "null"
          format: date-time
    CreditBalance:
      title: CreditBalance
      description: Your company's credits, shared by its members and keys. Free credits are used first, then the package that expires soonest.
      type: object
      required:
        - object
        - domain
        - balance
        - free
        - packages
        - expiringSoon
        - enforced
      properties:
        object:
          type: string
          const: credit_balance
        domain:
          description: The company domain the credits belong to.
          type: string
        balance:
          description: Credits available, in halves. Below zero when sessions that were running at zero used more; the next package that posts covers it.
          type: number
        free:
          type: object
          required:
            - granted
            - remaining
          properties:
            granted:
              type: number
            remaining:
              type: number
        packages:
          description: Every package with credits left, in the order they are used, then the used and expired ones.
          type: array
          items:
            $ref: "#/components/schemas/CreditPackage"
        expiringSoon:
          description: Credits that expire within 30 days, and the first such expiry, or `null`.
          oneOf:
            - type: object
              required:
                - credits
                - at
              properties:
                credits:
                  type: number
                at:
                  type: string
                  format: date-time
            - type: "null"
        enforced:
          description: Whether a new live session is refused at zero (`credits_exhausted`). `false` while orgasm.dev is only counting.
          type: boolean
    ChargeUnit:
      title: ChargeUnit
      description: "What a charge is for: an orgasm, a ruin, an edge, or the session minimum."
      type: string
      enum:
        - orgasm
        - ruin
        - edge
        - session_minimum
    Charge:
      title: Charge
      description: "One outcome a live session was charged for, and what it cost: an orgasm or a ruin is a credit, an edge or the session minimum half a credit. Its paid credits cost their package's price per credit; free credits cost nothing; credits used past zero are `pendingCredits` until a package posts and covers them, at that package's price."
      type: object
      required:
        - id
        - object
        - mode
        - sessionId
        - unit
        - index
        - at
        - credits
        - freeCredits
        - paidCredits
        - pendingCredits
        - amountUsd
        - packages
        - returned
        - ownGpu
        - apiKeyId
        - userReference
        - clientReferenceId
        - metadata
      properties:
        id:
          description: The session, the unit and its index. A charge is made once, so this never repeats.
          type: string
          pattern: ^ls_[0-9a-z]{20}\.(orgasm|ruin|edge|session_minimum)\.[0-9]+$
        object:
          type: string
          const: charge
        mode:
          type: string
          enum:
            - test
            - live
        sessionId:
          type: string
          pattern: ^ls_[0-9a-z]{20}$
        unit:
          $ref: "#/components/schemas/ChargeUnit"
        index:
          description: The orgasm's `orgasmIndex` or the edge's `edgeIndex`; 1 for the session minimum.
          type: integer
          minimum: 1
        at:
          description: When it was charged.
          type: string
          format: date-time
        credits:
          description: Credits it drew, in halves; 0 in test mode, which is free.
          type: number
          minimum: 0
          multipleOf: 0.5
        freeCredits:
          description: Of them, free credits.
          type: number
          minimum: 0
        paidCredits:
          description: Of them, credits from a package, including credits used past zero that a later package covered.
          type: number
          minimum: 0
        pendingCredits:
          description: Of them, credits used past zero that no package has covered yet.
          type: number
          minimum: 0
        amountUsd:
          description: "What it cost in US dollars: its paid credits at their packages' prices. 0 when a review returned it."
          type: number
          minimum: 0
        packages:
          description: The packages its credits came from, and at what price.
          type: array
          items:
            type: object
            required:
              - id
              - credits
              - pricePerCredit
            properties:
              id:
                type: string
                pattern: ^(free|pkg_[0-9a-z]{20})$
              credits:
                type: number
              pricePerCredit:
                type: number
                minimum: 0
        returned:
          description: A review found the call wrong and returned its credits.
          type: boolean
        ownGpu:
          description: The session ran on your own GPUs.
          type: boolean
        apiKeyId:
          description: The key the session was created with.
          type:
            - string
            - "null"
        userReference:
          description: The session's `userReference`; `null` when it had none, once the session is purged, and 13 months after it ended.
          oneOf:
            - $ref: "#/components/schemas/UserReference"
            - type: "null"
        clientReferenceId:
          description: The session's `clientReferenceId`, erased with its `userReference`.
          oneOf:
            - $ref: "#/components/schemas/ClientReferenceId"
            - type: "null"
        metadata:
          description: The session's metadata, `{}` once erased.
          $ref: "#/components/schemas/Metadata"
    ChargeTotals:
      title: ChargeTotals
      description: Every charge the filters match, across all pages.
      type: object
      required:
        - charges
        - credits
        - freeCredits
        - paidCredits
        - pendingCredits
        - amountUsd
      properties:
        charges:
          type: integer
          minimum: 0
        credits:
          type: number
          minimum: 0
        freeCredits:
          type: number
          minimum: 0
        paidCredits:
          type: number
          minimum: 0
        pendingCredits:
          type: number
          minimum: 0
        amountUsd:
          type: number
          minimum: 0
    ChargeList:
      title: ChargeList
      description: A page of charges, newest first, and the totals of every charge that matches.
      type: object
      required:
        - object
        - data
        - totals
        - hasMore
        - nextCursor
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/Charge"
        totals:
          $ref: "#/components/schemas/ChargeTotals"
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - "null"
    Model:
      title: Model
      description: A model behind one or more signals.
      type: object
      required:
        - id
        - object
        - version
        - description
        - produces
        - requires
        - benefitsFrom
        - appliesTo
        - availability
      properties:
        id:
          type: string
          enum:
            - imminence
            - onset-end
            - peak
            - face-end
            - subject
        object:
          type: string
          const: model
        version:
          type: string
        description:
          type: string
        produces:
          type: array
          items:
            $ref: "#/components/schemas/EventType"
        requires:
          description: Inputs without which the model does not run.
          type: array
          items:
            type: string
            enum:
              - face
              - audio
        benefitsFrom:
          description: Optional inputs that add to the model's calls.
          type: array
          items:
            type: string
            enum:
              - body
              - stimulation
        appliesTo:
          type: string
          enum:
            - woman
            - man
            - any
        availability:
          type: object
          required:
            - test
            - live
          properties:
            test:
              description: Simulated in the sandbox.
              type: boolean
            live:
              description: Available with live keys.
              type: boolean
    ModelList:
      title: ModelList
      description: Every model.
      type: object
      required:
        - object
        - data
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/Model"
    ApiKeyType:
      title: ApiKeyType
      description: "`secret`: everything in this API. `billing`: reads `getCredits`, `getUsage` and `listCharges` and nothing else, in live mode only."
      type: string
      enum:
        - secret
        - billing
    ApiKeyCreateRequest:
      title: ApiKeyCreateRequest
      description: A name, a mode and, optionally, a type for a new key.
      type: object
      required:
        - name
        - mode
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        mode:
          type: string
          enum:
            - test
            - live
        type:
          description: "`secret` by default. A `billing` key must be `live`."
          $ref: "#/components/schemas/ApiKeyType"
    ApiKeyRollRequest:
      title: ApiKeyRollRequest
      description: When the key being replaced stops working.
      type: object
      properties:
        expiresInS:
          description: "Seconds until the old key stops working: 0 (at once, the default), an hour, a day or a week."
          type: integer
          enum:
            - 0
            - 3600
            - 86400
            - 604800
          default: 0
    ApiKey:
      title: ApiKey
      description: A key of your company's.
      type: object
      required:
        - id
        - object
        - name
        - mode
        - type
        - redacted
        - secret
        - createdBy
        - createdAt
        - lastUsedAt
        - expiresAt
      properties:
        id:
          type: string
          pattern: ^key_[0-9a-z]{20}$
        object:
          type: string
          const: api_key
        name:
          type: string
        mode:
          type: string
          enum:
            - test
            - live
        type:
          $ref: "#/components/schemas/ApiKeyType"
        redacted:
          description: The key's prefix and last four characters.
          type: string
        secret:
          description: The whole key, only in the response that created or rolled it.
          type:
            - string
            - "null"
        createdBy:
          description: The email of the member who made it in the console, or `null` for a key made through this API.
          type:
            - string
            - "null"
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type:
            - string
            - "null"
          format: date-time
        expiresAt:
          description: When a rolled key stops working; `null` for a key that does not expire.
          type:
            - string
            - "null"
          format: date-time
    ApiKeyList:
      title: ApiKeyList
      description: A page of API keys.
      type: object
      required:
        - object
        - data
        - hasMore
        - nextCursor
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: "#/components/schemas/ApiKey"
        hasMore:
          type: boolean
        nextCursor:
          type:
            - string
            - "null"
    AttestationPolicy:
      title: AttestationPolicy
      description: What an enclave's attestation must show before a device sends it media. In test mode no enclave runs, and the policy says so.
      type: object
      required:
        - object
        - mode
        - version
        - enforced
        - issuer
        - hardware
        - image
        - seal
        - evidence
        - debugAllowed
        - verify
        - updatedAt
      properties:
        object:
          type: string
          const: attestation_policy
        mode:
          type: string
          enum:
            - test
            - live
        version:
          type: string
        enforced:
          description: Whether devices must verify an attestation in this mode.
          type: boolean
        issuer:
          description: The issuer the attestation token must be signed by.
          type:
            - string
            - "null"
          format: uri
        hardware:
          description: The confidential-computing hardware the enclave must run on.
          type: array
          items:
            type: string
        image:
          type: object
          required:
            - source
            - minRelease
            - digests
            - signers
            - repository
            - releasesUrl
          properties:
            source:
              description: The public source the enclave image is built from.
              type:
                - string
                - "null"
              format: uri
            minRelease:
              description: The oldest enclave release accepted.
              type:
                - string
                - "null"
            digests:
              description: "Accepted image digests. Empty: any digest that carries an accepted signature and an accepted release."
              type: array
              items:
                type: string
                pattern: ^sha256:[0-9a-f]{64}$
            signers:
              description: "The keys the image must be signed by, as hex SHA-256 fingerprints of their public keys: the attestation reports the keys the launcher verified the image's signature with in `submods.container.image_signatures[].key_id`."
              type: array
              items:
                type: string
                pattern: ^[0-9a-f]{64}$
            repository:
              description: The public registry that holds each released digest with its SLSA provenance and keyless signature.
              type:
                - string
                - "null"
            releasesUrl:
              description: Every release, the digest it built and the commands that check it.
              type:
                - string
                - "null"
              format: uri
        seal:
          type: object
          required:
            - schemes
          properties:
            schemes:
              type: array
              items:
                type: string
                enum:
                  - v1
        evidence:
          description: How the enclave signs its answers to the device.
          type: object
          required:
            - algorithm
          properties:
            algorithm:
              type: string
              const: Ed25519
        debugAllowed:
          description: Whether a debuggable enclave is accepted. Never in live mode.
          type: boolean
        verify:
          description: What the enclave's own verifier (`tee-verify`, in the enclave's source) holds a running enclave to, for the enclaves this mode's sessions run on. `null` in test mode.
          oneOf:
            - $ref: "#/components/schemas/VerifierValues"
            - type: "null"
        note:
          type: string
        updatedAt:
          type: string
          format: date-time
    VerifierValues:
      title: VerifierValues
      description: The values `tee-verify` checks a running enclave's attestation against. Point it at the policy with `-policy-url`, or pass each as the flag of the same meaning.
      type: object
      required:
        - sourceUri
        - imageRepo
        - signerKeyIds
        - minRelease
        - readingsUrl
        - invokers
        - captureBucket
        - requestSeal
        - projectIds
        - imageRefPrefixes
      properties:
        sourceUri:
          description: The repository the image's SLSA provenance must name (`-source-uri`).
          type: string
        imageRepo:
          description: The public registry that holds the digest with its provenance (`-image-repo`).
          type: string
        signerKeyIds:
          description: Accepted image signing keys (`-signer-key-ids`).
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{64}$
        minRelease:
          description: The oldest release accepted (`-min-release`).
          type:
            - string
            - "null"
        readingsUrl:
          description: Where the enclave must post its readings, its attested `TRAINER_URL` (`-trainer-url`).
          type: string
          format: uri
        invokers:
          description: Exactly the identities the enclave's control routes may take a token from, its attested `TRAINER_INVOKER_SERVICE_ACCOUNT` (`-trainer-invoker`).
          type: array
          items:
            type: string
        captureBucket:
          description: The one bucket the enclave may write a session record to, its attested `TEE_CAPTURE_BUCKET` (`-capture-bucket`); empty for an enclave that keeps none. A lease names a record only when it asks for one, and orgasm.dev's never do.
          type: string
        requestSeal:
          description: The sealing scheme requests must use, its attested `TEE_REQUEST_SEAL` (`-request-seal`).
          type: string
        projectIds:
          description: The Google Cloud projects the enclave may run in (`-project-id`).
          type: array
          items:
            type: string
        imageRefPrefixes:
          description: Where the enclave's image may have been pulled from (`-image-ref-prefix`).
          type: array
          items:
            type: string
    EnclaveReceipt:
      title: EnclaveReceipt
      description: What a live session's enclave attested, after orgasm.dev held it to the attestation policy. Everything here comes from the token, which you can verify on your own against Google's keys.
      type: object
      required:
        - imageDigest
        - release
        - commit
        - releaseUrl
        - signers
        - hardware
        - debugging
        - confidentialSpace
        - projectId
        - zone
        - instanceId
        - tlsBound
        - attestedAt
        - verifiedAt
        - attestationToken
      properties:
        imageDigest:
          description: The digest of the image the enclave runs.
          type: string
          pattern: ^sha256:[0-9a-f]{64}$
        release:
          description: The release the image is stamped with (`TEE_IMAGE_VERSION`).
          type:
            - string
            - "null"
        commit:
          description: The source commit the image is stamped with (`TEE_IMAGE_COMMIT`).
          type:
            - string
            - "null"
        releaseUrl:
          description: The release's page, with its digest and the commands that check its SLSA provenance and signature.
          type:
            - string
            - "null"
          format: uri
        signers:
          description: The keys the launcher verified the image's signature with.
          type: array
          items:
            type: string
        hardware:
          type: object
          required:
            - cpu
            - gpus
            - gpuConfidentialComputing
            - secureBoot
          properties:
            cpu:
              description: The attested platform, `GCP_INTEL_TDX`.
              type: string
            gpus:
              description: The attested GPUs, `GCP_NVIDIA_H100`.
              type: array
              items:
                type: string
            gpuConfidentialComputing:
              type: boolean
            secureBoot:
              type: boolean
        debugging:
          description: The machine image's debug status, `disabled-since-boot` in live mode.
          type: string
        confidentialSpace:
          description: The Confidential Space image's support attributes, `STABLE` among them.
          type: array
          items:
            type: string
        projectId:
          description: The Google Cloud project the enclave runs in.
          type:
            - string
            - "null"
        zone:
          type:
            - string
            - "null"
        instanceId:
          type: string
        tlsBound:
          description: "The TLS connection orgasm.dev made to the enclave ended inside it: the token names that connection's key."
          type: boolean
        attestedAt:
          description: When Google's attestation service signed the token.
          type: string
          format: date-time
        verifiedAt:
          description: When orgasm.dev checked it.
          type: string
          format: date-time
        attestationToken:
          description: The token, as Google's Confidential Space attestation service signed it, with this session's id among its nonces. Verify its RS256 signature against https://www.googleapis.com/service_accounts/v1/metadata/jwk/signer@confidentialspace-sign.iam.gserviceaccount.com.
          type: string
    Deleted:
      title: Deleted
      description: Confirms a deletion.
      type: object
      required:
        - id
        - object
        - deleted
      properties:
        id:
          type: string
        object:
          type: string
        deleted:
          type: boolean
          const: true
  examples:
    ViewTokenCreated:
      summary: A view token for a stream overlay
      value:
        object: view_token
        token: vt_k3m9q2w7e1r5t8y4u0i6o3p9a2s5d8f1
        sessionId: ls_8f3kq2m7x9w4c1n6t5ra
        eventTypes:
          - imminence.updated
          - signals.updated
          - stimulation.updated
          - orgasm.onset
          - orgasm.peak
          - orgasm.end
          - edge.completed
          - session.status
          - input.warning
        face: false
        createdAt: 2026-10-16T14:00:00Z
        expiresAt: 2026-10-16T17:00:00Z
    LiveSessionStarting:
      summary: A sandbox session just created
      description: Returned by createLiveSession in the sandbox.
      value:
        id: ls_8f3kq2m7x9w4c1n6t5ra
        object: live_session
        mode: test
        status: starting
        degraded: false
        inputs:
          face:
            present: false
            baselineReady: false
          audio:
            declared: true
            present: false
          body:
            declared: false
            present: false
        signals:
          - imminence.updated
          - signals.updated
          - subject.identified
          - edge.completed
          - orgasm.onset
          - orgasm.peak
          - orgasm.end
        subject: null
        latestImminence: null
        ingest:
          protocol: whip
          url: https://orgasm.dev/v1/sandbox/whip/ls_8f3kq2m7x9w4c1n6t5ra
          bodyUrl: null
          attestationUrl: https://orgasm.dev/v1/attestation-policy?mode=test
          seal: v1
          iceServersUrl: https://orgasm.dev/v1/sandbox/ice/ls_8f3kq2m7x9w4c1n6t5ra
          expiresAt: 2026-10-16T14:15:00Z
          video:
            codecs:
              - H264
              - H265
            maxLongEdgePx: 1280
            recommendedFps: 30
          audio:
            codecs:
              - opus
            expected: true
        enclave: null
        charges:
          orgasms: 0
          ruins: 0
          edges: 0
          sessionMinimum: false
          credits: 0
        results:
          streamUrl: https://orgasm.dev/v1/live-sessions/ls_8f3kq2m7x9w4c1n6t5ra/stream
          websocketUrl: wss://orgasm.dev/v1/live-sessions/ls_8f3kq2m7x9w4c1n6t5ra/ws
          eventsUrl: https://orgasm.dev/v1/live-sessions/ls_8f3kq2m7x9w4c1n6t5ra/events
          clientToken: ct_q8w1e4r7t0y3u6i9o2p5a8s1d4f7g0h3
          clientTokenExpiresAt: 2026-10-16T15:00:00Z
        subjectHint: null
        maxDurationS: 3600
        retentionDays: 30
        webhookEndpointId: null
        userReference: 9f2c41ab7e05d3a86b1c
        clientReferenceId: round_1842
        metadata:
          plan: premium
        sandbox:
          scenario: woman-onset-end
          speed: 10
        createdAt: 2026-10-16T14:00:00Z
        startedAt: null
        endedAt: null
        endedReason: null
        resultsExpireAt: null
    LiveSessionAnalyzing:
      summary: A sandbox session nine minutes in
      description: Returned by getLiveSession once the scenario is past its onset.
      value:
        id: ls_8f3kq2m7x9w4c1n6t5ra
        object: live_session
        mode: test
        status: analyzing
        degraded: false
        inputs:
          face:
            present: true
            baselineReady: true
          audio:
            declared: true
            present: true
          body:
            declared: false
            present: false
        signals:
          - imminence.updated
          - signals.updated
          - subject.identified
          - edge.completed
          - orgasm.onset
          - orgasm.peak
          - orgasm.end
        subject:
          sex: woman
          pWoman: 0.94
          secondsObserved: 30
          decidedAtS: 32
          hint: null
          detectors:
            - onset_end
        latestImminence:
          p30: 0.868
          p60: 0.983
          streamTimeS: 542
          eventId: evt_1ayxm16hy930duw499dv
        ingest:
          protocol: whip
          url: https://orgasm.dev/v1/sandbox/whip/ls_8f3kq2m7x9w4c1n6t5ra
          bodyUrl: null
          attestationUrl: https://orgasm.dev/v1/attestation-policy?mode=test
          seal: v1
          iceServersUrl: https://orgasm.dev/v1/sandbox/ice/ls_8f3kq2m7x9w4c1n6t5ra
          expiresAt: 2026-10-16T14:15:00Z
          video:
            codecs:
              - H264
              - H265
            maxLongEdgePx: 1280
            recommendedFps: 30
          audio:
            codecs:
              - opus
            expected: true
        enclave: null
        charges:
          orgasms: 1
          ruins: 0
          edges: 0
          sessionMinimum: false
          credits: 0
        results:
          streamUrl: https://orgasm.dev/v1/live-sessions/ls_8f3kq2m7x9w4c1n6t5ra/stream
          websocketUrl: wss://orgasm.dev/v1/live-sessions/ls_8f3kq2m7x9w4c1n6t5ra/ws
          eventsUrl: https://orgasm.dev/v1/live-sessions/ls_8f3kq2m7x9w4c1n6t5ra/events
          clientToken: ct_q8w1e4r7t0y3u6i9o2p5a8s1d4f7g0h3
          clientTokenExpiresAt: 2026-10-16T15:00:00Z
        subjectHint: null
        maxDurationS: 3600
        retentionDays: 30
        webhookEndpointId: null
        userReference: 9f2c41ab7e05d3a86b1c
        clientReferenceId: round_1842
        metadata:
          plan: premium
        sandbox:
          scenario: woman-onset-end
          speed: 10
        createdAt: 2026-10-16T14:00:00Z
        startedAt: 2026-10-16T14:00:00.2Z
        endedAt: null
        endedReason: null
        resultsExpireAt: null
    EventListOnset:
      summary: The onset call, after the imminence update before it
      description: Returned by listLiveSessionEvents around an onset call.
      value:
        object: list
        data:
          - id: evt_1ayxm16hy930duw499dv
            object: event
            type: imminence.updated
            mode: test
            sessionId: ls_8f3kq2m7x9w4c1n6t5ra
            sequence: 967
            streamTimeS: 542
            confidence: high
            data:
              p30: 0.868
              p60: 0.983
              logit30: 1.89
              logit60: 4.04
              featuresPresent: 0.95
              faceVisible: true
              baselineReady: true
              stimulationAware: false
              recentCalls: []
            wallTime: 2026-10-16T14:00:55.200Z
          - id: evt_2099smltv0t2c2wzzyzq
            object: event
            type: orgasm.onset
            mode: test
            sessionId: ls_8f3kq2m7x9w4c1n6t5ra
            sequence: 969
            streamTimeS: 542.6
            confidence: high
            data:
              orgasmIndex: 1
              eventAtS: 538
              calledAtS: 542.6
              lagS: 4.6
              detector: onset_end
              score: 0.71
              threshold: 0.5
            wallTime: 2026-10-16T14:00:55.260Z
        hasMore: false
        nextCursor: evt_2099smltv0t2c2wzzyzq
    RecordingAwaitingUpload:
      summary: A sandbox recording waiting for its file
      description: Returned by submitRecording for an upload.
      value:
        id: rec_2n5v8c1x4m7q0w3e6r9t
        object: recording
        mode: test
        status: awaiting_upload
        source:
          type: upload
        uploads:
          face:
            url: https://orgasm.dev/v1/sandbox/uploads/up_6b9n2m5k8j1h4g7f0d3s6a9q
            method: PUT
            headers:
              Content-Type: video/mp4
            maxBytes: 5368709120
            expiresAt: 2026-10-16T15:00:00Z
            sealed: false
          body: null
        inputs:
          audio: true
          body: false
        progress: null
        result: null
        failure: null
        subjectHint: null
        retentionDays: 30
        webhookEndpointId: null
        userReference: null
        clientReferenceId: null
        metadata: {}
        sandbox:
          scenario: man-peak
          speed: 60
        createdAt: 2026-10-16T14:00:00Z
        startedAt: null
        completedAt: null
        resultsExpireAt: null
    RecordingCompleted:
      summary: A sandbox recording after processing
      description: Returned by getRecording after processing.
      value:
        id: rec_2n5v8c1x4m7q0w3e6r9t
        object: recording
        mode: test
        status: completed
        source:
          type: upload
        uploads: null
        inputs:
          audio: true
          body: false
        progress: null
        result:
          subject: &a5
            sex: man
            pWoman: 0.07
            secondsObserved: 30
            decidedAtS: 31
            hint: null
            detectors:
              - peak
              - face_end
          summary:
            durationS: 780
            orgasmCount: 1
            orgasms:
              - orgasmIndex: 1
                detectors:
                  - peak
                  - face_end
                onsetAtS: null
                peakAtS: 701
                endAtS: 742
                durationS: 41
                confidence: high
          timeline:
            - id: evt_2aq0wyoeyck0k8yhwknk
              object: event
              type: subject.identified
              mode: test
              recordingId: rec_2n5v8c1x4m7q0w3e6r9t
              sequence: 1
              streamTimeS: 31
              confidence: high
              data: *a5
              wallTime: 2026-10-16T14:00:20.517Z
            - id: evt_1m1ugxow8zk03ybhqpq6
              object: event
              type: orgasm.peak
              mode: test
              recordingId: rec_2n5v8c1x4m7q0w3e6r9t
              sequence: 645
              streamTimeS: 704.2
              confidence: high
              data:
                orgasmIndex: 1
                eventAtS: 701
                calledAtS: 704.2
                lagS: 3.2
                detector: peak
                score: 0.66
                threshold: 0.5
              wallTime: 2026-10-16T14:00:31.737Z
            - id: evt_2ecvtv7npvg2760yypya
              object: event
              type: orgasm.end
              mode: test
              recordingId: rec_2n5v8c1x4m7q0w3e6r9t
              sequence: 687
              streamTimeS: 745.5
              confidence: high
              data:
                orgasmIndex: 1
                eventAtS: 742
                startedAtS: 701
                durationS: 41
                calledAtS: 745.5
                lagS: 3.5
                detector: face_end
                score: null
                threshold: null
                ruined: false
              wallTime: 2026-10-16T14:00:32.425Z
        failure: null
        subjectHint: null
        retentionDays: 30
        webhookEndpointId: null
        userReference: null
        clientReferenceId: null
        metadata: {}
        sandbox:
          scenario: man-peak
          speed: 60
        createdAt: 2026-10-16T14:00:00Z
        startedAt: 2026-10-16T14:00:20Z
        completedAt: 2026-10-16T14:13:20Z
        resultsExpireAt: 2026-11-15T14:13:20Z
    WebhookEndpointCreated:
      summary: A new endpoint and its secret
      description: Returned by createWebhookEndpoint.
      value:
        id: we_5h8j1k4l7z0x3c6v9b2n
        object: webhook_endpoint
        mode: test
        url: https://api.example.com/hooks/orgasm-dev
        events:
          - orgasm.onset
          - orgasm.peak
          - orgasm.end
          - subject.identified
          - session.status
        description: Production receiver
        enabled: true
        secret: whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
        previousSecretExpiresAt: null
        createdAt: 2026-10-16T14:00:00Z
    WebhookEndpointSecretRolled:
      summary: An endpoint with a new secret, the old one valid for a day
      description: Returned by rollWebhookSecret.
      value:
        id: we_5h8j1k4l7z0x3c6v9b2n
        object: webhook_endpoint
        mode: live
        url: https://api.example.com/hooks/orgasm-dev
        events:
          - orgasm.onset
          - orgasm.peak
          - orgasm.end
          - subject.identified
          - session.status
        description: Production receiver
        enabled: true
        secret: whsec_Tq2Lr8bWn4Zc6Ve1Xk9Hs3Pd7Fy5Jm0A
        previousSecretExpiresAt: 2026-10-22T09:30:00Z
        createdAt: 2026-10-16T14:00:00Z
    LiveSessionsPurged:
      summary: A person's two sessions, purged
      description: Returned by purgeLiveSessionsByUserReference.
      value:
        object: live_session_purge
        userReference: 9f2c41ab7e05d3a86b1c
        deleted: 2
        ids:
          - ls_8f3kq2m7x9w4c1n6t5ra
          - ls_2w5e8r1t4y7u0i3o6p9a
    ChargeListOne:
      summary: A live session's orgasm, drawn from a Growth package
      description: Returned by listCharges with a live key.
      value:
        object: list
        data:
          - id: ls_8f3kq2m7x9w4c1n6t5ra.orgasm.1
            object: charge
            mode: live
            sessionId: ls_8f3kq2m7x9w4c1n6t5ra
            unit: orgasm
            index: 1
            at: 2026-10-21T14:09:02Z
            credits: 1
            freeCredits: 0
            paidCredits: 1
            pendingCredits: 0
            amountUsd: 4
            packages:
              - id: pkg_4n7q2w9e5r1t8y3u6i0o
                credits: 1
                pricePerCredit: 4
            returned: false
            ownGpu: false
            apiKeyId: key_9d2f5g8h1j4k7l0z3x6c
            userReference: 9f2c41ab7e05d3a86b1c
            clientReferenceId: round_1842
            metadata:
              plan: premium
        totals:
          charges: 1
          credits: 1
          freeCredits: 0
          paidCredits: 1
          pendingCredits: 0
          amountUsd: 4
        hasMore: false
        nextCursor: null
    UsageThreeDays:
      summary: Sandbox usage over three days
      description: Returned by getUsage.
      value:
        object: usage
        mode: test
        from: 2026-10-14
        to: 2026-10-16
        days:
          - date: 2026-10-14
            liveSessions: 3
            liveSeconds: 1980
            recordings: 1
            recordingSeconds: 780
            orgasms: 2
            ruins: 0
            edges: 3
            sessionMinimums: 0
            credits: 0
          - date: 2026-10-15
            liveSessions: 0
            liveSeconds: 0
            recordings: 0
            recordingSeconds: 0
            orgasms: 0
            ruins: 0
            edges: 0
            sessionMinimums: 0
            credits: 0
          - date: 2026-10-16
            liveSessions: 5
            liveSeconds: 3420
            recordings: 2
            recordingSeconds: 1440
            orgasms: 3
            ruins: 1
            edges: 2
            sessionMinimums: 1
            credits: 0
        totals:
          liveSessions: 8
          liveSeconds: 5400
          recordings: 3
          recordingSeconds: 2220
          orgasms: 5
          ruins: 1
          edges: 5
          sessionMinimums: 1
          credits: 0
    CreditsGrowth:
      summary: A company on a Growth package, with free credits used up
      description: Returned by getCredits.
      value:
        object: credit_balance
        domain: studio.example
        balance: 9412.5
        free:
          granted: 20
          remaining: 0
        packages:
          - id: pkg_4n7q2w9e5r1t8y3u6i0o
            object: credit_package
            package: growth
            credits: 10000
            remaining: 9412.5
            pricePerCredit: 4
            postedAt: 2026-10-20T17:04:00Z
            expiresAt: 2027-10-20T17:04:00Z
          - id: free
            object: credit_package
            package: free
            credits: 20
            remaining: 0
            pricePerCredit: 0
            postedAt: 2026-10-16T14:00:00Z
            expiresAt: null
        expiringSoon: null
        enforced: true
    ApiKeyCreated:
      summary: A new test key and its secret
      description: Returned by createApiKey.
      value:
        id: key_9d2f5g8h1j4k7l0z3x6c
        object: api_key
        name: Staging server
        mode: test
        type: secret
        redacted: sk_test_…7qk2
        secret: sk_test_51nfx8kq2mzp4lr7wv9ty3bc6hd1jg0ae5qk7qk2
        createdBy: null
        createdAt: 2026-10-16T14:00:00Z
        lastUsedAt: null
        expiresAt: null
    ApiKeyRolled:
      summary: The replacement for a key rolled with a day's grace
      description: Returned by rollApiKey.
      value:
        id: key_3v6b9n2m5k8j1h4g7f0d
        object: api_key
        name: Staging server
        mode: test
        type: secret
        redacted: sk_test_…w3p8
        secret: sk_test_7hc2kq9mzd4lr1wv8ty5bn3gf6jx0ae2pw3p8
        createdBy: null
        createdAt: 2026-10-21T09:30:00Z
        lastUsedAt: null
        expiresAt: null
    ApiKeyListOne:
      summary: One key
      description: Returned by listApiKeys.
      value:
        object: list
        data:
          - id: key_9d2f5g8h1j4k7l0z3x6c
            object: api_key
            name: Staging server
            mode: test
            type: secret
            redacted: sk_test_…7qk2
            secret: null
            createdBy: dev@studio.example
            createdAt: 2026-10-16T14:00:00Z
            lastUsedAt: 2026-10-16T14:05:12Z
            expiresAt: null
        hasMore: false
        nextCursor: null
