# orgasm.dev

> Know when your users orgasm, with live updates as they get close: the orgasm API for games, sex toys, AI companions, creators and adult entertainment. Live camera streams and recorded videos go in as two separate endpoints; events about imminence, onset, peak and end come back over server-sent events, a WebSocket, webhooks and event lists. The sandbox is open to any key that starts with `sk_test_`, with no account; live sessions take a `sk_live_` key from the developer's dashboard, after signing up at https://orgasm.dev/signup, and recorded videos are analysed in the sandbox only for now.

Everything an agent needs to integrate, in machine-readable form:

- OpenAPI 3.1 (REST): https://orgasm.dev/openapi.json
- AsyncAPI 3.1 (events): https://orgasm.dev/asyncapi.json
- Action MCP server (tools that call the API with your key): https://orgasm.dev/mcp
- Docs MCP server (list, search and read these docs): https://orgasm.dev/api/mcp
- Every page as Markdown: append `.md` to a docs URL, or send `Accept: text/markdown`
- API catalog (RFC 9727): https://orgasm.dev/.well-known/api-catalog


---

# For AI agents (https://orgasm.dev/docs/agents)

orgasm.dev is written to be integrated by an agent. There are two kinds:

- **Integration-time agents** write the integration: they read the docs and the contracts, call the sandbox while they work, and write tests.
- **Runtime agents** run inside a product and act on a person's session as it happens, through the action MCP server.

## The prompt [#the-prompt]

Paste this into your coding agent from your project:

```text
Integrate orgasm.dev into this project.

Read https://orgasm.dev/llms.txt first, then the pages it links that apply. The REST contract is https://orgasm.dev/openapi.json and the events are https://orgasm.dev/asyncapi.json. To call the API while you work, connect the MCP server at https://orgasm.dev/mcp with a test key (any key that starts with sk_test_ reaches the sandbox).

Inspect this project's language, framework and where it uses the camera, then choose:
- live sessions (POST /v1/live-sessions) for a camera stream, or recordings (POST /v1/recordings) for video files;
- server-sent events, the WebSocket or webhooks for the results.

Keep the secret key on the server. Have the end user's device generate the capability and publish its front camera and microphone itself; pass only the capability's SHA-256 and the client token across. Set consent only where this product verifies that the person on camera is an adult and has agreed to the analysis; ask me how it does that if you cannot find it.

If the product has user accounts, set userReference on each live session to a pseudonymous id for the person: an HMAC of their user id under a key of this product's own, never their email, phone or name. Set clientReferenceId to this product's own id for the session. Our finance team then sees what each user and session cost.

Treat imminence as a probability over 30 and 60 seconds, not a countdown, and orgasm calls as arriving a few seconds after the moment they name. If the product changes stimulation, report it with reportStimulation. If it implements edge, ruin or finish, start from the reference presets at https://orgasm.dev/docs/concepts/presets, and keep a stop control that works whatever the signals say.

Write tests against the sandbox scenarios (sandbox.scenario, sandbox.speed). Then tell me what you built, how to run it, and what remains before live keys.
```

## Connect your agent [#connect-your-agent]

Give your agent both MCP servers: the docs server needs no key, and the action server takes a test key, so every call it makes reaches the sandbox. Any key that starts with `sk_test_` works; put it in `ORGASM_KEY` first:

```bash
export ORGASM_KEY=sk_test_your_own_suffix
```

<Tabs items={['Cursor', 'Claude Code', 'Codex']}>
<Tab value="Cursor">

Open each link to install the server in Cursor, which asks before it does: [orgasm.dev actions](cursor://anysphere.cursor-deeplink/mcp/install?name=orgasm&config=eyJ1cmwiOiJodHRwczovL29yZ2FzbS5kZXYvbWNwIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyICR7ZW52Ok9SR0FTTV9LRVl9In19) and [orgasm.dev docs](cursor://anysphere.cursor-deeplink/mcp/install?name=orgasm-docs&config=eyJ1cmwiOiJodHRwczovL29yZ2FzbS5kZXYvYXBpL21jcCJ9). Or add them to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project:

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "orgasm": {
      "url": "https://orgasm.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:ORGASM_KEY}" }
    },
    "orgasm-docs": { "url": "https://orgasm.dev/api/mcp" }
  }
}
```

</Tab>
<Tab value="Claude Code">

Run these in your terminal, not inside a session. Add `--scope user` to use them in every project:

```bash
claude mcp add --transport http orgasm https://orgasm.dev/mcp \
  --header "Authorization: Bearer $ORGASM_KEY"
claude mcp add --transport http orgasm-docs https://orgasm.dev/api/mcp
```

Check both with `/mcp` in a session: each shows a check mark once connected.

</Tab>
<Tab value="Codex">

Codex reads the key from `ORGASM_KEY` each time it starts, so the key stays out of its configuration:

```bash
codex mcp add orgasm --url https://orgasm.dev/mcp --bearer-token-env-var ORGASM_KEY
codex mcp add orgasm-docs --url https://orgasm.dev/api/mcp
```

Or add them to `~/.codex/config.toml`:

```toml title="~/.codex/config.toml"
[mcp_servers.orgasm]
url = "https://orgasm.dev/mcp"
bearer_token_env_var = "ORGASM_KEY"

[mcp_servers.orgasm-docs]
url = "https://orgasm.dev/api/mcp"
```

</Tab>
</Tabs>

Live keys belong on your server, never in an agent's configuration. Get one from your dashboard once you [sign up](/signup).

## Contracts [#contracts]

The two documents are the source of truth; everything on this site is generated from them.

| Document | What it describes |
| --- | --- |
| [`/openapi.json`](/openapi.json) ([YAML](/openapi.yaml)) | OpenAPI 3.1: every REST operation, its parameters, bodies, responses and errors. Each `operationId` is also an MCP tool name. |
| [`/asyncapi.json`](/asyncapi.json) ([YAML](/asyncapi.yaml)) | AsyncAPI 3.1: the events, on the stream, the socket and webhooks, with examples the sandbox actually sends. |
| [`/.well-known/api-catalog`](/.well-known/api-catalog) | RFC 9727 linkset pointing at both documents and the docs. |
| [`/.well-known/mcp.json`](/.well-known/mcp.json) | Both MCP servers, how to connect, and their tools. |

Generate a client with any OpenAPI generator. Errors are RFC 9457 problem details whose `type` links to an explanation of their `code` ([errors](/docs/guides/errors)).

## Docs as Markdown [#docs-as-markdown]

| URL | Contents |
| --- | --- |
| [`/llms.txt`](/llms.txt) | An index of every page, one line each. |
| [`/llms-full.txt`](/llms-full.txt) | Every guide, then the REST reference and the events reference, in one file. |
| `/docs/<page>.md` | One page as Markdown. Charts and tables on a page become Markdown tables. |
| `Accept: text/markdown` | Any docs URL, and `/`, answers in Markdown when asked (with `Vary: Accept`). |

## Docs MCP server [#docs-mcp-server]

Lists, searches and reads these docs. No key.

```json title="mcp.json"
{
  "mcpServers": {
    "orgasm-docs": { "url": "https://orgasm.dev/api/mcp" }
  }
}
```

Tools: `list_pages`, `get_page` (by URL) and `search`.

## Action MCP server [#action-mcp-server]

Calls the API with your key: one tool per operation, plus two helpers. With a test key every call reaches the sandbox, so an agent can run an integration end to end.

```json title="mcp.json"
{
  "mcpServers": {
    "orgasm": {
      "url": "https://orgasm.dev/mcp",
      "headers": { "Authorization": "Bearer sk_test_your_own_suffix" }
    }
  }
}
```

| tool | calls | does |
| --- | --- | --- |
| `list_live_sessions` | GET /v1/live-sessions | Lists your company's live sessions, newest first. |
| `create_live_session` | POST /v1/live-sessions | Starts analysis capacity for one person's live camera stream and returns where their device publishes (`ingest`) and where events arrive (`results`). |
| `purge_live_sessions_by_user_reference` | POST /v1/live-sessions/purge | 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. |
| `get_live_session` | GET /v1/live-sessions/{sessionId} | Returns the session's status, which inputs are arriving, the subject read once it is made, and the latest imminence (`latestImminence`). |
| `end_live_session` | DELETE /v1/live-sessions/{sessionId} | 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. |
| `purge_live_session` | POST /v1/live-sessions/{sessionId}/purge | 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. |
| `list_live_session_events` | GET /v1/live-sessions/{sessionId}/events | Returns the session's events in order, oldest first. |
| `create_view_token` | POST /v1/live-sessions/{sessionId}/view-tokens | 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. |
| `report_stimulation` | POST /v1/live-sessions/{sessionId}/stimulation | Tells the analysis when stimulation starts, stops or changes, if your product controls it (a device, an e-stim unit, a scene). |
| `list_recordings` | GET /v1/recordings | Lists your company's recordings, newest first. |
| `submit_recording` | POST /v1/recordings | Submits a recorded video for analysis. |
| `get_recording` | GET /v1/recordings/{recordingId} | 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. |
| `delete_recording` | DELETE /v1/recordings/{recordingId} | Deletes the recording's results and events now and stops processing if it is still running. |
| `list_recording_events` | GET /v1/recordings/{recordingId}/events | Returns the recording's full event timeline in order, including `imminence.updated` for every second of analysed face. |
| `list_webhook_endpoints` | GET /v1/webhook-endpoints | Lists your company's webhook endpoints for the key's mode, newest first, without their secrets. |
| `create_webhook_endpoint` | POST /v1/webhook-endpoints | Registers an HTTPS URL on your server to receive events as POSTs, signed per the Standard Webhooks specification (`webhook-id`, `webhook-timestamp`, `webhook-signature`). |
| `get_webhook_endpoint` | GET /v1/webhook-endpoints/{webhookEndpointId} | Returns one webhook endpoint and the event types it receives, without its secret. |
| `update_webhook_endpoint` | PATCH /v1/webhook-endpoints/{webhookEndpointId} | Changes an endpoint's URL, the event types it receives, its description, or whether it is enabled. |
| `delete_webhook_endpoint` | DELETE /v1/webhook-endpoints/{webhookEndpointId} | Stops all deliveries to the endpoint, including retries in flight. |
| `roll_webhook_secret` | POST /v1/webhook-endpoints/{webhookEndpointId}/roll-secret | Replaces the endpoint's signing secret and returns the new one, once. |
| `send_test_webhook` | POST /v1/webhook-endpoints/{webhookEndpointId}/test | Sends one signed sample event of the given type to the endpoint now and reports how your server answered. |
| `get_usage` | GET /v1/usage | 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). |
| `get_credits` | GET /v1/credits | 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. |
| `list_charges` | GET /v1/charges | 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. |
| `list_models` | GET /v1/models | The models behind each signal: what each produces, which inputs it needs, who it applies to, and where it is available. |
| `get_attestation_policy` | GET /v1/attestation-policy | 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. |
| `wait_for_event` | helper | Waits until a live session or a recording has an event of one of the given types after `after`, for up to `timeoutS` seconds, and returns the matching events with the cursor to continue from. |
| `get_latest_imminence` | helper | Returns a live session’s newest imminence (p30 and p60, the probability that the next orgasm begins within 30 and 60 seconds), with the session status, the subject read and the last orgasm calls. |

`wait_for_event` follows a session without a stream client: call it in a loop, passing back `nextCursor` as `after`. `get_latest_imminence` answers "how close is it now" in one call, with the session status, the subject read and the last calls.

API-key management is deliberately not exposed as tools.

## Rules for runtime agents [#rules-for-runtime-agents]

A runtime agent acts on a person in an intimate moment. Build these in:

- Never set `consent` on someone's behalf. Only set it when the product has verified the person's age and recorded their agreement.
- Treat imminence as a probability over a horizon, never as a countdown, and orgasm calls as a few seconds late.
- Never raise intensity, or take any irreversible action, on a single signal. Prefer cues from a [preset](/docs/concepts/presets), with hysteresis.
- Stop when the person says stop, whatever the signals say, and end the session when the experience ends (`end_live_session`).
- When someone asks for their data to be deleted, call `purge_live_session` or `delete_recording`.


---

# Acceptable use (https://orgasm.dev/docs/concepts/compliance)

orgasm.dev measures something intimate about a person. Using it is conditional on the following. Breaking them ends sessions and revokes keys.

These rules take effect on October 20, 2026. You accept them when you [set up your account](/signup), and again whenever they change.

## Adults only [#adults-only]

Every person on camera is 18 or older, or older where their local law requires, and you have verified it. A self-declared birthday is not verification. Say how you verified in `consent.ageVerification`.

If there is any reason to think a person on camera might be a minor, do not send the video. Never build for, market to, or allow use by minors.

## Consent [#consent]

The person on camera has agreed to this analysis, explicitly and specifically, before it starts:

- They know what is measured (how close they are to orgasm; its onset, peak and end; how their face reads; and in a live session their vocalizations and loudness, their contractions and movement where a body view is sent, and how each region of their face moves), who receives it, and how long it is kept.
- They know which screens show it, and agreed to each: their own device, and any screen others watch, such as a partner's, a coach's or a stream. A screen that draws their face's movement, on a generic face, does so only if they agreed to that too; view tokens leave the face's channels out unless made with `includeFace`, and a creator's overlay leaves the face off unless they turn it on.
- They can stop it at any moment, with a control that is always on screen.
- They see when analysis is running.
- Consent to one experience is not consent to another, and it can be withdrawn.

On the person's device, [the HUD](/docs/guides/hud) shows both the indicator and the Stop control in every layout but `overlay`, which, like the `stream` attribute, is for screens other people watch. When the person presses Stop, ending the session is yours to do.

Every request that starts an analysis attests it: `consent.subjectIsAdult` and `consent.subjectConsented` must both be `true`, or the request is refused with `consent_required`. Set them only when your product has done both; keep the record your `consentRecordId` refers to.

## Recordings [#recordings]

Submit only recordings of people who agreed to this analysis of that recording. Never analyse videos of other people, scraped or downloaded content, or performers' work without each performer's explicit agreement.

## Never [#never]

- Analyse anyone who does not know, or who cannot freely refuse.
- Use orgasm.dev to identify, track or monitor people.
- Store or use the subject read as a person's sex or gender, or for anything but choosing detectors.
- Treat a call as proof about a person, or attach consequences to one that the person has not agreed to.
- Use the events in decisions about employment, insurance, credit, housing, education, immigration or legal proceedings.
- Present the events as a medical diagnosis or treatment.
- Sell the events, or share them beyond what the person agreed to.

## Your data obligations [#your-data-obligations]

The events, and the video they come from, are special-category data in many places: data about a person's sex life and, for the face, biometric data. Depending on where you and the person are, laws such as the GDPR and UK GDPR (Article 9: explicit consent), Illinois's BIPA (a written release before collecting face geometry, and a published retention schedule), Texas's CUBI, Washington's My Health My Data Act and the CCPA's rules for sensitive personal information may apply. You are responsible for meeting them: a lawful basis, a privacy notice, a data protection impact assessment where required. This page is not legal advice.

Your notice must tell the people on camera that orgasm.dev processes their sessions for you, and that it may keep de-identified, aggregated statistics from them to improve its detectors. The [Privacy Policy](/privacy) describes both, and what orgasm.dev does with your own account.

## Retention and deletion [#retention-and-deletion]

- **Video** is never stored. Live media exists only inside the enclave during analysis; a recording is deleted once analysed.
- **Events** stay readable for `retentionDays` after a session ends or a recording completes (30 by default, up to 90). With `0`, nothing is kept: events are only delivered as they happen.
- **Cost attribution.** A session's `userReference`, `clientReferenceId` and `metadata` stay with its charges for 13 months, so your finance team can see what it cost, and are then erased. The charges stay, without them.
- **On request**, delete a person's data at once: `purgeLiveSessionsByUserReference` for every live session with their `userReference`, `purgeLiveSession` for one session, `deleteRecording` for a recording. A purge erases the session's references and metadata along with its events; its charges stay, as what your company was billed. Webhook deliveries already made are in your systems; delete them there.

A `userReference` must be an id that only you can link to the person, never their email address, phone number or name, so orgasm.dev never learns who they are ([cost attribution](/docs/credits#cost-attribution)).

## Reporting misuse [#reporting-misuse]

If you believe orgasm.dev is being used on someone without their consent, or on a minor, write to legal@orgasm.dev.


---

# Inputs (https://orgasm.dev/docs/concepts/inputs)

## What each input unlocks [#what-each-input-unlocks]

| Inputs | Imminence | Subject read | Onset and end (women) | Peak (men) | End (men) |
| --- | --- | --- | --- | --- | --- |
| Face | Yes | Yes | No | No | No |
| Face and microphone | Yes | Yes | Yes | Yes | Yes |
| Face, microphone and body view | Yes | Yes | Yes, corroborated | Yes, corroborated | Yes |

Declare what the device will publish when you create the session (`inputs.audio`, `inputs.body`); the session's `signals` then lists the events it can produce.

## Face (required) [#face-required]

The front camera, with the person's face in view and only that person in frame.

- H.264 or H.265 video. Frames are scaled to a long edge of 1280 pixels; 30 frames a second is ideal.
- Even, frontal light. The analysis corrects for a turned or tilted head, but not for a face in shadow or out of frame.
- The first minute of visible face is the person's resting baseline. Imminence starts once it is in (`baseline_pending` until then); the subject read is made after the first 30 seconds.

## Microphone (recommended) [#microphone-recommended]

Publish the microphone with the camera. The onset, peak and end detectors read the voice as well as the face and do not run without it. Sound is measured inside the enclave (classes of vocalization, level, pitch); no audio leaves it. In a live session it also gives `signals.updated` its vocalizations and loudness.

Without the microphone you still get imminence and the subject read, and an `audio_absent` warning says why the calls are missing.

**Face only: no microphone** (sandbox scenario `face-only`). The device publishes the camera without the microphone: imminence and the subject read arrive, onset, peak and end cannot, and an audio warning says why. With no orgasm called, the approach that recedes counts as an edge.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.018 | 0.036 |
| 122 | 0.035 | 0.069 |
| 182 | 0.042 | 0.083 |
| 242 | 0.064 | 0.124 |
| 302 | 0.156 | 0.287 |
| 362 | 0.173 | 0.317 |
| 422 | 0.386 | 0.624 |
| 482 | 0.757 | 0.941 |
| 542 | 0.241 | 0.424 |

## Body view (optional) [#body-view-optional]

A second camera that sees the person's body, published to `ingest.bodyUrl` when the session declares `inputs.body: true`. It corroborates onset, peak and end calls, so more of them arrive with `confidence: high`. Calls are still made without it. In a live session it also gives `signals.updated` its contractions and movement.

## Stimulation (optional) [#stimulation-optional]

If your product controls stimulation, report when it starts, stops or changes with `reportStimulation`, or a `stimulation` message on the socket. Imminence from the face alone does not know how long the person has been stimulated; with reports, it does (`stimulationAware: true`). Report changes, not a heartbeat. A report can also carry the device's level, channels and mode, which every reader receives as `stimulation.updated` for its display ([reporting the device](/docs/guides/realtime#reporting-the-device)).

## When an input goes missing [#when-an-input-goes-missing]

- `input.warning` events are raised and cleared as conditions start and stop: `face_not_visible`, `multiple_faces`, `audio_absent`, `body_stream_absent`, `baseline_pending`, `low_confidence`. Each has a `message` you can show the person.
- The session's `degraded` flag is true while a declared input is missing or the face is out of view, and `session.status` events report the change.
- While the face is out of view, imminence is `null`. Treat `null` as "unknown", never as "low": hold rather than increase.

**Face lost for 20 seconds** (sandbox scenario `face-lost`). The face leaves the frame at five minutes: imminence goes null, a warning is raised and the session is degraded until the face returns 20 seconds later.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.019 | 0.038 |
| 122 | 0.032 | 0.062 |
| 182 | 0.044 | 0.086 |
| 242 | 0.067 | 0.13 |
| 302 | null | null |
| 362 | 0.161 | 0.296 |
| 422 | 0.301 | 0.512 |
| 482 | 0.518 | 0.767 |
| 542 | 0.512 | 0.761 |
| 602 | 0.081 | 0.156 |
| 662 | 0.034 | 0.067 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.onset` | orgasm 1 at 520 s, lag 4.8 s, score 0.69 |
| `orgasm.end` | orgasm 1 at 556 s, lasted 36 s, onset_end, lag 5.4 s |


---

# Edge, ruin and finish (https://orgasm.dev/docs/concepts/presets)

Edge, ruin and finish are policies: rules your product applies to imminence and to the orgasm calls to decide what to do next. orgasm.dev gives you the signals; the reference presets below turn them into **cues**, and what a cue does (lower an intensity, slow a scene, pause a level) is yours to decide. orgasm.dev does count what came of them, at the presets' own levels: each edge (`edge.completed`), each ruin (`ruined` on `orgasm.end`, from your stimulation reports) and each orgasm, which is what a live session is [charged for](/docs/credits).

| Cue | Means |
| --- | --- |
| `build` | Increase, or continue increasing |
| `hold` | Stop increasing; keep the current level |
| `back_off` | Reduce or pause, now |
| `resume` | Start building again after a rest |
| `sustain` | Keep going through the orgasm that has begun |
| `ease_off` | Wind down gently |
| `stop` | Stop stimulation now, and for good |

The thresholds are starting values to tune for each person and each experience, not calibrated operating points. The sandbox scenarios are scripted and do not react to cues; the charts show what the presets would do on them.

## Edge [#edge]

Approach the point of no return and back away, as often as the person wants. The preset holds once `p60` reaches 0.5, backs off once `p30` reaches 0.6, and resumes only after a minute's rest and once `p30` is below 0.3. It returns from holding to building only well below the hold level, so it does not flap. An onset or a peak means the edge was crossed; the preset stops. Each approach that reaches the back-off level and falls below the resume level with no orgasm is an edge, and orgasm.dev sends `edge.completed` for it.

**Edge: three approaches, no orgasm** (sandbox scenario `edge`). Imminence rises past the hold and back-off levels three times and falls each time stimulation is backed off, and the session ends without an orgasm: three edges, each an edge.completed.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.02 | 0.039 |
| 122 | 0.039 | 0.077 |
| 182 | 0.083 | 0.158 |
| 242 | 0.143 | 0.265 |
| 302 | 0.29 | 0.496 |
| 362 | 0.605 | 0.844 |
| 422 | 0.171 | 0.312 |
| 482 | 0.145 | 0.268 |
| 542 | 0.526 | 0.776 |
| 602 | 0.26 | 0.452 |
| 662 | 0.116 | 0.219 |
| 722 | 0.389 | 0.627 |
| 782 | 0.396 | 0.635 |
| 842 | 0.133 | 0.249 |

| at | cue | because |
| --- | --- | --- |
| 62 s | `build` | imminence is available |
| 306 s | `hold` | p60 0.51 ≥ 0.5 |
| 362 s | `back_off` | p30 0.60 ≥ 0.6 |
| 422 s | `resume` | rested 60 s and p30 0.17 < 0.3 |
| 501 s | `hold` | p60 0.51 ≥ 0.5 |
| 548 s | `back_off` | p30 0.61 ≥ 0.6 |
| 608 s | `resume` | rested 60 s and p30 0.21 < 0.3 |
| 692 s | `hold` | p60 0.52 ≥ 0.5 |
| 747 s | `back_off` | p30 0.61 ≥ 0.6 |
| 807 s | `resume` | rested 60 s and p30 0.23 < 0.3 |

## Ruin [#ruin]

Build to the point of no return, then stop completely and for good. The stop comes from imminence (`p30` at 0.75), because an orgasm call arrives a few seconds after the moment it names, which is too late to time a ruin. If a call arrives first, the preset stops at once. Report the stop with `reportStimulation` as it happens: an orgasm that begins within 30 seconds of it is counted as a ruin, and its `orgasm.end` says `ruined: true`.

**Ruin: past the point of no return** (sandbox scenario `ruin`). Imminence crosses the stop level, stimulation is reported off for good, and the peak still comes a few seconds later: a ruined orgasm, whose end says so.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.023 | 0.045 |
| 122 | 0.028 | 0.054 |
| 182 | 0.049 | 0.095 |
| 242 | 0.069 | 0.134 |
| 302 | 0.074 | 0.142 |
| 362 | 0.146 | 0.27 |
| 422 | 0.306 | 0.518 |
| 482 | 0.319 | 0.536 |
| 542 | 0.558 | 0.804 |
| 602 | 0.819 | 0.967 |
| 662 | 0.119 | 0.223 |
| 722 | 0.053 | 0.104 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.peak` | orgasm 1 at 612 s, lag 3.3 s, score 0.57 |
| `orgasm.end` | orgasm 1 at 640 s, lasted 28 s, face_end, lag 3.9 s, ruined |

| at | cue | because |
| --- | --- | --- |
| 62 s | `build` | imminence is available |
| 586 s | `stop` | p30 0.77 ≥ 0.75: the point of no return |

## Finish [#finish]

Build to an orgasm and carry the person through it, then ease off. For a woman, `sustain` runs from the onset to the end; for a man, the peak is the orgasm. With `orgasms` above 1 the preset builds again after each, until the count is reached.

**Finish: two orgasms** (sandbox scenario `finish`). A build-up to an onset and an end, a second, shorter build-up, and a second onset and end, each with its own orgasm index.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.021 | 0.042 |
| 122 | 0.029 | 0.058 |
| 182 | 0.038 | 0.074 |
| 242 | 0.049 | 0.095 |
| 302 | 0.101 | 0.193 |
| 362 | 0.148 | 0.274 |
| 422 | 0.249 | 0.436 |
| 482 | 0.377 | 0.612 |
| 542 | 0.853 | 0.978 |
| 602 | 0.316 | 0.532 |
| 662 | 0.414 | 0.657 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.onset` | orgasm 1 at 541 s, lag 4.4 s, score 0.73 |
| `orgasm.end` | orgasm 1 at 571 s, lasted 30 s, onset_end, lag 5 s |
| `orgasm.onset` | orgasm 2 at 643 s, lag 4.2 s, score 0.67 |
| `orgasm.end` | orgasm 2 at 668 s, lasted 25 s, onset_end, lag 4.9 s |

| at | cue | because |
| --- | --- | --- |
| 62 s | `build` | imminence is available |
| 545.4 s | `sustain` | onset called; keep going through it |
| 576 s | `build` | end called; 1 of 2, continue |
| 647.2 s | `sustain` | onset called; keep going through it |
| 672.9 s | `ease_off` | end called; 2 of 2 finished |

## The code [#the-code]

Each preset is a function of the event stream: feed it every event in `sequence` order and act on the cues it returns. Copy it into your product and tune it.

```ts title="examples/presets.ts"
// Reference implementations of the edge, ruin and finish presets.
//
// A preset is a policy your product runs on the event stream; it is not
// something orgasm.dev detects. Each preset reads `imminence.updated` and the
// orgasm calls and answers with a cue for your experience: build, hold, back
// off, resume, sustain, ease off or stop. What a cue does (lower an intensity,
// slow a scene, pause a game) is yours to decide.
//
// The thresholds are starting values to tune per person, not calibrated
// operating points. Signals can be wrong: never raise intensity on a signal
// alone, and keep a stop control that works whatever the signals say.

export type Cue = 'build' | 'hold' | 'back_off' | 'resume' | 'sustain' | 'ease_off' | 'stop';

export interface CueEvent {
  cue: Cue;
  /** Stream seconds of the event that produced the cue. */
  atS: number;
  reason: string;
}

/** The parts of an orgasm.dev event a preset reads. */
export interface PresetInput {
  type: string;
  streamTimeS: number;
  data?: unknown;
}

export interface Preset {
  readonly name: 'edge' | 'ruin' | 'finish';
  /** Feed every event in `sequence` order; returns a cue when one is due. */
  next(event: PresetInput): CueEvent | null;
}

interface Imminence {
  p30: number | null;
  p60: number | null;
}

const imminenceOf = (event: PresetInput): Imminence | null =>
  event.type === 'imminence.updated' ? (event.data as Imminence) : null;

const ended = (event: PresetInput) =>
  event.type === 'session.status' && (event.data as { status?: string } | undefined)?.status === 'ended';

const orgasmIndexOf = (event: PresetInput) => (event.data as { orgasmIndex: number }).orgasmIndex;

const fmt = (p: number) => p.toFixed(2);

export interface EdgeOptions {
  /** Stop increasing once p60 reaches this. */
  holdAtP60?: number;
  /** Back off once p30 reaches this. */
  backOffAtP30?: number;
  /** Resume only once p30 is below this... */
  resumeBelowP30?: number;
  /** ...and at least this many seconds have passed since backing off. */
  restS?: number;
}

/**
 * Edge: approach the point of no return and back away, as many times as the
 * person wants. An onset or a peak means the edge was crossed; the preset
 * then stops.
 */
export function edge(options: EdgeOptions = {}): Preset {
  const { holdAtP60 = 0.5, backOffAtP30 = 0.6, resumeBelowP30 = 0.3, restS = 60 } = options;
  let state: 'idle' | 'building' | 'holding' | 'resting' | 'done' = 'idle';
  let restingSince = 0;
  return {
    name: 'edge',
    next(event) {
      if (state === 'done') return null;
      const t = event.streamTimeS;
      if (ended(event)) {
        state = 'done';
        return null;
      }
      if (event.type === 'orgasm.onset' || event.type === 'orgasm.peak') {
        state = 'done';
        return { cue: 'stop', atS: t, reason: 'an orgasm began, so the edge was crossed' };
      }
      const im = imminenceOf(event);
      if (!im) return null;
      if (im.p30 === null || im.p60 === null) {
        if (state === 'building' || state === 'idle') {
          state = 'holding';
          return { cue: 'hold', atS: t, reason: 'no face reading; do not increase without one' };
        }
        return null;
      }
      if (state === 'idle') {
        state = 'building';
        return { cue: 'build', atS: t, reason: 'imminence is available' };
      }
      if (state === 'resting') {
        if (t - restingSince >= restS && im.p30 < resumeBelowP30) {
          state = 'building';
          return { cue: 'resume', atS: t, reason: `rested ${Math.round(t - restingSince)} s and p30 ${fmt(im.p30)} < ${resumeBelowP30}` };
        }
        return null;
      }
      if (im.p30 >= backOffAtP30) {
        state = 'resting';
        restingSince = t;
        return { cue: 'back_off', atS: t, reason: `p30 ${fmt(im.p30)} ≥ ${backOffAtP30}` };
      }
      if (state === 'building' && im.p60 >= holdAtP60) {
        state = 'holding';
        return { cue: 'hold', atS: t, reason: `p60 ${fmt(im.p60)} ≥ ${holdAtP60}` };
      }
      // Hysteresis: return to building only well below the hold level.
      if (state === 'holding' && im.p60 < holdAtP60 - 0.1) {
        state = 'building';
        return { cue: 'build', atS: t, reason: `p60 ${fmt(im.p60)} < ${fmt(holdAtP60 - 0.1)}` };
      }
      return null;
    },
  };
}

export interface RuinOptions {
  /** Stop for good once p30 reaches this: the point of no return. */
  stopAtP30?: number;
}

/**
 * Ruin: build to the point of no return, then stop stimulation completely and
 * for good. The stop comes from imminence, because orgasm calls arrive a few
 * seconds after the moment they name, which is too late to time a ruin.
 */
export function ruin(options: RuinOptions = {}): Preset {
  const { stopAtP30 = 0.75 } = options;
  let state: 'idle' | 'building' | 'holding' | 'done' = 'idle';
  return {
    name: 'ruin',
    next(event) {
      if (state === 'done') return null;
      const t = event.streamTimeS;
      if (ended(event)) {
        state = 'done';
        return null;
      }
      if (event.type === 'orgasm.onset' || event.type === 'orgasm.peak') {
        state = 'done';
        return { cue: 'stop', atS: t, reason: 'an orgasm was called before the stop level; stop now' };
      }
      const im = imminenceOf(event);
      if (!im) return null;
      if (im.p30 === null) {
        if (state !== 'holding') {
          state = 'holding';
          return { cue: 'hold', atS: t, reason: 'no face reading; do not increase without one' };
        }
        return null;
      }
      if (im.p30 >= stopAtP30) {
        state = 'done';
        return { cue: 'stop', atS: t, reason: `p30 ${fmt(im.p30)} ≥ ${stopAtP30}: the point of no return` };
      }
      if (state !== 'building') {
        state = 'building';
        return { cue: 'build', atS: t, reason: 'imminence is available' };
      }
      return null;
    },
  };
}

export interface FinishOptions {
  /** How many orgasms to finish before easing off. */
  orgasms?: number;
}

/**
 * Finish: build to an orgasm and through it, then ease off. A woman's orgasm
 * runs from its onset to its end; a man's is reached at its peak.
 */
export function finish(options: FinishOptions = {}): Preset {
  const { orgasms = 1 } = options;
  let state: 'idle' | 'building' | 'holding' | 'sustaining' | 'done' = 'idle';
  const reached = new Set<number>();
  const reach = (t: number, index: number, what: string): CueEvent | null => {
    if (reached.has(index)) return null;
    reached.add(index);
    if (reached.size >= orgasms) {
      state = 'done';
      return { cue: 'ease_off', atS: t, reason: `${what}; ${reached.size} of ${orgasms} finished` };
    }
    state = 'building';
    return { cue: 'build', atS: t, reason: `${what}; ${reached.size} of ${orgasms}, continue` };
  };
  return {
    name: 'finish',
    next(event) {
      if (state === 'done') return null;
      const t = event.streamTimeS;
      if (ended(event)) {
        state = 'done';
        return null;
      }
      if (event.type === 'orgasm.onset') {
        state = 'sustaining';
        return { cue: 'sustain', atS: t, reason: 'onset called; keep going through it' };
      }
      if (event.type === 'orgasm.peak') return reach(t, orgasmIndexOf(event), 'peak called');
      if (event.type === 'orgasm.end') return reach(t, orgasmIndexOf(event), 'end called');
      const im = imminenceOf(event);
      if (!im || state === 'sustaining') return null;
      if (im.p30 === null) {
        if (state === 'building' || state === 'idle') {
          state = 'holding';
          return { cue: 'hold', atS: t, reason: 'no face reading; do not increase without one' };
        }
        return null;
      }
      if (state !== 'building') {
        state = 'building';
        return { cue: 'build', atS: t, reason: 'imminence is available' };
      }
      return null;
    },
  };
}

export const presets = { edge, ruin, finish };

/** Runs a preset over a list of events and returns every cue it gives. */
export function cuesFor(preset: Preset, events: PresetInput[]): CueEvent[] {
  const cues: CueEvent[] = [];
  for (const event of events) {
    const cue = preset.next(event);
    if (cue) cues.push(cue);
  }
  return cues;
}
```

## Safety [#safety]

Every experience built on these signals needs the following, whatever the preset:

- **A stop that always works.** The person can end stimulation instantly at any moment, with a control that does not depend on the signals, the network or your server.
- **Signals advise; limits decide.** Never raise intensity on a signal alone, and cap intensity in the device, not in the policy. Treat a `null` reading as unknown and hold.
- **False calls and missed calls happen.** If a call has consequences in your experience (a forfeit, a reset, a reward), the person agreed to them in advance and can contest a call.
- **Electrical stimulation has its own rules.** Follow the device maker's instructions; never pass current across the chest or near the heart, and never use it with a pacemaker or another implanted device.
- **Consent is ongoing.** Denial, ruin and long edging are intense. Check in, let the person change the preset or stop mid-session, and plan for rest and aftercare.


---

# Signals (https://orgasm.dev/docs/concepts/signals)

orgasm.dev sends two kinds of signal. **Imminence** looks ahead: how likely orgasm is to begin soon. **Orgasm calls** look back: an onset, a peak or an end that has just happened. From the two, orgasm.dev also counts each **edge**, an approach that receded. A live session also describes what the voice, the body and the face are doing, for a **display**. Your product decides what to do with any of them; [presets](/docs/concepts/presets) are worked examples.

**A woman's orgasm: onset, then end** (sandbox scenario `woman-onset-end`). The face reads as a woman’s after about 30 seconds, imminence climbs over nine minutes, and the onset and end of one orgasm are called a few seconds after each happens.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.019 | 0.037 |
| 122 | 0.025 | 0.049 |
| 182 | 0.029 | 0.058 |
| 242 | 0.048 | 0.094 |
| 302 | 0.052 | 0.102 |
| 362 | 0.117 | 0.22 |
| 422 | 0.14 | 0.261 |
| 482 | 0.322 | 0.541 |
| 542 | 0.868 | 0.983 |
| 602 | 0.087 | 0.167 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.onset` | orgasm 1 at 538 s, lag 4.6 s, score 0.71 |
| `orgasm.end` | orgasm 1 at 575 s, lasted 37 s, onset_end, lag 5.2 s |

## Imminence [#imminence]

`imminence.updated` arrives about once a second while the face is analysed.

| Field | Meaning |
| --- | --- |
| `p30` | Probability that the next orgasm begins within 30 seconds, given that it has not begun yet |
| `p60` | The same over 60 seconds; never lower than `p30` |
| `logit30`, `logit60` | The same probabilities as logits, to combine with a prior of your own |
| `featuresPresent` | Share of the model's inputs available this second |
| `faceVisible`, `baselineReady` | Whether the reading rests on a tracked face and on the person's own baseline |
| `stimulationAware` | Whether it accounts for time under stimulation you [reported](/docs/api/live-sessions/reportStimulation) |
| `recentCalls` | The session's last orgasm calls, repeated so a missed call is seen within a second |

"Begins" means the onset for a woman and the peak for a man.

Read it as a probability over a horizon, **not a countdown**. A `p30` of 0.6 does not mean "in 18 seconds"; it means the model estimates that orgasm is more likely than not to begin within the next 30 seconds. Compare it with thresholds you tune for your experience and for the person, rather than reading the number as exact. The reading is `null` until the person's resting baseline is in, about a minute after their face first appears, and whenever the face is out of view.

Imminence from the face alone does not know how long the person has been stimulated. If your product controls stimulation, report it with `reportStimulation`, and imminence takes time under stimulation into account.

Imminence is currently more informative for men than for women. For women, combine it with onset and end.

## Orgasm calls [#orgasm-calls]

| Event | Called by | Applies to | Needs |
| --- | --- | --- | --- |
| `orgasm.onset` | `onset_end` | Women | Face and microphone |
| `orgasm.end` | `onset_end` | Women | Face and microphone |
| `orgasm.peak` | `peak` | Men | Face and microphone |
| `orgasm.end` | `face_end` | Men, after a peak | Face |

Each call names a moment (`eventAtS`) and says when the detector was sure enough to call it (`calledAtS`). The difference, `lagS`, is typically a few seconds: a call tells you what happened, not what is about to. To act at a moment, act on imminence; to confirm what happened, act on calls.

`orgasmIndex` counts orgasms in the session from 1; the onset and end of the same orgasm share it, as do a man's peak and the end read from his face. `score` and `threshold` are the detector's own: a score at or above the threshold made the call.

`orgasm.end` also says whether the orgasm was `ruined`: your product reported stimulation `off` at the point of no return (`p30` at 0.75 or above) within the 30 seconds before it began. A recording takes no stimulation reports, so its orgasms are never ruined.

**A man's orgasm: peak, then end** (sandbox scenario `man-peak`). The face reads as a man’s, imminence climbs to a peak, which is called about three seconds after it happens; the end is then read from his face.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.01 | 0.02 |
| 122 | 0.017 | 0.033 |
| 182 | 0.025 | 0.05 |
| 242 | 0.043 | 0.084 |
| 302 | 0.074 | 0.142 |
| 362 | 0.086 | 0.165 |
| 422 | 0.125 | 0.234 |
| 482 | 0.206 | 0.369 |
| 542 | 0.285 | 0.488 |
| 602 | 0.467 | 0.716 |
| 662 | 0.667 | 0.889 |
| 722 | 0.318 | 0.535 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.peak` | orgasm 1 at 701 s, lag 3.2 s, score 0.66 |
| `orgasm.end` | orgasm 1 at 742 s, lasted 41 s, face_end, lag 3.5 s |

## Edges [#edges]

`edge.completed` arrives when an approach recedes: `p30` reached 0.6 and fell back below 0.3 with no orgasm called in between, the [edge preset's](/docs/concepts/presets#edge) back-off and resume levels. orgasm.dev counts it on its side, numbers it (`edgeIndex`), and says when the approach started, how high it went (`peakP30`) and how long it lasted. Without the microphone no orgasm can be called, so every approach that recedes is an edge. In live mode an edge is charged half a credit ([Credits and billing](/docs/credits)).

**Edge: three approaches, no orgasm** (sandbox scenario `edge`). Imminence rises past the hold and back-off levels three times and falls each time stimulation is backed off, and the session ends without an orgasm: three edges, each an edge.completed.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.02 | 0.039 |
| 122 | 0.039 | 0.077 |
| 182 | 0.083 | 0.158 |
| 242 | 0.143 | 0.265 |
| 302 | 0.29 | 0.496 |
| 362 | 0.605 | 0.844 |
| 422 | 0.171 | 0.312 |
| 482 | 0.145 | 0.268 |
| 542 | 0.526 | 0.776 |
| 602 | 0.26 | 0.452 |
| 662 | 0.116 | 0.219 |
| 722 | 0.389 | 0.627 |
| 782 | 0.396 | 0.635 |
| 842 | 0.133 | 0.249 |

## Signals for a display [#signals-for-a-display]

`signals.updated` arrives with each imminence reading of a live session. It describes what the voice, the body and the face are doing, so a heads-up display can show more than a probability. None of it is a call, and none of it is charged. It is only streamed: webhooks don't carry it, and recordings don't have it.

| Field | Meaning | Needs |
| --- | --- | --- |
| `vocalizationsPerMin` | Vocalizations a minute | Microphone |
| `loudnessAboveBaselineDb` | How much louder the voice is than at the person's baseline, in decibels | Microphone |
| `contractionsPerMin` | Pelvic floor contractions a minute | Body view |
| `movement` | How still the body is: `settled`, `shifting` or `unsettled` | Body view |
| `faceRegions` | How far the `brows`, `eyes`, `cheeks`, `nose`, `lips`, mouth `corners` and `jaw` have each moved from the person's own resting state, from 0 to 1: each the largest of its expression channels | Face |
| `face` | The face's 24 expression channels (`expression`, each 0 at the person's rest to 1 for a full movement) and how far the head has turned from its resting pose (`head`: `yawDeg`, `pitchDeg`, `rollDeg`, as someone facing them sees it), for a display that draws the face | Face |

Each field is `null` while its input is absent or still calibrating, so show only the fields that have a value. To act, act on imminence and the calls; these describe the moment.

The channels say how the face moves, not what it looks like: drawn on a generic face, as the [HUD's](/docs/guides/hud) `face` part does, they show the person's expression without their features. A display can read them five times a second as [face frames](/docs/guides/realtime#face-frames), which also carry the head as the camera sees it, from before the baseline. A view token reads them only when made with `includeFace`.

## The device's state [#the-devices-state]

`stimulation.updated` is not a signal of the person's: it is what your product [reported](/docs/guides/realtime#reporting-the-device) about the device it drives (on or off, its level and channels, its mode, who sets the level), merged across reports and sent to every reader, so a display can show it beside the signals. It is only streamed.

## The subject read [#the-subject-read]

`subject.identified` arrives once, about 30 seconds after the face first appears: whether it reads as a woman's or a man's, or `undetermined`. It decides which detectors apply. [Subject](/docs/concepts/subject) explains how, and how to treat it.

## Confidence [#confidence]

Every signal carries `confidence`: `high`, `medium` or `low`, from how complete its input was. `high` means the face was tracked throughout and every input the signal uses was present; `low` means degraded input, or a detector that ran while the subject was undetermined. It describes the input, not a calibrated probability that the call is right.

## What signals are not [#what-signals-are-not]

- **Not proof.** Detectors make false calls and miss real ones. Do not treat a call as evidence about a person, and do not attach consequences to one that the person has not agreed to in advance.
- **Not a medical measurement.** Nothing here diagnoses or monitors a condition.
- **Not identity.** No signal identifies who a person is, and the subject read is not a statement about anyone's sex or gender.


---

# Subject (https://orgasm.dev/docs/concepts/subject)

Orgasm looks different in different bodies, and orgasm.dev's detectors are specific to it: one calls the onset and the end of a woman's orgasm (`onset_end`), another the peak of a man's (`peak`), and a third reads the end of a man's orgasm from his face (`face_end`). You never have to say which applies. The face is read, and the detectors follow.

## The read [#the-read]

`subject.identified` arrives once per session or recording, after about 30 seconds of visible face with one person in view.

```json
{
  "id": "evt_0z6tc53e7py0ep61nm8s",
  "object": "event",
  "type": "subject.identified",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 4,
  "streamTimeS": 32,
  "confidence": "high",
  "data": {
    "sex": "woman",
    "pWoman": 0.94,
    "secondsObserved": 30,
    "decidedAtS": 32,
    "hint": null,
    "detectors": [
      "onset_end"
    ]
  },
  "wallTime": "2026-10-16T14:00:04.200Z"
}
```

| Field | Meaning |
| --- | --- |
| `sex` | `woman`, `man` or `undetermined` |
| `pWoman` | The read's probability that the face is a woman's, or `null` if it could not be read |
| `secondsObserved` | Seconds of visible face the read was made from |
| `decidedAtS` | When it was made, in stream seconds |
| `hint` | The `subjectHint` you gave, if any |
| `detectors` | The detectors that apply from now on |

The read decides only when it is clear, so **`undetermined` is common**. While undetermined, every detector runs, and their calls arrive with `confidence: low` and a shared `orgasmIndex` when they describe the same orgasm.

**Subject undetermined: every detector runs** (sandbox scenario `undetermined`). The face read stays undetermined, so the onset-and-end detector and the peak detector both run, and their calls arrive with low confidence and a shared orgasm index.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.022 | 0.043 |
| 122 | 0.024 | 0.047 |
| 182 | 0.047 | 0.092 |
| 242 | 0.056 | 0.11 |
| 302 | 0.077 | 0.147 |
| 362 | 0.132 | 0.247 |
| 422 | 0.172 | 0.315 |
| 482 | 0.279 | 0.481 |
| 542 | 0.446 | 0.693 |
| 602 | 0.769 | 0.947 |
| 662 | 0.103 | 0.196 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.onset` | orgasm 1 at 590 s, lag 5.1 s, score 0.58 |
| `orgasm.peak` | orgasm 1 at 596 s, lag 3.4 s, score 0.55 |
| `orgasm.end` | orgasm 1 at 624 s, lasted 34 s, onset_end, lag 5.3 s |

## Which detectors apply [#which-detectors-apply]

1. If you gave `subjectHint`, it decides, from the start.
2. Otherwise the read decides, once it is made.
3. Before the read, and while it is undetermined, all detectors run.

Give `subjectHint` when the person has told you, for example in their profile or in the experience's setup. Don't guess it. If the hint and the read disagree, the hint wins and both are reported.

## How to treat the read [#how-to-treat-the-read]

The read describes facial appearance, to choose detectors. It can be wrong for anyone, and it says nothing about a person's sex or gender identity.

- Don't show it to the person as a judgment about them, and don't store it as their sex or gender.
- Let people choose. Offering the hint as a setting serves trans and non-binary people, and everyone the read gets wrong.
- Don't use it for anything but choosing detectors: not for targeting, profiling or access decisions.


---

# Timing (https://orgasm.dev/docs/concepts/timing)

## Two clocks [#two-clocks]

- **Stream time** (fields ending in `S`): seconds on the media's own clock, from the first frame of a live stream or the start of a recording. Every moment an event names is on it.
- **Wall time** (`wallTime`): UTC, when the event was produced. For a recording it is when the analysis made the call, not a time in the recording.

Use stream time to place events relative to each other and to your own media; use wall time to relate them to the rest of your system.

## Calls are retrospective [#calls-are-retrospective]

An orgasm call is made once the detector is sure, a few seconds after the moment it names:

```json
{
  "id": "evt_26m8iv7m9ik1q6bbpxah",
  "object": "event",
  "type": "orgasm.peak",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 1293,
  "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:01:11.420Z"
}
```

`eventAtS` is when the peak happened; `calledAtS` is when it was called; `lagS` is the difference. Design for it:

- To act **before** a moment (back off at the edge, stop for a ruin), act on imminence.
- To act **because of** a moment (end a level, log an outcome), act on the call.
- Never assume no call means nothing happened: wait at least `lagS` plus a margin.

## Order and delivery [#order-and-delivery]

- `sequence` numbers a session's or recording's events from 1, without gaps. Sort by it and use it to spot a gap.
- Delivery is at least once. A redelivered event keeps its `id`; deduplicate on it.
- The stream and the socket replay what you missed when you reconnect with the last `id` (`Last-Event-ID`, `after` or a `resume` message). Webhook retries can arrive out of order.
- Every `imminence.updated` repeats the last eight orgasm calls in `recentCalls`. If you only follow imminence, a call whose own message was lost still reaches you within a second.

## Acting without flapping [#acting-without-flapping]

Imminence moves. Acting on every crossing of a threshold makes an experience stutter. Use hysteresis: enter a state above one level and leave it only below a lower one, and require the condition for a moment before acting.

```ts title="hysteresis.ts"
type State = 'below' | 'above';

/** Enters `above` when p rises past `enter` for `holdS` seconds; leaves only when p falls past `exit`. */
export function threshold(enter: number, exit: number, holdS = 2) {
  let state: State = 'below';
  let since: number | null = null;
  return (p: number | null, atS: number): State => {
    if (p === null) return state; // no reading: keep the current state
    if (state === 'below') {
      since = p >= enter ? (since ?? atS) : null;
      if (since !== null && atS - since >= holdS) state = 'above';
    } else if (p < exit) {
      state = 'below';
      since = null;
    }
    return state;
  };
}
```

The [presets](/docs/concepts/presets) apply the same idea: edge holds at one level and backs off at a higher one, and returns to building only well below.

## How fast things arrive [#how-fast-things-arrive]

- Imminence updates about once a second.
- Status changes and warnings arrive as they happen.
- Orgasm calls arrive a few seconds after the moment they name, plus your network.
- The first minute of a session is calibration: the subject read comes after about 30 seconds, imminence after about a minute.
- Starting a session can take a few minutes when no analysis capacity is warm; `session.status` tells you when it is `ready`.


---

# Trust (https://orgasm.dev/docs/concepts/trust)

The video of someone's face in an intimate moment is about as sensitive as data gets. orgasm.dev is designed so that nobody sees it: not you, not orgasm.dev's operators, not the cloud provider. Only the numbers in the events leave the enclave that analyses it.

<Callout title="Status">
  Live sessions run as this page describes. The sandbox runs no enclave: it accepts no media and has nothing to attest (`GET /v1/attestation-policy?mode=test` says so). Recorded videos are not analysed by an enclave yet; what this page says of recordings is how they will be.
</Callout>

## The enclave [#the-enclave]

Media is decrypted and analysed only inside a confidential virtual machine: its memory is encrypted by the processor (Intel TDX) and its GPU, an NVIDIA H100, runs in confidential-computing mode, so the host, the hypervisor and the operators cannot read it. The machine boots Google's Confidential Space image with debugging disabled since boot: nobody can log in to it, redirect its output or read its memory.

It runs an image that a public repository's release workflow built from a tagged commit, with SLSA provenance and a signature in Sigstore's public log. The cloud's attestation service issues a signed token that names the exact image, its release and the hardware, which anyone can check: [Verify the enclave](/docs/guides/verify) shows how.

Inside, frames and audio samples are turned into measurements and never written to disk. What leaves is the events in this API. The enclave keeps no record of an orgasm.dev session: the lease that starts one names nowhere to write it.

## Read the code [#read-the-code]

The code is public, under the Apache-2.0 license: [the device SDK](https://github.com/Orgasm-dev/device-sdk) that films and sends, and [the enclave's source](https://github.com/Masseuse-ai/masseuse-video-tee) that analyses. Every line that reads a frame or an audio sample is in one of them.

| What it does | Where |
| --- | --- |
| On the device: checks the enclave's attestation, seals every request to it and publishes the camera and microphone | [`device-sdk/src`](https://github.com/Orgasm-dev/device-sdk/tree/main/src) |
| Decodes the video, finds the person, estimates keypoints and measures motion | [`workload/pixel`](https://github.com/Masseuse-ai/masseuse-video-tee/tree/master/workload/pixel) |
| Decodes the audio, classifies vocalizations, measures level and pitch | [`workload/audio`](https://github.com/Masseuse-ai/masseuse-video-tee/tree/master/workload/audio) |
| Runs the session: the WebRTC ingest, the capability and seal checks, the readings it sends on | [`workload/producer`](https://github.com/Masseuse-ai/masseuse-video-tee/tree/master/workload/producer) |
| Fixes what the machine may be told at boot (the launch policy) and how it starts | [`workload/tee/Dockerfile.tee`](https://github.com/Masseuse-ai/masseuse-video-tee/blob/master/workload/tee/Dockerfile.tee) |
| Builds, signs and attaches provenance to every release | [`.github/workflows/release.yml`](https://github.com/Masseuse-ai/masseuse-video-tee/blob/master/.github/workflows/release.yml) |
| Checks a running enclave from outside | [`verifier/`](https://github.com/Masseuse-ai/masseuse-video-tee/tree/master/verifier) and [`VERIFY.md`](https://github.com/Masseuse-ai/masseuse-video-tee/blob/master/VERIFY.md) |

## What is not public [#what-is-not-public]

The detectors, the code that turns those measurements into imminence, onset, peak, end and subject, are orgasm.dev's and are not published. What the enclave guarantees about them:

- They run in a process of their own, as a user of their own, with no network access of their own; everything they produce leaves through the public code above.
- They never receive a frame, a crop or an audio sample. [`analysis/protocol.md`](https://github.com/Masseuse-ai/masseuse-video-tee/blob/master/analysis/protocol.md) lists every field they receive and every field they return.
- Their bytes are pinned. The image fetches them at boot and refuses to start them unless their SHA-256 matches [`analysis.lock`](https://github.com/Masseuse-ai/masseuse-video-tee/blob/master/analysis.lock), which is part of the attested image, so the attestation also says which detectors ran. The model weights are pinned the same way in [`models.lock`](https://github.com/Masseuse-ai/masseuse-video-tee/blob/master/models.lock).

## What the device verifies [#what-the-device-verifies]

Before it sends anything, the end user's device:

1. Fetches the enclave's attestation (`ingest.attestationUrl`) and checks it against the [attestation policy](/docs/api/trust/getAttestationPolicy): the issuer, the hardware, the image and its minimum release, and that the enclave is not debuggable.
2. Takes the enclave's sealing key from the attested evidence and seals each request to it (`seal: v1`: an ephemeral P-256 key agreement and AES-256-GCM). Only that enclave can open them.
3. Checks the enclave's signature (Ed25519, with a key bound into the attestation) on the WebRTC answer before connecting, so the media session ends inside the attested enclave.

The device also holds the session's **capability**, 32 random bytes it generated. Your server and orgasm.dev's servers only ever see its SHA-256 (`capabilityHash`), and only the holder of the capability can publish. The SDK does all of this; [live sessions](/docs/guides/live-sessions) shows the steps, and [Verify the enclave](/docs/guides/verify) shows how to run the same checks yourself, from outside, against a session's enclave.

## Who sees what [#who-sees-what]

| Party | Sees |
| --- | --- |
| The enclave | The media, while analysing it |
| Whoever runs the enclave's cloud project | Nothing of the media: they can start, stop and name the machine, never read its memory, its keys or the detectors |
| orgasm.dev's servers | The capability hash, session settings and metadata, the events, and the device's IP address when it connects |
| Your server | What you send and the events you receive |
| The network, a TURN relay | Encrypted media, and the device's IP address |

The enclave's cloud project is orgasm.dev's fleet, or, with [your own GPUs](/docs/guides/own-gpus), yours. On your own GPUs every reading the enclave sends is signed with the key its attestation binds, so orgasm.dev takes readings only from the enclave itself, whoever runs the project.

## Where the guarantee stops [#where-the-guarantee-stops]

- **Capture must happen on the person's device.** The guarantee holds when the device that films the person verifies the enclave and publishes to it directly. If you relay the video through your own servers, you can see it.
- **The SDK in your app runs the checks.** A device that skips them could send media anywhere, so the guarantee assumes your app runs the SDK as published. [Its source](https://github.com/Orgasm-dev/device-sdk) is public too, so you can read what it checks before it sends a frame, and each release on npm carries provenance from it, so `npm audit signatures` confirms that is what you installed.
- **Recordings** are sealed on the device before upload, or fetched by the enclave from a URL you sign, and deleted once analysed. Whoever holds the original file still holds it.
- **The events are sensitive too.** They describe a person's sexual response. Keep them only as long as you need (`retentionDays`, `purgeLiveSession`, `deleteRecording`) and protect them as you would health data.


---

# Credits and billing (https://orgasm.dev/docs/credits)

Live sessions draw on your company's prepaid **credits**. You pay for what orgasm.dev counts in a session, never for time on camera:

| Charged for | Credits | Counted when |
| --- | --- | --- |
| [An orgasm](#orgasms) | 1 | its first call arrives: an onset, a peak, or while the subject is undetermined, either |
| [A ruin](#ruins) | 1 | in place of an orgasm, when your product stopped stimulation at the point of no return just before it began |
| [An edge](#edges) | ½ | imminence reached 0.6 and fell back below 0.3 with no orgasm called in between |
| [The session minimum](#the-session-minimum) | ½ | a session with more than a minute of media ends having counted none of the above |

Credits belong to your company, shared by its [team](/docs/guides/teams). Every company starts with **20 free credits**. Test keys are free and unlimited. What credits cost, and how to buy them, is on [Pricing](/pricing).

## Orgasms [#orgasms]

An orgasm is charged once, by its `orgasmIndex`, when its first call arrives. A woman's onset and end, a man's peak and the end read from his face, and every call made while the subject is undetermined share one index and one charge. Two orgasms in a session are two credits.

## Ruins [#ruins]

A ruin is an orgasm that begins after your product has stopped stimulation at the point of no return. orgasm.dev tells it from an orgasm by your own [stimulation reports](/docs/api/live-sessions/reportStimulation): an orgasm is a ruin when the last report before it began was `off`, sent within the 30 seconds before while `p30` was at 0.75 or above, the [ruin preset's](/docs/concepts/presets#ruin) stop level. Its `orgasm.end` carries `ruined: true`.

A ruin costs what an orgasm costs, so reporting a stop changes what you count, never what you pay. Report the stop as it happens: a report sent after the orgasm's first call does not change how it was counted.

```json
{
  "id": "evt_20wbdv4aq0o16ns5dfu9",
  "object": "event",
  "type": "orgasm.end",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 1172,
  "streamTimeS": 643.9,
  "confidence": "high",
  "data": {
    "orgasmIndex": 1,
    "eventAtS": 640,
    "startedAtS": 612,
    "durationS": 28,
    "calledAtS": 643.9,
    "lagS": 3.9,
    "detector": "face_end",
    "score": null,
    "threshold": null,
    "ruined": true
  },
  "wallTime": "2026-10-16T14:01:05.390Z"
}
```

## Edges [#edges]

An edge is an approach that receded: `p30` reached 0.6, the [edge preset's](/docs/concepts/presets#edge) back-off level, and fell back below 0.3, its resume level, with no orgasm called in between. orgasm.dev counts it on its side and sends `edge.completed` with the reading that completed it, on the stream, the socket and to your webhooks. Its `confidence` is the lowest of the approach's readings.

```json
{
  "id": "evt_2gi9on772qb0beswjxgp",
  "object": "event",
  "type": "edge.completed",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 706,
  "streamTimeS": 411,
  "confidence": "high",
  "data": {
    "edgeIndex": 1,
    "startedAtS": 362,
    "eventAtS": 411,
    "durationS": 49,
    "peakP30": 0.687
  },
  "wallTime": "2026-10-16T14:00:42.100Z"
}
```

An orgasm called during an approach makes it an orgasm, not an edge, and so does the fall of imminence after it: a new approach starts only once `p30` is back below 0.3. Without the microphone no orgasm can be called, so in a face-only session every approach that recedes is an edge.

## The session minimum [#the-session-minimum]

A live session with more than a minute of media that ends having counted no orgasm, ruin or edge is charged half a credit, so an empty session is never free. A session that never received media is not charged, and neither is one that ended because orgasm.dev lost its analysis capacity (`interrupted`) or failed (`error`).

## Where charges show up [#where-charges-show-up]

- **On the session.** Every live session has `charges`: `orgasms`, `ruins`, `edges`, `sessionMinimum` and the `credits` it drew so far.
- **In the events.** `edge.completed` and `orgasm.end`'s `ruined` say what was counted, as it happens.
- **In usage.** [`getUsage`](/docs/api/account/getUsage) counts `orgasms`, `ruins`, `edges`, `sessionMinimums` and `credits` per day.
- **In the balance.** [`getCredits`](/docs/api/account/getCredits) returns what your company has left, the free credits remaining, and each package with its price per credit and expiry. Your console's Billing tab shows the same, with the last 30 days by unit.
- **By charge, in dollars.** [`listCharges`](/docs/api/account/listCharges) lists each charge with what it cost and the references of the session it belongs to ([cost attribution](#cost-attribution)). Admins and Billing members see the same in the Billing tab.

Charges are made once each: a redelivered event, a reconnect or a retry never charges twice.

## Credits, in order [#credits-in-order]

Free credits are used first, then whichever package expires soonest. A package's credits last 12 months from the day they post; the free 20 do not expire. A charge that a package cannot cover takes the rest from the next one.

## At zero [#at-zero]

A new live session is refused with [`credits_exhausted`](/docs/guides/errors#credits_exhausted) (`402`). Sessions already running finish, and what they use past zero comes out of the next package that posts, so the balance can read below zero until then. Test keys keep reaching the sandbox.

You hear before then. When your balance falls to 20% of your latest package (4 of the free 20), orgasm.dev sends `credits.low` to the live endpoints that subscribed to it, once per package:

```json
{
  "id": "evt_5c2x8v1b4n7m0q3w6e9r",
  "object": "event",
  "type": "credits.low",
  "mode": "live",
  "wallTime": "2026-10-16T14:21:07Z",
  "data": { "domain": "studio.example", "balance": 4, "threshold": 4, "freeRemaining": 4, "packageId": "free" }
}
```

It belongs to your company rather than a session, so it has no `sessionId`, `sequence` or stream time. Subscribe to it like any other [webhook](/docs/guides/webhooks).

## Cost attribution [#cost-attribution]

To see what each of your users and sessions cost, say who a session is for when you create it:

- **`userReference`**: your own pseudonymous id for the person, the same on each of their sessions. Never their email, phone or name: derive it from your user id with a key only you hold, as below.
- **`clientReferenceId`**: your id for the session, such as a booking, an order or a round.
- **`metadata`**: up to 20 string values of your own, like a plan, a product, a region or a campaign. Each key is a dimension your costs break down by. Keep personal data out of it.

Both references are 1 to 128 letters, digits, `.`, `_`, `:` or `-`, with at least one letter. A value with `@`, `+` or a space, or one made only of digits, is refused with `422 invalid_request`, so an email address or a phone number never gets in by mistake.

```ts title="server.ts"
import { createHmac } from 'node:crypto';

// The same person, the same reference; nobody without REFERENCE_KEY can link it back to them.
const userReference = `u_${createHmac('sha256', process.env.REFERENCE_KEY!).update(user.id).digest('hex').slice(0, 32)}`;

await fetch('https://orgasm.dev/v1/live-sessions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.ORGASM_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ consent, capabilityHash, userReference, clientReferenceId: `booking_${booking.id}`, metadata: { plan: user.plan } }),
});
```

Each charge is valued at the price per credit of the package it drew on. A charge on the free credits costs $0. A charge used [past zero](#at-zero) has no price until the next package posts and covers it, at that package's price. In the Billing tab, Admins and Billing members pick a month and break its costs down by day, unit, API key, user reference, session or any metadata key, and open a session to see its charges. [`listCharges`](/docs/api/account/listCharges) gives your systems the charges, filtered by `userReference`, `clientReferenceId`, `sessionId` or dates, with a secret key or a read-only [billing key](/docs/guides/teams#billing-keys).

References and metadata are kept for 13 months, then erased; the charges stay, without them. To delete one person's data, purge their sessions by reference ([retention and deletion](/docs/concepts/compliance#retention-and-deletion)).

## Reconciling with your invoices [#reconciling-with-your-invoices]

- **The statement.** For each month, the Billing tab's Statement shows your prepaid credits in dollars: at the start of the month, packages posted, used by sessions, returned by reviews, expired unused, and at the end. The month's charges add up to "used by sessions" to the cent.
- **Two CSV exports** for any month, in UTC:
  - *Charges*: one row per charge, with `id`, `at`, `session_id`, `unit`, `index`, `credits`, `free_credits`, `paid_credits`, `pending_credits`, `amount_usd`, `packages`, `returned`, `own_gpu`, `api_key_id`, `api_key_name`, `user_reference`, `client_reference_id` and `metadata`.
  - *Sessions*: one row per session, with its times, `ended_reason`, `media_seconds`, the key, its references and metadata, what it counted, and `credits`, `pending_credits` and `amount_usd`.
- **Pending.** Credits used past zero are valued when the package that covers them posts, and counted as used in that month.
- **Expired credits** are no session's cost. They appear on their own line, "Expired unused", never spread over sessions.
- **Returns.** A charge returned after a [review](#contesting-a-charge) is marked `returned` and costs nothing. The month of the review shows the return.

Amounts are in dollars to a tenth of a cent (`amount_usd` has three decimals), because a half-credit charge at some prices ends in half a cent.

## Testing in the sandbox [#testing-in-the-sandbox]

Sandbox sessions count everything a live session would, and draw nothing: their `charges` show what was counted, with `credits` at 0. The `edge` scenario counts three edges, `ruin` a ruin (it reports stimulation on at the baseline and off where the ruin preset stops, as your product would), `finish` two orgasms, and `face-only` an edge. A session you end after more than a minute of a scenario's media, before anything is counted, shows the minimum.

```bash
curl -s https://orgasm.dev/v1/live-sessions \
  -H "Authorization: Bearer $ORGASM_KEY" -H "Content-Type: application/json" \
  -d '{"consent":{"subjectIsAdult":true,"subjectConsented":true,"ageVerification":"document"},"sandbox":{"scenario":"edge","speed":60}}'
```

## Contesting a charge [#contesting-a-charge]

Detectors make false calls. If a charge was wrong, write to [support@orgasm.dev](mailto:support@orgasm.dev) within 14 days with the session and the call. If the review agrees, the credit is returned to the package it came from.

## Your own GPUs [#your-own-gpus]

Sessions on [your own GPUs](/docs/guides/own-gpus) are counted the same way and marked as yours; their price is set in your statement of work.


---

# Camera and microphone (https://orgasm.dev/docs/guides/capture)

A browser asks once for the camera and microphone, in a prompt it words itself, and remembers a no. The device SDK's capture module asks well: from a click, with the constraints the analysis needs, and when the answer is no, it says why and what to do in that browser. `<orgasm-capture-primer>` explains before the prompt appears.

## Explain first [#explain-first]

```html
<orgasm-capture-primer developer="Lumen Games" retention-days="7" privacy-url="https://lumen.example/privacy"></orgasm-capture-primer>
```

Before the browser asks anything, the primer tells the person, in plain words:

- **what is measured**: how close they are to orgasm, and when one begins, peaks and ends;
- **why the camera**: their face shows how close they are;
- **why the microphone**: breath and voice mark when an orgasm begins, peaks and ends, and without it those moments aren't called;
- **that only numbers leave their device**: video and sound go to an enclave their device checks first, are analysed there and never stored, and nobody can watch them, you included;
- **who receives the readings and for how long**: your name (`developer`) and your `retention-days`, or `0` for not kept;
- **that they are in control**: a light shows whenever analysis is on, and they can stop it at any time.

| Attribute | |
| --- | --- |
| `developer` | Your product's name, as the person knows it |
| `purpose` | A sentence on what your product does with the readings |
| `retention-days` | How long you keep them; without it, the primer points to your privacy policy |
| `privacy-url` | Your privacy policy |
| `audio` | `false` to ask for the camera alone |

`primer.strings` rewords any of it, for another language or your product's voice; keep what each line says.

```js title="device.js"
import { verifyEnclave } from '@orgasm-dev/device';
import '@orgasm-dev/device/hud';

const primer = document.querySelector('orgasm-capture-primer');
primer.verify = () => verifyEnclave({ origin: new URL(session.ingest.attestationUrl).origin, policyUrl: 'https://orgasm.dev/v1/attestation-policy' });
primer.addEventListener('orgasm-capture', (event) => publish(event.detail.capture.stream));
primer.addEventListener('orgasm-capture-refused', (event) => track('camera_refused', event.detail.reason));
primer.addEventListener('orgasm-capture-declined', () => showLater());
```

With `verify` set, the primer checks the enclave on the person's device before it asks, and says that it did, with the release it found. If the check fails it asks for nothing and fires `orgasm-capture-failed`. A sandbox session has no enclave to check, so leave `verify` unset with a test key.

## Ask from a click [#ask-from-a-click]

Without the primer, call `requestCapture` from a click: browsers show their prompt only in answer to one.

```ts title="device.ts"
import { CaptureRefused, requestCapture } from '@orgasm-dev/device/capture';

button.addEventListener('click', async () => {
  try {
    const capture = await requestCapture();
    // capture.stream for publishLiveSession; capture.audio is false when only the camera started
  } catch (error) {
    if (error instanceof CaptureRefused) message.textContent = error.recovery;
    else throw error;
  }
});
```

It asks for the front camera at a long edge of 1280 pixels and 30 frames a second, the [inputs](/docs/concepts/inputs) the analysis reads, and for the microphone. A missing or busy microphone doesn't stop it: the camera starts alone and `capture.audio` says so, because imminence and edges need only the face. `requestCapture({ audio: false })` asks for the camera alone.

## When the answer is no [#when-the-answer-is-no]

`CaptureRefused` names the refusal in `reason`, and `recovery` is a sentence to show the person, written for their browser:

| `reason` | What happened |
| --- | --- |
| `denied` | The person, the browser or the system said no. `recovery` says where this browser's camera permission is, and the system's setting behind it. |
| `no_camera` | There is no camera, or not the one asked for |
| `in_use` | Another app holds the camera; `recovery` mentions OBS's Virtual Camera |
| `insecure` | The page isn't https (or localhost) |
| `unsupported` | This browser can't share a camera with a page |
| `aborted` | The camera didn't start, for no reason the browser gave |

## Before asking anything [#before-asking-anything]

`captureSupport()` says whether this browser can run a live session at all, before any prompt: `{ ok, missing }`, where `missing` lists `secure_page`, `camera_access`, `webrtc`, `streams` or `ed25519` (the enclave's signatures). Show a browser that can't run one what to use instead, rather than a prompt that fails.

`listCaptureDevices()` lists the cameras and microphones, with names once the person has granted access. Pass one as `videoDeviceId` to `requestCapture`, or as the primer's `captureOptions`, to use a camera other than the front one, such as OBS's Virtual Camera.

## The primer is not consent [#the-primer-is-not-consent]

The primer explains; it doesn't ask for consent and doesn't record it. Your product still asks the person, explicitly, before the session starts, keeps a record, and attests both in `consent` when it creates the session ([Acceptable use](/docs/concepts/compliance)). Show the primer after that consent, as the step that turns the camera on.


---

# Errors (https://orgasm.dev/docs/guides/errors)

Errors are [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details, served as `application/problem+json`:

```json
{
  "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, and consent.ageVerification must say how age was verified.",
  "param": "consent",
  "instance": "/v1/live-sessions",
  "requestId": "req_3k6m9q2t5w8z1c4f7h0j"
}
```

Switch on `code`, which is stable; show `detail` to developers, not to end users. `param` names the field at fault. When a request breaks the contract, `errors` lists each violation with its `location`, JSON `path` and `message`. Every response carries `Request-Id`; include it when you ask for help.

## Codes [#codes]

### invalid_request [#invalid_request]

`400` or `422`. The body is not JSON, or a parameter or field breaks the contract. Fix the request; `errors` and `param` say where.

### consent_required [#consent_required]

`422`. `consent.subjectIsAdult` or `consent.subjectConsented` is not `true`, or `consent.ageVerification` is missing. Only set them when your product has verified both; see [acceptable use](/docs/concepts/compliance).

### capability_required [#capability_required]

`422`. A live session created with a live key needs `capabilityHash` from the device.

### sandbox_only [#sandbox_only]

`422`. `sandbox` options were sent with a live key.

### authentication_required [#authentication_required]

`401`. No key was sent. Send `Authorization: Bearer sk_test_…`.

### invalid_api_key [#invalid_api_key]

`401`. The key or client token is malformed, revoked, or belongs to no session.

### live_mode_unavailable [#live_mode_unavailable]

`403`. A live key cannot do this yet: today, recorded videos (`createRecording`), which the sandbox analyses meanwhile with a key that starts with `sk_test_`. Every live request answers it while live analysis is switched off.

### credits_exhausted [#credits_exhausted]

`402`. Your company has no credits left, so a new live session does not start. Sessions already running finish, and test keys still reach the sandbox. Buy a package through [sales@orgasm.dev](mailto:sales@orgasm.dev): live sessions start again as soon as it posts. Do not retry until then. [Credits and billing](/docs/credits) explains the balance and `credits.low`, which warns you before zero.

### permission_denied [#permission_denied]

`403`. The credential cannot do this; a client token, for example, only reads its own session, and a sandbox key that belongs to no company has no credits to read.

### not_found [#not_found]

`404`. No such resource in this key's mode, or it was deleted.

### idempotency_key_reused [#idempotency_key_reused]

`409`. The `Idempotency-Key` was used with a different body. Use a new key for a new request.

### session_ended [#session_ended]

`409`. The session has ended; create a new one.

### sandbox_no_media [#sandbox_no_media]

`501`. The sandbox accepts no media; its sessions play their scenario on their own.

### upload_already_received [#upload_already_received]

`409`. The upload URL was already used; submit a new recording to upload again.

### payload_too_large [#payload_too_large]

`413`. The upload is larger than `maxBytes`.

### rate_limited [#rate_limited]

`429`. Too many requests. Wait `Retry-After` seconds. `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` are on every response.

### capacity_unavailable [#capacity_unavailable]

`503`. No analysis capacity is free. Retry after `Retry-After` seconds.

### internal_error [#internal_error]

`500`. Something failed on our side. Retry with the same `Idempotency-Key`.

## Retries and idempotency [#retries-and-idempotency]

Send an `Idempotency-Key` (a UUID) with every `POST`. A retry with the same key and body within 24 hours returns the first response, marked `Idempotent-Replayed: true`, instead of acting twice. Retry `429`, `500` and `503` with exponential backoff; do not retry other `4xx`, `402` included, without changing the request or the balance.


---

# Show the HUD (https://orgasm.dev/docs/guides/hud)

`<orgasm-hud>` shows a live session to the person as it happens: how close they are, what just happened, and what needs their attention. It is part of the [device SDK](https://github.com/Orgasm-dev/device-sdk), draws only from the session's [events](/docs/concepts/signals), and has no dependencies.

<HudDemo layout="rail" caption="The edge scenario, played in your browser: no network, no camera." />

## What it shows [#what-it-shows]

- **The phase**, in a word. It says Calibrating while the person's baseline is taken (about a minute), then Building, then Rising, Close and Very close at the [presets'](/docs/concepts/presets) levels (`p30` at 0.3, 0.6 and 0.75). After a call it says Onset, Peak or Afterglow.
- **The gauge**: the chance that orgasm begins within 30 seconds (`p30`), with the 60-second chance as a ghost mark. It eases between the once-a-second readings, and it reads as a chance within 30 seconds, never as a countdown ([timing](/docs/concepts/timing)).
- **The trend**: the last three minutes, with each onset, peak, end and edge marked at the moment it names rather than when it arrived.
- **The counts** of orgasms, ruins and edges, and the session's clock.
- **The signals** from `signals.updated`: vocalizations, contractions and movement as tiles, and how far each region of the face has moved. Each appears only while its input is there.
- **The device**, when your product drives one and [reports it](/docs/guides/realtime#reporting-the-device): its name, its mode in words, who sets the level, and a bar per output toward the most it will go to.
- **The face**: a generic face (the Momentum Human Rig's mean head, which is no one's, its two sides each other's mirror) moving as the person's does, from their expression channels and the turn of their head, with the face's seven regions as meters beside it. It glides between readings, and follows the face five times a second when it reads frames. Where frames carry the head as the camera sees it (`cameraHead`), the head is drawn by that: a head held tilted, or lying on its side, is drawn as it is, and during the baseline a face at rest follows the head under the waiting words.
- **The timeline**: the whole session, up to three hours in five-second bins, in three lanes on one time axis: imminence, the device's level per output with each change of mode, and the body's rates. Each lane draws only once it has something to show, and each call and edge is marked across them.
- **Notices**, such as the face out of view, the baseline being taken or no microphone.
- **The subject read**, only when you ask for it with `show` ([subject](/docs/concepts/subject)).

On the person's device the HUD always shows that analysis is on, and a Stop control. The [Acceptable use](/docs/concepts/compliance) rules ask for both: the person sees when analysis runs, and can stop it at any moment.

## Install [#install]

```sh title="Terminal"
npm install @orgasm-dev/device
```

```ts
import '@orgasm-dev/device/hud'; // defines <orgasm-hud> and <orgasm-capture-primer>
```

The import is safe in server rendering: the elements are defined only where the browser has a registry.

## On the person's device [#on-the-persons-device]

The device that publishes reads the session's events with its client token. Feed them to the HUD, and end the session when the person presses Stop:

```html
<orgasm-hud layout="rail"></orgasm-hud>
```

```ts title="device.ts"
const hud = document.querySelector('orgasm-hud');
const live = await publishLiveSession({ session, capability, stream });
live.subscribe({ frames: ['face'], onEvent: (event) => hud.feed(event), onFaceFrame: (frame) => hud.feedFrame(frame) });
hud.addEventListener('orgasm-hud-stop', async () => {
  await live.stop({ releaseCamera: true });
  await fetch('/api/session/end', { method: 'POST' }); // your server ends it with the secret key
});
```

A page that only displays the session can let the HUD subscribe itself: `hud.connect({ streamUrl, token })`, which asks for face frames when the HUD shows the face. `orgasm-hud-phase` fires on each change of phase, with `phase`, `previous` and the whole `view` in its `detail`.

If your product drives a device, report it as it changes, and the HUD shows it beside the person's signals. The HUD only displays the device; your own controls set it.

```ts title="device.ts"
live.reportStimulation({ state: 'on', level: 31, levelMax: 60, mode: 'waves', device: { label: 'Unit' } });
```

### The whole panel [#the-whole-panel]

`layout="panel"` is the whole display: the phase, the gauge and the device's strip over three pages, Signals, Face and Timeline, turned with tabs or a swipe. Pick the first with `page="face"`.

<HudDemo layout="panel" scenario="edge" caption="The edge scenario with a scripted two-channel device: its level follows the person, it is held near the edge, and its mode changes as imminence rises." />

### A siderail [#a-siderail]

`layout="rail"` is a panel down the side of a page, beside a video or a scene: every part but the subject read, the face and the timeline, which you can add with `show`.

```html
<aside style="position: fixed; top: 80px; right: 16px; width: 320px">
  <orgasm-hud layout="rail"></orgasm-hud>
</aside>
```

### A bottom bar [#a-bottom-bar]

`layout="bar"` is a strip across the page: the phase, the gauge, the device, the counts, the clock and the notices.

<HudDemo layout="bar" scenario="finish" />

### A card in a game [#a-card-in-a-game]

`layout="card"` sits in a corner of a game or a scene, with the phase and the chance only.

<HudDemo layout="card" scenario="ruin" />

## On another screen [#on-another-screen]

A display that someone else watches, such as a coach's view, a second monitor or a stream, reads with a **view token** instead of the client token. Your server makes one per screen:

```ts title="server.ts"
const response = await fetch(`https://orgasm.dev/v1/live-sessions/${session.id}/view-tokens`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.ORGASM_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ expiresInS: 3 * 3600 }),
});
const { token } = await response.json(); // vt_…, shown only now
```

```ts title="screen.ts"
hud.connect({ streamUrl: session.results.streamUrl, token }); // sent in a header, never in the URL
```

A view token reads the session's display events and nothing else. It cannot read the session object with its metadata and references, and it cannot report stimulation. The subject read is left out unless you pass `includeSubject: true`, and the face's channels unless you pass `includeFace: true`: without them a `face` part shows nothing. The token stops at its `expiresAt` or five minutes after the session ends, whichever comes first ([`createViewToken`](/docs/api/live-sessions/createViewToken)).

Give a screen other than the person's the `stream` attribute, or use `layout="overlay"`, which implies it. Both leave out the indicator and the Stop control, which belong on the person's own device.

<HudDemo layout="overlay" scenario="edge" theme="dark" />

## In a game engine [#in-a-game-engine]

To draw the HUD natively, use the model the element draws. `hudReducer` folds each event into a state, and `hudView` turns the state into what to show, as plain data, as often as you draw:

```ts
import { subscribe, streamOf } from '@orgasm-dev/device';
import { hudFrameReducer, hudReducer, hudView, initialHudState, loadFaceMesh, poseFace } from '@orgasm-dev/device/hud';

let state = initialHudState();
subscribe({
  ...streamOf(session),
  frames: ['face'],
  onEvent: (event) => (state = hudReducer(state, event, Date.now())),
  onFaceFrame: (face) => (state = hudFrameReducer(state, face, Date.now())),
});
const mesh = await loadFaceMesh(); // the generic face, about 40 KB, fetched once

function frame() {
  const view = hudView(state, Date.now());
  // view.word, view.gauge.p30, view.trend.points, view.counts, view.clock.text, view.notices, view.signals,
  // view.stimulation (the strip), view.timeline (its lanes as points 0 to 1), view.face (its channels, regions and cameraHead)
  const face = view.face;
  // x, y per point, the head 1000 tall, turned as the camera sees it where a frame says so
  const points = face?.channels ? poseFace(mesh, face.channels, undefined, undefined, { cameraHead: face.cameraHead }) : null;
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);
```

Between frames, `headGlideTo` and `headAt` glide `cameraHead` the short way round, as `glideTo` and `faceAt` glide the channels.

An engine that does not run JavaScript reads the [stream](/docs/guides/realtime) itself. The model's source, held to the sandbox's scenarios by golden files, is the reference for the phases, how long each call holds the display, and when a reading counts as stale.

## Theme and words [#theme-and-words]

- `theme="dark"` (the default), `"light"` or `"auto"`, which follows the page's preference. `size` is `"sm"`, `"md"` or `"lg"`, and `brand="off"` hides the orgasm.dev mark.
- CSS custom properties restyle it: `--orgasm-hud-accent`, `--orgasm-hud-surface`, `--orgasm-hud-text`, `--orgasm-hud-muted`, `--orgasm-hud-font` and the others.
- `show` picks the parts, from `phase gauge percent trend counts clock signals notices subject stimulation face timeline`.
- `hud.strings` rewords any of it, for another language or your product's voice: `hud.strings = { phases: { close: 'Nearly there' } }`.

```css title="styles.css"
orgasm-hud {
  --orgasm-hud-accent: #ff4f8b;
  --orgasm-hud-font: 'Inter', system-ui, sans-serif;
}
```

## Accessibility [#accessibility]

The gauge is a `meter` whose value text gives the phase and the chance in words. Each change of phase is announced politely, once; nothing else is. When the system asks for reduced motion, nothing eases or pulses.

## Without a camera [#without-a-camera]

- `hud.demo({ scenario: 'edge' })` plays a scripted session in the browser with no network, a face and a scripted device included: `edge`, `finish`, `ruin` or `face-lost`.
- A [sandbox](/docs/guides/sandbox) session with `speed: 1` plays in real time against the API with a test key, so the whole loop, the HUD included, works before any camera is involved.


---

# Live sessions (https://orgasm.dev/docs/guides/live-sessions)

A live session is one person's camera stream, analysed as it arrives. Three parties take part: **your server**, which holds the secret key; **the person's device**, which films them and publishes; and **orgasm.dev**, which analyses the stream in an enclave and sends events.

```mermaid
sequenceDiagram
  participant Device as Device
  participant Server as Your server
  participant API as orgasm.dev
  participant Enclave as Enclave
  Device->>Device: capability = 32 random bytes
  Device->>Server: SHA-256(capability)
  Server->>API: POST /v1/live-sessions {consent, capabilityHash, inputs}
  API-->>Server: session: ingest, results.clientToken
  Server-->>Device: ingest, clientToken
  Device->>Enclave: GET attestation, check policy
  Device->>Enclave: WHIP offer, sealed with the capability
  Enclave-->>Device: answer, signed by the enclave
  Device->>Enclave: camera + microphone (WebRTC)
  API-->>Device: events (stream, clientToken)
  API-->>Server: events (stream or webhooks)
  Server->>API: DELETE /v1/live-sessions/{id}
```

## 1. On the device: a capability [#1-on-the-device-a-capability]

The device generates a secret only it will hold, and sends your server its hash.

```ts title="device.ts"
const bytes = crypto.getRandomValues(new Uint8Array(32));
const capability = btoa(String.fromCharCode(...bytes)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
const digest = await crypto.subtle.digest('SHA-256', bytes);
const capabilityHash = [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
// keep `capability` on the device; send `capabilityHash` to your server
```

## 2. On your server: create the session [#2-on-your-server-create-the-session]

```ts title="server.ts"
const response = await fetch('https://orgasm.dev/v1/live-sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORGASM_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    consent: {
      subjectIsAdult: true, // only when your product verified it
      subjectConsented: true, // only when the person agreed to this analysis
      ageVerification: 'third_party_service',
      consentedAt: user.consentedAt,
      consentRecordId: user.consentRecordId,
    },
    capabilityHash, // from the device
    inputs: { audio: true, body: false },
    maxDurationS: 3600,
    retentionDays: 7,
    userReference, // your pseudonymous id for the person, never their email
    clientReferenceId: `booking_${booking.id}`,
  }),
});
const session = await response.json();
// hand session.ingest and session.results.clientToken to the device
```

`capabilityHash` is required with live keys. `subjectHint` (`woman` or `man`) is optional: give it only when the person told you ([subject](/docs/concepts/subject)).

`userReference` and `clientReferenceId` are optional too: your own pseudonymous id for the person and your id for the session. They come back on the session and on each of its charges, so your finance team sees what each user and session cost ([cost attribution](/docs/credits#cost-attribution)), and [`listLiveSessions`](/docs/api/live-sessions/listLiveSessions) filters by either.

The session starts in `starting` while analysis capacity is prepared. That takes a few minutes when none is warm; `503 capacity_unavailable` means none is free, and `Retry-After` says when to try again.

## 3. On the device: verify, then publish [#3-on-the-device-verify-then-publish]

The device checks the enclave before sending it anything, then publishes its front camera and microphone over WHIP:

1. `GET ingest.attestationUrl`, and check the token against the [attestation policy](/docs/api/trust/getAttestationPolicy).
2. Create an `RTCPeerConnection` with the camera and microphone tracks, using `ingest.iceServersUrl` on strict networks.
3. `POST` the SDP offer to `ingest.url`, sealed with the capability (`ingest.seal`).
4. Verify the enclave's signature on the answer, then apply it.

The device SDK does all four, and its [source is public](https://github.com/Orgasm-dev/device-sdk) (Apache-2.0). Each release on npm is built from that repository with provenance, which `npm audit signatures` checks:

```sh title="Terminal"
npm install @orgasm-dev/device
npm audit signatures
```

```ts title="device.ts"
import { publishLiveSession } from '@orgasm-dev/device';
import { requestCapture } from '@orgasm-dev/device/capture';

const { stream } = await requestCapture(); // from a click: the front camera and the microphone
const live = await publishLiveSession({ session, capability, stream }); // throws AttestationRefused, sending nothing, if the enclave does not verify
```

Ask for the camera after explaining why: `<orgasm-capture-primer>` says what is measured, why the camera and why the microphone, and who receives the readings, then asks, and names any refusal with what to do about it ([camera and microphone](/docs/guides/capture)).

Video must be H.264 or H.265; see [inputs](/docs/concepts/inputs) for framing. With `inputs.body`, publish the body view to `ingest.bodyUrl` the same way.

## 4. Read the events [#4-read-the-events]

Anywhere that suits you; all carry the same events ([realtime](/docs/guides/realtime)):

- **On the device**: `live.subscribe({ onEvent })`, which reads the stream with the client token in a header. The client token reads this session only, and stops working five minutes after it ends. [Show the HUD](/docs/guides/hud) to the person with the same events.
- **On another screen**: a read-only view token from [`createViewToken`](/docs/api/live-sessions/createViewToken), one per screen.
- **On your server**: the stream with the secret key, [webhooks](/docs/guides/webhooks), or `listLiveSessionEvents` with `wait`.

If your product controls stimulation, report each change with `reportStimulation` (from your server or, with the client token, from the device), or `live.reportStimulation`, which sends it over the session's WebSocket. With the device's level, channels and mode in the report, every reader receives them as `stimulation.updated`, and the HUD shows the device ([reporting the device](/docs/guides/realtime#reporting-the-device)).

## 5. End it [#5-end-it]

```ts
await fetch(`https://orgasm.dev/v1/live-sessions/${session.id}`, { method: 'DELETE', headers: { Authorization: `Bearer ${process.env.ORGASM_KEY}` } });
```

A final `session.status` with `status: ended` closes every stream. The events stay readable until `resultsExpireAt`; `purgeLiveSession` deletes them now.

## Status [#status]

```mermaid
stateDiagram-v2
  [*] --> starting
  starting --> ready: capacity is up
  ready --> calibrating: media arrives
  calibrating --> analyzing: baseline in (about a minute)
  analyzing --> ended
  calibrating --> ended
  ready --> ended
  starting --> ended
  ended --> [*]
```

`endedReason` says why it ended: `client_ended`, `media_ended` (the device hung up), `media_timeout`, `max_duration`, `interrupted` (capacity was lost; create a new session), `policy` or `error`. `degraded` is true while a declared input is missing or the face is out of view; the open `input.warning` events say which, and `session.status` reports each change.


---

# Your own GPUs (https://orgasm.dev/docs/guides/own-gpus)

<Callout title="Early access">
  We are starting with a few design partners. Sign in and open [Your GPUs](/dashboard/compute) in your console to ask: name your Google Cloud project and its slots, and the page walks you through the rest once your project is approved.
</Callout>

The enclave that analyses live sessions is a public image anyone can run. With your own GPUs, it runs in your Google Cloud project, on your network, and orgasm.dev's API leases it for your sessions: the same keys, the same sessions, the same events and webhooks, with the media decrypted only in your project.

```mermaid
flowchart LR
  subgraph project [Your Google Cloud project and VPC]
    enclave["Enclave: the released image, on Intel TDX and an H100"]
  end
  device["The person's device, with the SDK"] -->|"verifies the attestation, then sealed media"| enclave
  server["Your server"] -->|"secret key: create the session"| api["orgasm.dev"]
  api -->|"control, pinned to the attested TLS key"| enclave
  enclave -->|"signed readings, never media"| api
  api -->|"events and webhooks"| server
```

## What stays in your project [#what-stays-in-your-project]

- **The enclave and the media.** The person's device publishes straight to an enclave in your project; orgasm.dev's servers and relays never carry it.
- **Your capacity.** The machines are yours, in your region, so your sessions never wait on a shared fleet.

## What orgasm.dev still does [#what-orgasmdev-still-does]

- Your keys, sessions, events, webhooks and usage, as with any live session.
- Leasing your enclaves to your sessions. Before each session, orgasm.dev asks the enclave for an attestation minted for that session and holds it to your project's values. Then it controls the enclave over a connection pinned to the TLS key that attestation names.
- Releasing the detectors to your enclaves. Only an enclave that proves all of this receives them: a released image, in production posture, on confidential hardware, in your approved project, reporting to orgasm.dev, and keeping no record.

## What nobody can do, you included [#what-nobody-can-do-you-included]

Owning the project lets you start, stop and name the machines. It does not let anyone read a session:

- The device verifies each enclave before it sends a frame, exactly as it does on orgasm.dev's fleet: the release signing key, the release, the hardware and debugging off since boot. A modified image is refused.
- The enclave's memory, its keys and the detectors in it cannot be read from the project. Its readings are signed with a key that never leaves it, and orgasm.dev takes none that is not.
- An enclave that would keep a record of the session never receives the detectors.

That is the point: your users can be told, and shown, that their video is analysed in a machine even you cannot see into.

## What you need [#what-you-need]

- A Google Cloud project with quota for `a3-highgpu-1g` Spot machines (one NVIDIA H100 each) as Confidential VMs, in a zone that offers them.
- A VPC and a subnet in each region your slots are in, and a public address for each slot, so devices can reach it.
- A domain name for each slot. Each enclave obtains its own certificate for its name at boot, so the name must point at the slot's address.
- Terraform, and the enclave release v0.20.0 or later, whose readings are signed.

## Set it up [#set-it-up]

<Steps>
<Step>

**Ask.** In [Your GPUs](/dashboard/compute), name your project and each slot's zone and DNS name. The slots will run as the account `enclave-slot-vm@<your project>.iam.gserviceaccount.com`.

</Step>
<Step>

**Approval.** The enclave's operator approves your project and that account for orgasm.dev as their controller. Your console then shows your deployment's `terraform.tfvars`, with everything it needs.

</Step>
<Step>

**Deploy.** From the enclave's source at its release tag, with the tfvars from your console and your VPC and subnet filled in:

```sh title="Terminal"
git clone --depth 1 --branch v0.20.0 https://github.com/Masseuse-ai/masseuse-video-tee enclave
cd enclave/deploy/own-project
terraform init && terraform apply
```

It creates the slots, their account, addresses and firewall rules on your network, and lets each enclave obtain its certificate in your project. [The module](https://github.com/Masseuse-ai/masseuse-video-tee/tree/master/terraform/modules/slot) is the same machine orgasm.dev's fleet runs.

</Step>
<Step>

**Point DNS** at each slot's address (`terraform output slots`).

</Step>
<Step>

**Verify.** With a slot up, run the `tee-verify` command your console prints for it ([Verify the enclave](/docs/guides/verify)). It passes only for a released image, signed, with its SLSA provenance, in production posture, on this hardware, reporting to orgasm.dev and keeping no record.

</Step>
<Step>

**Route.** Your live sessions go to your slots first and to orgasm.dev's fleet when none of yours is free or passes its checks. Choose your slots only and a session that none of them can take is refused with `capacity_unavailable`. Each session's [receipt](/docs/guides/verify#read-a-sessions-receipt) names the project its enclave ran in.

</Step>
</Steps>

## Releases and leaving [#releases-and-leaving]

Your approval covers the release digests it names. To move to a newer release, ask in your console. Once the digest is approved, change `container_image` to it and apply.

To leave, withdraw in your console and run `terraform destroy`. Withdrawing sends your sessions back to orgasm.dev's fleet at once. Once the operator removes your project, your slots can no longer read the detectors.


---

# Realtime (https://orgasm.dev/docs/guides/realtime)

Every live session's events reach you four ways. They carry the same event objects; pick by where your code runs.

| Channel | Use it from | Notes |
| --- | --- | --- |
| Server-sent events (`results.streamUrl`) | Browsers, devices, servers | The device SDK's `subscribe` reads it with the token in a header |
| WebSocket (`results.websocketUrl`) | Devices and servers that also report a device | Events out, `stimulation` reports in, over one connection |
| Webhooks | Your server | Every type but `imminence.updated`, `signals.updated` and `stimulation.updated`; see [webhooks](/docs/guides/webhooks) |
| Long polling (`listLiveSessionEvents` with `wait`) | Agents, serverless functions | One request per batch |

## In the browser: `subscribe` [#in-the-browser-subscribe]

```ts title="device.ts"
import { subscribe, streamOf } from '@orgasm-dev/device';

const subscription = subscribe({
  ...streamOf(session), // results.streamUrl and the client token
  onEvent: (event) => {
    if (event.type === 'imminence.updated') meter.value = event.data.p30 ?? 0;
    if (event.type === 'orgasm.onset') onOnset(event);
  },
  onState: (state) => (status.textContent = state), // connecting, open, reconnecting, ended, refused, closed
});
// subscription.close() to stop reading
```

`subscribe` sends the token in `Authorization`, so it never sits in a URL or a server log. It delivers each event once and in order, resumes from the last event after a dropped connection, reports a gap in `sequence` through `onGap`, and ends by itself after the final `session.status`. A token that no longer works ends it with `refused` instead of retrying. On the device that publishes, `live.subscribe(...)` does the same for its session, and [the HUD](/docs/guides/hud) is built on it.

## Server-sent events [#server-sent-events]

Any SSE client reads the stream:

```ts title="browser.ts"
const source = new EventSource(`${session.results.streamUrl}?token=${clientToken}`);
source.addEventListener('imminence.updated', (message) => {
  meter.value = JSON.parse(message.data).data.p30 ?? 0;
});
source.addEventListener('session.status', (message) => {
  if (JSON.parse(message.data).data.status === 'ended') source.close();
});
```

Each message's `id:` is the event `id`, and `event:` its `type`. A comment line every 15 seconds keeps proxies from closing the connection. Filter with `?types=orgasm.onset,orgasm.peak,orgasm.end`. On a server, send the secret key in `Authorization`. `EventSource` can't set headers, so it is the one reader that puts a client token in the URL, as `token`; a view token is never accepted there.

## The WebSocket [#the-websocket]

The socket carries the same events as the stream, one JSON text frame each in `sequence` order, and takes your product's stimulation reports the other way. Connect with `?token=` and the session's client token, or, where your client can set headers, `Authorization: Bearer` with the secret key or the client token. A view token never goes in a URL, so view tokens read the stream instead.

```ts title="device.ts"
const socket = new WebSocket(`${session.results.websocketUrl}?token=${clientToken}&types=imminence.updated,session.status`);
socket.onmessage = (message) => {
  const event = JSON.parse(message.data);
  if (event.type === 'imminence.updated') meter.value = event.data.p30 ?? 0;
};
// the toy's level changed
socket.send(JSON.stringify({ action: 'stimulation', state: 'on', level: 34, levelMax: 60, mode: 'waves' }));
```

- `?after=` replays from an event, `?types=` filters, and `?frames=face` adds [face frames](#face-frames).
- The client sends `stimulation`, the same report as [`reportStimulation`](/docs/api/live-sessions/reportStimulation), and `resume` with an `after` to replay without reconnecting. A message it can't take is answered with a `socket.error` frame (`invalid_message`, `unknown_action`, `session_ended`), and the socket stays open.
- It closes with `1000` after the session's final status, `1008` when its token stops working, and `1013` when the session already has its 12 readers.

## Reporting the device [#reporting-the-device]

If your product drives a device, tell orgasm.dev what it is doing: on or off, its `level` and the most it will go to (`levelMax`), each output's level for a device with more than one (`channels`, up to four), its `mode` and `modeLabel`, who sets the level (`drive`: `auto`, `manual`, `hold` or `paused`), and whether it is `connected`. A report updates the fields it carries and keeps the rest; `null` clears one. `state` alone is enough for imminence to account for time under stimulation, and for a stop to make an orgasm a ruin ([presets](/docs/concepts/presets)).

Each report reaches every reader of the session as `stimulation.updated`, at most four a second, reports in between merged into the next: a [HUD](/docs/guides/hud) shows it as the stimulation strip and a lane of its timeline. The SDK does the merging and the pacing for you, over the socket while it is open and over HTTP while it is not:

```ts title="device.ts"
live.reportStimulation({ state: 'on', level: 31, levelMax: 60, channels: [{ id: 'a', level: 31 }, { id: 'b', level: 24 }], mode: 'waves', device: { label: 'Unit' } });
live.reportStimulation({ state: 'on', level: 34 }); // only the level changed
```

On your server, `stimulationReporter({ ...reporterOf(session), token: process.env.ORGASM_KEY })` does the same over HTTP, since a secret key never goes in a URL. Report changes, not a heartbeat. The device's name is what a display shows: never the person's.

## Face frames [#face-frames]

`signals.updated` carries the face's 24 expression channels and the head's turn once a second (`face`). A display that draws the face, like the HUD's `face` part, can ask for them about five times a second as well: add `frames=face` to the stream or the socket, or pass `frames: ['face']` to `subscribe`.

```ts title="device.ts"
subscribe({ ...streamOf(session), frames: ['face'], onEvent: (event) => hud.feed(event), onFaceFrame: (frame) => hud.feedFrame(frame) });
```

A `face.frame` is not an event: it has no `id` or `sequence`, is never stored, replayed or sent to webhooks, and a reader that falls behind skips to the newest. Its `face` is `null` while the face is out of view and before the baseline is in.

A frame also carries `cameraHead`: the head as the camera sees it (`yawDeg` and `rollDeg` within 180, `pitchDeg` within 90, with `head`'s senses), not its turn from the resting pose. A head held tilted through the baseline minute, or lying on its side, reads as it is, where `head` reads it as rest. It needs no baseline, so it arrives as soon as the face is in view; it is `null` while the face is out of view, and a frame without it is read the same way. Draw the head by `cameraHead` where a frame has it, and by `face.head` otherwise.

## Another screen: view tokens [#another-screen-view-tokens]

A screen other than the person's device, such as a coach's view, a second monitor or a stream overlay, reads with a view token. Your server creates one per screen with [`createViewToken`](/docs/api/live-sessions/createViewToken) and hands it over; the screen reads with `subscribe` or the HUD's `connect`.

```ts title="server.ts"
const view = await fetch(`https://orgasm.dev/v1/live-sessions/${session.id}/view-tokens`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.ORGASM_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ expiresInS: 3600 }),
}).then((response) => response.json());
// view.token is vt_…; view.eventTypes lists what it reads
```

It reads the stream and the event list, with the token in the header only, and only the display's events: imminence and the other signals, the device's `stimulation.updated`, the calls, edges, warnings and statuses. The subject read is included only when the token is created with `includeSubject: true`, and the face's channels, in `signals.updated` and as frames, only with `includeFace: true`: a screen others watch should not show either unasked. It can't read the session object, its metadata or its references, and can't report stimulation.

## Long polling [#long-polling]

```bash
curl -s "https://orgasm.dev/v1/live-sessions/ls_…/events?after=evt_…&types=orgasm.onset,orgasm.peak,orgasm.end&wait=30" \
  -H "Authorization: Bearer $ORGASM_KEY"
```

The request returns as soon as a matching event exists after `after`, or after `wait` seconds with an empty `data`. Pass `nextCursor` back as `after` next time. The action MCP server's `wait_for_event` is this loop.

## Resuming [#resuming]

Connections drop. Nothing is lost if you resume from the last event you processed:

- **`subscribe`** resumes by itself.
- **Server-sent events**: browsers send `Last-Event-ID` automatically on reconnect; elsewhere send it yourself, or `?after=`.
- **The socket**: reconnect with `?after=` and the last event's `id`, or send `resume` on an open socket.
- **Long polling**: always pass `after`.

Missed events are replayed first, in `sequence` order. Deduplicate on `id` regardless; delivery is at least once.

## Limits [#limits]

- A session serves at most 12 streams at once, sockets included, whoever reads them; another stream is refused with `429 rate_limited`, another socket with a `socket.error` and `1013`, until one closes.
- A stream or socket is closed after an hour; reconnect after the last event, as `subscribe` does by itself.
- Client and view tokens stop working five minutes after the session ends, which leaves time to read its final events. A view token stops sooner at its own `expiresAt`.

## Which to choose [#which-to-choose]

- A **browser experience** that reacts on screen: `subscribe` with the client token, or the [HUD](/docs/guides/hud).
- A **game**: `subscribe` where it runs JavaScript; a native engine reads the stream with its own HTTP client.
- A **product that drives a device**: the socket, which reads the events and takes the device's reports over one connection, or `live.reportStimulation` beside `subscribe`.
- **Another screen**: a view token.
- A **backend** that records outcomes: webhooks for calls, plus the stream if it needs imminence.
- An **agent**: long polling, or `wait_for_event` over MCP.


---

# Recordings (https://orgasm.dev/docs/guides/recordings)

A recording is a video file analysed after the fact. It is a separate endpoint from live sessions, and it returns the same events as a timeline.

<Callout title="Status">
  Recordings are analysed in the sandbox only for now, with a key that starts with `sk_test_`. With a live key, `createRecording` answers `live_mode_unavailable`; [live sessions](/docs/guides/live-sessions) are open.
</Callout>

## Requirements [#requirements]

- The person's face, in view, in H.264 or H.265 video.
- Between two minutes and four hours. The first minute is the person's baseline.
- The audio track, if you want onset, peak and end (`inputs.audio`, true by default).
- A recording of a person who agreed to this analysis of it ([acceptable use](/docs/concepts/compliance)).

## Submit by upload [#submit-by-upload]

```bash
curl -s https://orgasm.dev/v1/recordings \
  -H "Authorization: Bearer $ORGASM_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "consent": { "subjectIsAdult": true, "subjectConsented": true, "ageVerification": "document" },
    "source": { "type": "upload" }
  }'
```

The recording comes back `awaiting_upload`, with `uploads.face`: a URL, a method (`PUT`), headers, a size limit and an expiry. In live mode `uploads.face.sealed` is true: the SDK seals the file to the enclave before it leaves the device, so only the enclave can read it.

```bash
curl -X PUT --data-binary @session.mp4 -H "Content-Type: video/mp4" "<uploads.face.url>"
```

With `source.bodyView: true` you also upload a body video to `uploads.body`; `bodyOffsetS` says how many seconds after the face video it starts.

## Submit by URL [#submit-by-url]

```json
{
  "consent": { "subjectIsAdult": true, "subjectConsented": true, "ageVerification": "payment_card" },
  "source": { "type": "url", "url": "https://storage.example.com/sessions/1842.mp4?signature=…" }
}
```

The enclave fetches the file itself. Give a signed URL valid for at least an hour; the stored `source.url` drops its query string.

## Processing [#processing]

`awaiting_upload` → `queued` → `processing` → `completed` (or `failed`). Processing takes about as long as the recording. While it runs, `progress.processedS` counts up, and `listRecordingEvents` already returns what has been analysed.

When it finishes, a `recording.completed` webhook is sent to subscribed endpoints, and `getRecording` returns `result`:

- `subject`: the subject read.
- `summary`: the recording's length and one entry per orgasm: its onset, peak and end, its duration, the detectors that called it, and its confidence.
- `timeline`: the discrete events in order (orgasm calls, the subject read, input warnings).

Imminence for every second of analysed face is in `listRecordingEvents`; filter it with `types=imminence.updated`.

## Failure [#failure]

`recording.failed` and `failure.code` say why: `unreadable_media`, `no_face`, `too_short`, `too_long`, `fetch_failed`, `upload_expired` or `internal` (submit it again).

## Deletion [#deletion]

The video is deleted once analysed. `deleteRecording` deletes the result and the events now; otherwise they go at `resultsExpireAt` (`retentionDays`, 30 by default).

## In the sandbox [#in-the-sandbox]

The upload URL points at the sandbox, which reads and discards the bytes, then plays `sandbox.scenario` at `sandbox.speed` (60 by default, so a 13-minute scenario completes in 13 seconds). Upload any small video file, never a real recording of a person.


---

# Sandbox (https://orgasm.dev/docs/guides/sandbox)

Any key that starts with `sk_test_` reaches the sandbox. It answers the whole contract, and its sessions and recordings play **scenarios**: scripted, deterministic event timelines, the same ones that generate the examples throughout these docs. The same scenario always produces the same events.

## Choosing a scenario [#choosing-a-scenario]

```json
{ "sandbox": { "scenario": "man-peak", "speed": 20 } }
```

`scenario` defaults to `woman-onset-end`. `speed` plays it faster than real time, from 1 to 60: 10 by default for live sessions, 60 for recordings. Stream times in events stay on the scenario's own clock, so a call at `streamTimeS: 704.2` arrives about 35 seconds in at speed 20.

`subjectHint` and `inputs` apply as they would live: a `man` hint on a woman's scenario suppresses its onset and end calls, and `inputs.audio: false` leaves only imminence and the subject read.

## The scenarios [#the-scenarios]

### woman-onset-end [#woman-onset-end]

**A woman's orgasm: onset, then end** (sandbox scenario `woman-onset-end`). The face reads as a woman’s after about 30 seconds, imminence climbs over nine minutes, and the onset and end of one orgasm are called a few seconds after each happens.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.019 | 0.037 |
| 122 | 0.025 | 0.049 |
| 182 | 0.029 | 0.058 |
| 242 | 0.048 | 0.094 |
| 302 | 0.052 | 0.102 |
| 362 | 0.117 | 0.22 |
| 422 | 0.14 | 0.261 |
| 482 | 0.322 | 0.541 |
| 542 | 0.868 | 0.983 |
| 602 | 0.087 | 0.167 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.onset` | orgasm 1 at 538 s, lag 4.6 s, score 0.71 |
| `orgasm.end` | orgasm 1 at 575 s, lasted 37 s, onset_end, lag 5.2 s |

| sequence | streamTimeS | type | confidence | data |
| --- | --- | --- | --- | --- |
| 1 | 0 | `session.status` | — | ready |
| 2 | 0 | `session.status` | — | calibrating |
| 3 | 0 | `input.warning` | — | baseline_pending raised |
| 4 | 32 | `subject.identified` | high | woman, pWoman 0.94, detectors onset_end |
| 5 | 62 | `session.status` | — | analyzing |
| 6 | 62 | `input.warning` | — | baseline_pending cleared |
| 969 | 542.6 | `orgasm.onset` | high | orgasm 1 at 538 s, lag 4.6 s, score 0.71 |
| 1046 | 580.2 | `orgasm.end` | high | orgasm 1 at 575 s, lasted 37 s, onset_end, lag 5.2 s |
| 1205 | 660 | `session.status` | — | ended, media_ended |

### man-peak [#man-peak]

**A man's orgasm: peak, then end** (sandbox scenario `man-peak`). The face reads as a man’s, imminence climbs to a peak, which is called about three seconds after it happens; the end is then read from his face.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.01 | 0.02 |
| 122 | 0.017 | 0.033 |
| 182 | 0.025 | 0.05 |
| 242 | 0.043 | 0.084 |
| 302 | 0.074 | 0.142 |
| 362 | 0.086 | 0.165 |
| 422 | 0.125 | 0.234 |
| 482 | 0.206 | 0.369 |
| 542 | 0.285 | 0.488 |
| 602 | 0.467 | 0.716 |
| 662 | 0.667 | 0.889 |
| 722 | 0.318 | 0.535 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.peak` | orgasm 1 at 701 s, lag 3.2 s, score 0.66 |
| `orgasm.end` | orgasm 1 at 742 s, lasted 41 s, face_end, lag 3.5 s |

| sequence | streamTimeS | type | confidence | data |
| --- | --- | --- | --- | --- |
| 1 | 0 | `session.status` | — | ready |
| 2 | 0 | `session.status` | — | calibrating |
| 3 | 0 | `input.warning` | — | baseline_pending raised |
| 4 | 31 | `subject.identified` | high | man, pWoman 0.07, detectors peak, face_end |
| 5 | 62 | `session.status` | — | analyzing |
| 6 | 62 | `input.warning` | — | baseline_pending cleared |
| 1293 | 704.2 | `orgasm.peak` | high | orgasm 1 at 701 s, lag 3.2 s, score 0.66 |
| 1376 | 745.5 | `orgasm.end` | high | orgasm 1 at 742 s, lasted 41 s, face_end, lag 3.5 s |
| 1445 | 780 | `session.status` | — | ended, media_ended |

### undetermined [#undetermined]

**Subject undetermined: every detector runs** (sandbox scenario `undetermined`). The face read stays undetermined, so the onset-and-end detector and the peak detector both run, and their calls arrive with low confidence and a shared orgasm index.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.022 | 0.043 |
| 122 | 0.024 | 0.047 |
| 182 | 0.047 | 0.092 |
| 242 | 0.056 | 0.11 |
| 302 | 0.077 | 0.147 |
| 362 | 0.132 | 0.247 |
| 422 | 0.172 | 0.315 |
| 482 | 0.279 | 0.481 |
| 542 | 0.446 | 0.693 |
| 602 | 0.769 | 0.947 |
| 662 | 0.103 | 0.196 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.onset` | orgasm 1 at 590 s, lag 5.1 s, score 0.58 |
| `orgasm.peak` | orgasm 1 at 596 s, lag 3.4 s, score 0.55 |
| `orgasm.end` | orgasm 1 at 624 s, lasted 34 s, onset_end, lag 5.3 s |

### face-only [#face-only]

**Face only: no microphone** (sandbox scenario `face-only`). The device publishes the camera without the microphone: imminence and the subject read arrive, onset, peak and end cannot, and an audio warning says why. With no orgasm called, the approach that recedes counts as an edge.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.018 | 0.036 |
| 122 | 0.035 | 0.069 |
| 182 | 0.042 | 0.083 |
| 242 | 0.064 | 0.124 |
| 302 | 0.156 | 0.287 |
| 362 | 0.173 | 0.317 |
| 422 | 0.386 | 0.624 |
| 482 | 0.757 | 0.941 |
| 542 | 0.241 | 0.424 |

### face-lost [#face-lost]

**Face lost for 20 seconds** (sandbox scenario `face-lost`). The face leaves the frame at five minutes: imminence goes null, a warning is raised and the session is degraded until the face returns 20 seconds later.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.019 | 0.038 |
| 122 | 0.032 | 0.062 |
| 182 | 0.044 | 0.086 |
| 242 | 0.067 | 0.13 |
| 302 | null | null |
| 362 | 0.161 | 0.296 |
| 422 | 0.301 | 0.512 |
| 482 | 0.518 | 0.767 |
| 542 | 0.512 | 0.761 |
| 602 | 0.081 | 0.156 |
| 662 | 0.034 | 0.067 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.onset` | orgasm 1 at 520 s, lag 4.8 s, score 0.69 |
| `orgasm.end` | orgasm 1 at 556 s, lasted 36 s, onset_end, lag 5.4 s |

| sequence | streamTimeS | type | confidence | data |
| --- | --- | --- | --- | --- |
| 1 | 0 | `session.status` | — | ready |
| 2 | 0 | `session.status` | — | calibrating |
| 3 | 0 | `input.warning` | — | baseline_pending raised |
| 4 | 31 | `subject.identified` | high | woman, pWoman 0.89, detectors onset_end |
| 5 | 62 | `session.status` | — | analyzing |
| 6 | 62 | `input.warning` | — | baseline_pending cleared |
| 483 | 300 | `input.warning` | — | face_not_visible raised |
| 484 | 300 | `session.status` | — | analyzing, degraded |
| 525 | 320 | `input.warning` | — | face_not_visible cleared |
| 526 | 320 | `session.status` | — | analyzing |
| 937 | 524.8 | `orgasm.onset` | high | orgasm 1 at 520 s, lag 4.8 s, score 0.69 |
| 1012 | 561.4 | `orgasm.end` | high | orgasm 1 at 556 s, lasted 36 s, onset_end, lag 5.4 s |
| 1289 | 700 | `session.status` | — | ended, media_ended |

### edge [#edge]

**Edge: three approaches, no orgasm** (sandbox scenario `edge`). Imminence rises past the hold and back-off levels three times and falls each time stimulation is backed off, and the session ends without an orgasm: three edges, each an edge.completed.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.02 | 0.039 |
| 122 | 0.039 | 0.077 |
| 182 | 0.083 | 0.158 |
| 242 | 0.143 | 0.265 |
| 302 | 0.29 | 0.496 |
| 362 | 0.605 | 0.844 |
| 422 | 0.171 | 0.312 |
| 482 | 0.145 | 0.268 |
| 542 | 0.526 | 0.776 |
| 602 | 0.26 | 0.452 |
| 662 | 0.116 | 0.219 |
| 722 | 0.389 | 0.627 |
| 782 | 0.396 | 0.635 |
| 842 | 0.133 | 0.249 |

Each approach ends in an `edge.completed`:

| sequence | streamTimeS | type | confidence | data |
| --- | --- | --- | --- | --- |
| 1 | 0 | `session.status` | — | ready |
| 2 | 0 | `session.status` | — | calibrating |
| 3 | 0 | `input.warning` | — | baseline_pending raised |
| 4 | 31 | `subject.identified` | high | man, pWoman 0.05, detectors peak, face_end |
| 5 | 62 | `session.status` | — | analyzing |
| 6 | 62 | `input.warning` | — | baseline_pending cleared |
| 706 | 411 | `edge.completed` | high | edge 1: p30 0.6 at 362 s, peak 0.687, below 0.3 49 s later |
| 1067 | 591 | `edge.completed` | high | edge 2: p30 0.6 at 548 s, peak 0.669, below 0.3 43 s later |
| 1468 | 791 | `edge.completed` | high | edge 3: p30 0.6 at 747 s, peak 0.684, below 0.3 44 s later |
| 1686 | 900 | `session.status` | — | ended, media_ended |

### ruin [#ruin]

**Ruin: past the point of no return** (sandbox scenario `ruin`). Imminence crosses the stop level, stimulation is reported off for good, and the peak still comes a few seconds later: a ruined orgasm, whose end says so.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.023 | 0.045 |
| 122 | 0.028 | 0.054 |
| 182 | 0.049 | 0.095 |
| 242 | 0.069 | 0.134 |
| 302 | 0.074 | 0.142 |
| 362 | 0.146 | 0.27 |
| 422 | 0.306 | 0.518 |
| 482 | 0.319 | 0.536 |
| 542 | 0.558 | 0.804 |
| 602 | 0.819 | 0.967 |
| 662 | 0.119 | 0.223 |
| 722 | 0.053 | 0.104 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.peak` | orgasm 1 at 612 s, lag 3.3 s, score 0.57 |
| `orgasm.end` | orgasm 1 at 640 s, lasted 28 s, face_end, lag 3.9 s, ruined |

The scenario reports stimulation as a product running the [ruin preset](/docs/concepts/presets#ruin) would: on at the baseline, off where the preset stops. Its imminence is stimulation-aware from the baseline, and the orgasm's end says `ruined: true`.

| sequence | streamTimeS | type | confidence | data |
| --- | --- | --- | --- | --- |
| 1 | 0 | `session.status` | — | ready |
| 2 | 0 | `session.status` | — | calibrating |
| 3 | 0 | `input.warning` | — | baseline_pending raised |
| 4 | 31 | `subject.identified` | high | man, pWoman 0.08, detectors peak, face_end |
| 5 | 62 | `session.status` | — | analyzing |
| 6 | 62 | `input.warning` | — | baseline_pending cleared |
| 1115 | 615.3 | `orgasm.peak` | high | orgasm 1 at 612 s, lag 3.3 s, score 0.57 |
| 1172 | 643.9 | `orgasm.end` | high | orgasm 1 at 640 s, lasted 28 s, face_end, lag 3.9 s, ruined |
| 1445 | 780 | `session.status` | — | ended, media_ended |

### finish [#finish]

**Finish: two orgasms** (sandbox scenario `finish`). A build-up to an onset and an end, a second, shorter build-up, and a second onset and end, each with its own orgasm index.

Imminence each minute:

| streamTimeS | p30 | p60 |
| --- | --- | --- |
| 62 | 0.021 | 0.042 |
| 122 | 0.029 | 0.058 |
| 182 | 0.038 | 0.074 |
| 242 | 0.049 | 0.095 |
| 302 | 0.101 | 0.193 |
| 362 | 0.148 | 0.274 |
| 422 | 0.249 | 0.436 |
| 482 | 0.377 | 0.612 |
| 542 | 0.853 | 0.978 |
| 602 | 0.316 | 0.532 |
| 662 | 0.414 | 0.657 |

Orgasm calls:

| type | data |
| --- | --- |
| `orgasm.onset` | orgasm 1 at 541 s, lag 4.4 s, score 0.73 |
| `orgasm.end` | orgasm 1 at 571 s, lasted 30 s, onset_end, lag 5 s |
| `orgasm.onset` | orgasm 2 at 643 s, lag 4.2 s, score 0.67 |
| `orgasm.end` | orgasm 2 at 668 s, lasted 25 s, onset_end, lag 4.9 s |

## How the sandbox differs from live analysis [#how-the-sandbox-differs-from-live-analysis]

- **Free.** Sandbox sessions count orgasms, ruins and edges as live ones do, in their `charges` and your test usage, and draw no credits: `credits` stays 0. [Credits and billing](/docs/credits#testing-in-the-sandbox) says what each scenario counts.
- **No media.** A sandbox session starts its scenario as soon as it is created. `ingest.url` answers `501 sandbox_no_media`, and the attestation policy for test mode says there is nothing to verify.
- **Scripted.** Scenarios do not react to what you do. Reporting stimulation sets `stimulationAware` from then on but does not change the curve, or which orgasms are ruined.
- **Uploads are discarded.** Recording uploads are read and thrown away. Use any small video file, never a real recording of a person.
- **Thresholds are illustrative.** Detector `score` and `threshold` values are the sandbox's, not live operating points.
- **Usage, credits and API keys** answer with the examples in the contract.
- **State lives in memory.** Sessions, recordings and webhook endpoints last until the sandbox restarts.

## Running it yourself [#running-it-yourself]

From this repository, `npm run dev` serves the sandbox with the docs at `http://localhost:3000/v1`, and `npm run mock` serves it alone at `http://localhost:4010`, together with the WebSocket channel.


---

# Teams and roles (https://orgasm.dev/docs/guides/teams)

A company on orgasm.dev is its domain. The first person to sign in with an address at it becomes its Admin. After that, people join only when an Admin lets them in. Credits, API keys, webhook endpoints, live sessions and [your own GPUs](/docs/guides/own-gpus) belong to the company, not to whoever made them, so they stay when someone leaves.

## Roles [#roles]

| | Admin | Developer | Billing |
| --- | --- | --- | --- |
| API keys: create, roll, revoke | Yes | Yes | No |
| Webhook endpoints: add, edit, roll the secret, delete | Yes | Yes | No |
| Live sessions and usage | Yes | Yes | Usage only |
| Credits and the balance | Yes | Yes | Yes |
| Prices, costs in dollars, the statement, CSV exports | Yes | No | Yes |
| [Billing keys](#billing-keys) | Yes | No | Yes |
| Your GPUs | Change | Read | No |
| The team | Manage | Read | Read |
| The [activity log](#the-activity-log) | Yes | No | No |

A Developer sees how many credits the company has and what each session counted, not what they cost. A Billing member's console opens on Billing; it has no Overview, sandbox or secret keys.

## Joining [#joining]

- **Invitations.** In the console's Team tab, an Admin invites an address at the company's domain with a role. orgasm.dev emails the invitation link to the address, and the console shows the link too, to send yourself if the email doesn't arrive. The link works for 14 days, and only for that address, whatever its case. The person joins with the role when they sign in with Google or Apple as that address. An Admin can withdraw an invitation until then.
- **Requests.** Anyone else who signs in with an address at your domain is asked to request to join, and the company's Admins get an email about it. The request waits in the Team tab, where an Admin lets them in with a role or declines; the person gets an email with the answer. Someone declined may ask again.
- **Only the domain.** Only addresses at the company's domain can be invited or join. Personal addresses (Gmail, iCloud, Hide My Email) cannot sign in at all.

## Changing roles and removing people [#changing-roles-and-removing-people]

An Admin changes anyone's role, their own included, and removes members; anyone may leave. The company always keeps an Admin: the last one cannot leave or give up the role until someone else is an Admin.

Removing someone takes effect on their next request. Keys they made stay with the company and keep working, marked with who made them. If the person had a key's secret, [roll it](#rolling-a-key). Someone removed can be invited again.

## Rolling a key [#rolling-a-key]

Every key shows who made it and when it was last used, and any Admin or Developer can roll or revoke any of the company's keys. Rolling makes a replacement with the same name and mode, shows its secret once, and lets you choose when the old key stops working: at once, in an hour, a day or a week. Until then both work. After that the old key is refused with `401`, saying when it stopped. Roll from the key's menu in the console, or with [`rollApiKey`](/docs/api/account/rollApiKey):

```bash
curl -s https://orgasm.dev/v1/api-keys/key_9d2f5g8h1j4k7l0z3x6c/roll \
  -H "Authorization: Bearer $ORGASM_KEY" -H "Content-Type: application/json" \
  -d '{ "expiresInS": 86400 }'
```

## Rolling a webhook secret [#rolling-a-webhook-secret]

An endpoint's menu edits it (its URL, its events, a description, or pausing it), rolls its signing secret, or deletes it. The API equivalents are [`updateWebhookEndpoint`](/docs/api/webhooks/updateWebhookEndpoint) and [`rollWebhookSecret`](/docs/api/webhooks/rollWebhookSecret). After a roll, the new secret signs every delivery. For 24 hours each delivery also carries a signature made with the previous secret: `webhook-signature` lists both, separated by a space. Your receiver keeps verifying while you switch it to the new secret. The [verifier in the webhooks guide](/docs/guides/webhooks#verify-every-delivery), like any Standard Webhooks library, accepts a delivery when any signature matches.

## Billing keys [#billing-keys]

A billing key (`rk_live_…`) is for a finance or data system. It reads [`getCredits`](/docs/api/account/getCredits), [`getUsage`](/docs/api/account/getUsage) and [`listCharges`](/docs/api/account/listCharges); every other request is refused with `403 permission_denied`. It cannot start a session or change anything. Admins and Billing members make billing keys in the Billing tab, and roll and revoke them there.

What the charges carry, and how to break your costs down by your own users and sessions, is in [Cost attribution](/docs/credits#cost-attribution).

## The activity log [#the-activity-log]

Admins see the company's last 100 changes in the Team tab, each with who made it and when:

- keys made, rolled and revoked;
- endpoints added, edited, rolled and deleted;
- your GPUs asked for, routed and withdrawn;
- people invited, let in, declined, given a new role, removed, or leaving;
- purges by user reference.

A change made with an API key shows the key instead of a person.


---

# Verify the enclave (https://orgasm.dev/docs/guides/verify)

Every live session is analysed on a confidential virtual machine whose image was built in public. You can check three things, each with tools that do not depend on orgasm.dev:

1. **The release.** Its SLSA provenance and its keyless signature tie the image's digest to a tagged commit of the [public source](https://github.com/Masseuse-ai/masseuse-video-tee).
2. **The machine.** Its attestation token, signed by Google's attestation service, names the hardware, the machine image and the digest and release the enclave runs.
3. **The session.** The device checked that token before it sent a frame; you can make the same checks yourself, from outside, against a session's enclave while it is live, and read the token Google signed for the session in its receipt afterwards.

Sample attestation receipt, release v0.19.0:

| Checked | |
| --- | --- |
| Image | `sha256:5871c1c0eb516ec9f565f631e925762d0a4b738bed3a8cf0c6e915eaadfae6a1` |
| Release | [v0.19.0](https://github.com/Masseuse-ai/masseuse-video-tee/releases/tag/v0.19.0) from [`b494418`](https://github.com/Masseuse-ai/masseuse-video-tee/commit/b494418fa760bb47d36190ef6c380d1a6a381eab) |
| Hardware | Intel TDX, NVIDIA H100 with confidential computing on |
| Debugging | Off since boot |
| Provenance | SLSA Build Level 3, by the release workflow (published with the release) |
| Signature | Keyless, in Sigstore’s public log (published with the release) |

## Three layers, three proofs [#three-layers-three-proofs]

| Layer | What proves it | Who checks it |
| --- | --- | --- |
| The hardware: Intel TDX memory encryption, an NVIDIA H100 in confidential-computing mode, Secure Boot | The attestation token's `hwmodel`, `secboot` and `submods.nvidia_gpu` | The device, and `tee-verify` |
| The machine image: Google's Confidential Space, on its STABLE track, debugging disabled since boot | The token's `swname`, `dbgstat` and `submods.confidential_space.support_attributes` | The device, and `tee-verify` |
| The workload: the enclave image and what it loads | The token's `image_digest`, its release stamp (`TEE_IMAGE_VERSION`, `TEE_IMAGE_COMMIT`) and its signature; the digest's SLSA provenance and keyless signature in Sigstore's public log | `slsa-verifier`, `cosign`, and `tee-verify` |

The token is signed by `https://confidentialcomputing.googleapis.com`, and only the launcher inside a real Confidential Space machine can obtain one. Debugging disabled since boot (`dbgstat: disabled-since-boot`) means nobody could log in, redirect the output or read memory at any point since the machine started.

## Check a release [#check-a-release]

Each release's page on GitHub names its image digest and gives the two commands that check it. For the example release, v0.19.0 (October 16, 2026):

```sh title="Terminal"
slsa-verifier verify-image ghcr.io/masseuse-ai/masseuse-video-tee@sha256:5871c1c0eb516ec9f565f631e925762d0a4b738bed3a8cf0c6e915eaadfae6a1 \
  --source-uri github.com/Masseuse-ai/masseuse-video-tee --source-tag v0.19.0

cosign verify ghcr.io/masseuse-ai/masseuse-video-tee@sha256:5871c1c0eb516ec9f565f631e925762d0a4b738bed3a8cf0c6e915eaadfae6a1 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity https://github.com/Masseuse-ai/masseuse-video-tee/.github/workflows/release.yml@refs/tags/v0.19.0
```

You need [`slsa-verifier`](https://github.com/slsa-framework/slsa-verifier) and [`cosign`](https://github.com/sigstore/cosign) 3 or later (the signature is stored as a Sigstore bundle). When both pass, the image with that digest was built on GitHub's runners by the repository's release workflow, from the commit the tag names. Change one line of code and the digest changes, and neither record exists for it. Then [read the code at that tag](https://github.com/Masseuse-ai/masseuse-video-tee/tree/v0.19.0).

Every release is listed on [the releases page](https://github.com/Masseuse-ai/masseuse-video-tee/releases). Tags there are immutable: once created, nobody can move or delete one.

## Check a live session's enclave [#check-a-live-sessions-enclave]

Your server's `POST /v1/live-sessions` response carries `ingest.attestationUrl`, the enclave's own attestation endpoint. While the session is live, from any machine with Go 1.22 or later and `slsa-verifier`:

```sh title="Terminal"
git clone https://github.com/Masseuse-ai/masseuse-video-tee enclave
cd enclave/verifier && go build -o tee-verify .

ORIGIN=$(node -p 'new URL(process.argv[1]).origin' "$ATTESTATION_URL")
./tee-verify -policy-url 'https://orgasm.dev/v1/attestation-policy?mode=live' -origin "$ORIGIN"
```

`-policy-url` reads the values orgasm.dev holds its enclaves to from the policy's `verify` block: the release signing key, the minimum release, where the enclave posts its readings, which identity may control it, the record bucket and the project. A flag you pass yourself wins over the policy, and the report names the policy it read.

`tee-verify` asks the enclave for a token minted for a random nonce of its own, over a TLS connection it opens itself, and checks:

- the token's signature against Google's published keys, its issuer, and that it was minted for this enclave, just now;
- the hardware, the machine image and the posture in the table above;
- that the image carries the release signing key's signature, and which release and commit it is stamped with;
- that the running digest has SLSA provenance from the public repository at that release and commit, with `slsa-verifier`;
- that the TLS connection it negotiated, and the key that signs every WebRTC answer, both belong to this enclave;
- where the enclave sends its readings, which identity may control it, and that requests are sealed.

An exit code of 0 and `"passed": true` mean every check held. Add `-expect-release v0.19.0` to insist on a release, or `-v` to print every attested value. With [your own GPUs](/docs/guides/own-gpus), your console prints the command with your project's values.

An enclave runs only while a session needs it and stops a minute or two after it ends, so run the check while your session is live. A refused connection afterwards means the machine is gone, not that a check failed.

## Read a session's receipt [#read-a-sessions-receipt]

Once a live session's enclave is attested, `GET /v1/live-sessions/{id}` carries `enclave`: the image digest, the release and commit it was built from, the hardware and its posture, and `attestationToken`, the token Google's attestation service signed for that enclave with the session's id among its nonces. orgasm.dev checked it against the [attestation policy](/docs/api/trust/getAttestationPolicy) over a TLS connection the token names, and the receipt stays with the session's events. Your console's live mode lists each session with its receipt.

You can check the token yourself, after the machine is gone:

```ts title="receipt.ts"
import { createRemoteJWKSet, decodeJwt, jwtVerify } from 'jose';

const keys = createRemoteJWKSet(
  new URL('https://www.googleapis.com/service_accounts/v1/metadata/jwk/signer@confidentialspace-sign.iam.gserviceaccount.com'),
);
const token = session.enclave.attestationToken;
// The token lives an hour; check it as of the moment it was signed.
const signedAt = new Date((decodeJwt(token).iat ?? 0) * 1000 + 1000);
const { payload } = await jwtVerify(token, keys, { issuer: 'https://confidentialcomputing.googleapis.com', currentDate: signedAt });
const claims = payload as unknown as { eat_nonce: string[]; submods: { container: { image_digest: string } } };

console.log(claims.eat_nonce.at(-1) === session.id); // minted for this session
console.log(claims.submods.container.image_digest === session.enclave.imageDigest);
```

Then check that digest's release with the two commands above. Google rotates its signing keys, so a token can only be checked while its key is still published: keep the keys with the receipt if you need to prove it later.

## What this does not prove [#what-this-does-not-prove]

- **That your app runs the SDK as published.** The device's checks happen in your app; a modified SDK could skip them. [Read its source](https://github.com/Orgasm-dev/device-sdk), pin the version you ship, and run `npm audit signatures`: each release on npm carries provenance tying it to a tag of that repository.
- **What the detectors compute.** Their code is not published. What is proved is which bytes ran, that they never received a frame or a sound, and that they had no network of their own ([Trust](/docs/concepts/trust#what-is-not-public)).
- **The policy orgasm.dev serves.** The device checks the enclave against `GET /v1/attestation-policy`, which orgasm.dev serves. `tee-verify` and the release checks above do not rely on it.
- **Anything outside the token.** That the image writes nothing of a session to disk, for one, is in its code, which you can read, not in the token. The repository's [`VERIFY.md`](https://github.com/Masseuse-ai/masseuse-video-tee/blob/master/VERIFY.md) lists the rest.


---

# Webhooks (https://orgasm.dev/docs/guides/webhooks)

A webhook endpoint is a URL on your server that receives events as HTTP POSTs, signed per the [Standard Webhooks](https://www.standardwebhooks.com) specification. Every event type can be delivered except `imminence.updated`, `signals.updated` and `stimulation.updated`, which arrive often and are only streamed. One more type exists only here: `credits.low`, sent to live endpoints when your company's balance runs low ([Credits and billing](/docs/credits#at-zero)).

## Register an endpoint [#register-an-endpoint]

```bash
curl -s https://orgasm.dev/v1/webhook-endpoints \
  -H "Authorization: Bearer $ORGASM_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://api.example.com/hooks/orgasm-dev",
        "events": ["orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "recording.completed", "credits.low"] }'
```

The response carries the endpoint's signing `secret` (`whsec_…`) once. Store it. By default every session and recording delivers to every endpoint subscribed to an event's type; set `webhookEndpointId` on a session or recording to deliver its events to one endpoint only.

## Verify every delivery [#verify-every-delivery]

Each POST carries three headers:

| Header | Value |
| --- | --- |
| `webhook-id` | The event `id`; the same on every retry |
| `webhook-timestamp` | When this attempt was sent, in Unix seconds |
| `webhook-signature` | `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}` |

Verify before you trust the body, against the raw body as received:

```ts title="verify.ts"
export async function verify(secret: string, headers: Headers, body: string, nowS = Date.now() / 1000): Promise<boolean> {
  const id = headers.get('webhook-id');
  const timestamp = headers.get('webhook-timestamp');
  const signatures = headers.get('webhook-signature');
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(nowS - Number(timestamp)) > 300) return false;
  const key = await crypto.subtle.importKey(
    'raw',
    Uint8Array.from(atob(secret.replace(/^whsec_/, '')), (c) => c.charCodeAt(0)),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign'],
  );
  const mac = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(`${id}.${timestamp}.${body}`));
  const expected = `v1,${btoa(String.fromCharCode(...new Uint8Array(mac)))}`;
  return signatures.split(' ').includes(expected);
}
```

Any Standard Webhooks library verifies the same headers. The examples in the [events reference](/docs/events/deliverWebhooks) are signed with the sample secret `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw`, so you can test your verifier against them: pass the example's `webhook-timestamp` as `nowS`.

## Answer fast, process later [#answer-fast-process-later]

Answer with any 2xx within 10 seconds, then process. Any other answer, or none, is retried with exponential backoff for up to 24 hours.

- Deliveries are at least once: deduplicate on `webhook-id`.
- Retries arrive out of order: sort by `sequence` within a session or recording. `credits.low` has no `sequence`; order it by `wallTime`.

## Test your receiver [#test-your-receiver]

`sendTestWebhook` sends one signed sample event of the type you choose and reports how your server answered: status code, duration and the headers it sent. In test mode, `http://localhost` and `http://127.0.0.1` URLs are accepted, so you can point an endpoint at a server on your machine.


---

# Overview (https://orgasm.dev/docs)

orgasm.dev turns the front camera of a consenting adult, live or recorded, into events about their orgasm. Your app, device, game or scene reacts to those events: to hold someone at the edge, to ruin an orgasm at the point of no return, or to carry it through.

## What you get back [#what-you-get-back]

| Event | What it says | Needs |
| --- | --- | --- |
| `imminence.updated` | The probability that orgasm begins within 30 and within 60 seconds, about once a second | Face |
| `signals.updated` | Vocalizations, loudness, contractions, movement and how each region of the face has moved, about once a second, for a display | Each field its own input |
| `orgasm.onset` | A woman's orgasm began | Face and microphone |
| `orgasm.peak` | A man's orgasm peaked | Face and microphone |
| `orgasm.end` | The orgasm ended | Face, and the microphone for women |
| `subject.identified` | Whether the face reads as a woman's or a man's, which decides the detectors | Face |

Every signal carries `confidence`, which says how complete the input behind it was. [Signals](/docs/concepts/signals) explains each one, including what it is not.

## Two ways in [#two-ways-in]

<Cards>
  <Card title="Live sessions" href="/docs/guides/live-sessions">
    `POST /v1/live-sessions`. The person's device publishes its camera and microphone over WHIP; events arrive within seconds over server-sent events, a WebSocket or webhooks.
  </Card>
  <Card title="Recordings" href="/docs/guides/recordings">
    `POST /v1/recordings`. Upload a video or give a URL; the same events come back as a timeline once it is processed.
  </Card>
</Cards>

You never have to say whether the person is a woman or a man: the face is read, and the detectors that apply follow. You may say so with `subjectHint` when the person told you.

## The shape of a session [#the-shape-of-a-session]

```mermaid
sequenceDiagram
  participant App as Your server
  participant API as orgasm.dev
  participant Device as The person's device
  participant Enclave as Enclave
  App->>API: POST /v1/live-sessions (secret key, consent, capability hash)
  API-->>App: ingest, results.clientToken
  App->>Device: ingest, client token
  Device->>Enclave: verify attestation, then publish camera + microphone (WHIP)
  Enclave-->>API: numbers only
  API-->>App: imminence.updated, subject.identified, orgasm.onset / peak / end
  App->>API: DELETE /v1/live-sessions/{id}
```

## Where things stand [#where-things-stand]

The sandbox is open. Any key that starts with `sk_test_` reaches it; it plays [deterministic scenarios](/docs/guides/sandbox) through the same contract, so you can build and test an integration end to end today. Keys that start with `sk_live_`, from your dashboard once you [sign up](/signup), run [live sessions](/docs/guides/live-sessions) on attested enclaves: the end user's device publishes its front camera and microphone straight to one ([trust](/docs/concepts/trust)). Recorded videos are analysed in the sandbox only for now: with a live key, `createRecording` answers `live_mode_unavailable`.

## What we ask of you [#what-we-ask-of-you]

Everyone on camera is a verified adult who agreed to the analysis and can stop it at any time; every request that starts an analysis says so in `consent`. Read [acceptable use](/docs/concepts/compliance) before you build, and [trust](/docs/concepts/trust) for what the enclave does and does not guarantee.

## Next [#next]

- [Quickstart](/docs/quickstart): a sandbox session in five minutes.
- [For AI agents](/docs/agents): the prompt, the MCP servers and the machine-readable contracts.
- [REST reference](/reference): every operation, with a sandbox key filled in.


---

# Quickstart (https://orgasm.dev/docs/quickstart)

The sandbox answers the whole contract with [deterministic scenarios](/docs/guides/sandbox), so you can integrate before live analysis exists. Nothing here needs a camera.

<Steps>
<Step>

### Pick a key and a base URL [#pick-a-key-and-a-base-url]

In the sandbox any key that starts with `sk_test_` works. Keys namespace your sessions, so pick one of your own.

```bash
export ORGASM_KEY=sk_test_quickstart_$(whoami)
export ORGASM_API=https://orgasm.dev
```

Working from this repository? `npm run dev` serves the same sandbox at `http://localhost:3000`, and `npm run mock` at `http://localhost:4010`, with the WebSocket channel as well.

</Step>
<Step>

### Create a live session [#create-a-live-session]

Every request that starts an analysis attests [consent](/docs/concepts/compliance). In the sandbox, `sandbox.scenario` picks what plays and `sandbox.speed` how much faster than real time.

```bash
curl -s "$ORGASM_API/v1/live-sessions" \
  -H "Authorization: Bearer $ORGASM_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "consent": { "subjectIsAdult": true, "subjectConsented": true, "ageVerification": "document" },
    "sandbox": { "scenario": "woman-onset-end", "speed": 20 }
  }'
```

The answer is the session, with `status: "starting"`, an `ingest` block (where a real device would publish) and a `results` block (where events arrive). Keep its `id`.

</Step>
<Step>

### Follow its events [#follow-its-events]

As a stream of server-sent events:

```bash
curl -N "$ORGASM_API/v1/live-sessions/ls_…/stream" -H "Authorization: Bearer $ORGASM_KEY"
```

Or by long polling, which suits agents and simple servers: `wait` holds the request until an event matches.

```bash
curl -s "$ORGASM_API/v1/live-sessions/ls_…/events?types=orgasm.onset,orgasm.end&wait=30" \
  -H "Authorization: Bearer $ORGASM_KEY"
```

At speed 20, the subject read arrives after about three seconds, imminence after four, and the onset about half a minute in:

```json
{
  "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"
}
```

</Step>
<Step>

### End it [#end-it]

```bash
curl -s -X DELETE "$ORGASM_API/v1/live-sessions/ls_…" -H "Authorization: Bearer $ORGASM_KEY"
```

</Step>
</Steps>

## The same in TypeScript [#the-same-in-typescript]

Node 18 or later, no dependencies. It creates a session, reads the stream and reacts to each call.

```ts title="quickstart.ts"
const API = process.env.ORGASM_API ?? 'https://orgasm.dev';
const KEY = process.env.ORGASM_KEY!; // sk_test_… reaches the sandbox

const auth = { Authorization: `Bearer ${KEY}` };

const created = await fetch(`${API}/v1/live-sessions`, {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
  body: JSON.stringify({
    consent: { subjectIsAdult: true, subjectConsented: true, ageVerification: 'document' },
    sandbox: { scenario: 'man-peak', speed: 30 },
  }),
});
const session = await created.json();

const stream = await fetch(session.results.streamUrl, { headers: auth });
const decoder = new TextDecoder();
let buffer = '';
for await (const chunk of stream.body!) {
  buffer += decoder.decode(chunk, { stream: true });
  let end: number;
  while ((end = buffer.indexOf('\n\n')) !== -1) {
    const frame = buffer.slice(0, end);
    buffer = buffer.slice(end + 2);
    const data = frame.split('\n').find((line) => line.startsWith('data: '));
    if (!data) continue; // a keep-alive comment
    const event = JSON.parse(data.slice(6));
    if (event.type === 'imminence.updated' && event.data.p30 !== null) {
      console.log(`${event.streamTimeS}s  p30 ${event.data.p30}  p60 ${event.data.p60}`);
    }
    if (event.type.startsWith('orgasm.')) {
      console.log(`${event.type} at ${event.data.eventAtS}s, called ${event.data.lagS}s later`);
    }
  }
}
```

## A recording instead [#a-recording-instead]

Recordings are a separate endpoint. Ask for an upload URL, `PUT` the file, then read the result once `status` is `completed`. In the sandbox the bytes are read and discarded; use any small video, never a real recording of a person.

```bash
curl -s "$ORGASM_API/v1/recordings" \
  -H "Authorization: Bearer $ORGASM_KEY" -H "Content-Type: application/json" \
  -d '{
    "consent": { "subjectIsAdult": true, "subjectConsented": true, "ageVerification": "document" },
    "source": { "type": "upload" },
    "sandbox": { "scenario": "man-peak", "speed": 60 }
  }'
# then: curl -X PUT --data-binary @test.mp4 -H "Content-Type: video/mp4" "<uploads.face.url>"
# and:  curl "$ORGASM_API/v1/recordings/rec_…" -H "Authorization: Bearer $ORGASM_KEY"
```

## Next [#next]

- [Signals](/docs/concepts/signals): what imminence, onset, peak and end mean, and what they don't.
- [Live sessions](/docs/guides/live-sessions): the capability, the device and the enclave, end to end.
- [Presets](/docs/concepts/presets): edge, ruin and finish as code you can start from.


---

# REST API reference

# orgasm.dev API

- **OpenAPI Version:** `3.2.0`
- **API Version:** `1.0.0`
- **Contact:** orgasm.dev <https://orgasm.dev/docs>
- **License:** Proprietary

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>.

## Contents

**Operations**

- [POST /v1/live-sessions](#scalar-operation-post-v1live-sessions)
- [GET /v1/live-sessions](#scalar-operation-get-v1live-sessions)
- [POST /v1/live-sessions/purge](#scalar-operation-post-v1live-sessionspurge)
- [GET /v1/live-sessions/{sessionId}](#scalar-operation-get-v1live-sessionssessionid)
- [DELETE /v1/live-sessions/{sessionId}](#scalar-operation-delete-v1live-sessionssessionid)
- [POST /v1/live-sessions/{sessionId}/purge](#scalar-operation-post-v1live-sessionssessionidpurge)
- [GET /v1/live-sessions/{sessionId}/events](#scalar-operation-get-v1live-sessionssessionidevents)
- [GET /v1/live-sessions/{sessionId}/stream](#scalar-operation-get-v1live-sessionssessionidstream)
- [POST /v1/live-sessions/{sessionId}/view-tokens](#scalar-operation-post-v1live-sessionssessionidview-tokens)
- [POST /v1/live-sessions/{sessionId}/stimulation](#scalar-operation-post-v1live-sessionssessionidstimulation)
- [POST /v1/recordings](#scalar-operation-post-v1recordings)
- [GET /v1/recordings](#scalar-operation-get-v1recordings)
- [GET /v1/recordings/{recordingId}](#scalar-operation-get-v1recordingsrecordingid)
- [DELETE /v1/recordings/{recordingId}](#scalar-operation-delete-v1recordingsrecordingid)
- [GET /v1/recordings/{recordingId}/events](#scalar-operation-get-v1recordingsrecordingidevents)
- [POST /v1/webhook-endpoints](#scalar-operation-post-v1webhook-endpoints)
- [GET /v1/webhook-endpoints](#scalar-operation-get-v1webhook-endpoints)
- [GET /v1/webhook-endpoints/{webhookEndpointId}](#scalar-operation-get-v1webhook-endpointswebhookendpointid)
- [PATCH /v1/webhook-endpoints/{webhookEndpointId}](#scalar-operation-patch-v1webhook-endpointswebhookendpointid)
- [DELETE /v1/webhook-endpoints/{webhookEndpointId}](#scalar-operation-delete-v1webhook-endpointswebhookendpointid)
- [POST /v1/webhook-endpoints/{webhookEndpointId}/roll-secret](#scalar-operation-post-v1webhook-endpointswebhookendpointidroll-secret)
- [POST /v1/webhook-endpoints/{webhookEndpointId}/test](#scalar-operation-post-v1webhook-endpointswebhookendpointidtest)
- [GET /v1/usage](#scalar-operation-get-v1usage)
- [GET /v1/credits](#scalar-operation-get-v1credits)
- [GET /v1/charges](#scalar-operation-get-v1charges)
- [GET /v1/models](#scalar-operation-get-v1models)
- [POST /v1/api-keys](#scalar-operation-post-v1api-keys)
- [GET /v1/api-keys](#scalar-operation-get-v1api-keys)
- [POST /v1/api-keys/{apiKeyId}/roll](#scalar-operation-post-v1api-keysapikeyidroll)
- [DELETE /v1/api-keys/{apiKeyId}](#scalar-operation-delete-v1api-keysapikeyid)
- [GET /v1/attestation-policy](#scalar-operation-get-v1attestation-policy)
- [PUT /v1/sandbox/uploads/{uploadToken}](#scalar-operation-put-v1sandboxuploadsuploadtoken)

**Schemas**

- [EventType](#scalar-schema-eventtype)
- [Confidence](#scalar-schema-confidence)
- [Detector](#scalar-schema-detector)
- [EventBase](#scalar-schema-eventbase)
- [RecentCall](#scalar-schema-recentcall)
- [ImminenceData](#scalar-schema-imminencedata)
- [OrgasmOnsetData](#scalar-schema-orgasmonsetdata)
- [OrgasmPeakData](#scalar-schema-orgasmpeakdata)
- [OrgasmEndData](#scalar-schema-orgasmenddata)
- [EdgeCompletedData](#scalar-schema-edgecompleteddata)
- [SubjectIdentifiedData](#scalar-schema-subjectidentifieddata)
- [InputsPresence](#scalar-schema-inputspresence)
- [SessionStatusData](#scalar-schema-sessionstatusdata)
- [InputWarningData](#scalar-schema-inputwarningdata)
- [FaceRegions](#scalar-schema-faceregions)
- [FaceExpression](#scalar-schema-faceexpression)
- [HeadPose](#scalar-schema-headpose)
- [CameraHeadPose](#scalar-schema-cameraheadpose)
- [FaceChannels](#scalar-schema-facechannels)
- [SignalsData](#scalar-schema-signalsdata)
- [StimulationChannel](#scalar-schema-stimulationchannel)
- [StimulationDevice](#scalar-schema-stimulationdevice)
- [StimulationData](#scalar-schema-stimulationdata)
- [StimulationReportChannel](#scalar-schema-stimulationreportchannel)
- [StimulationReportDevice](#scalar-schema-stimulationreportdevice)
- [FaceFrame](#scalar-schema-faceframe)
- [RecordingCompletedData](#scalar-schema-recordingcompleteddata)
- [RecordingFailedData](#scalar-schema-recordingfaileddata)
- [ImminenceUpdatedEvent](#scalar-schema-imminenceupdatedevent)
- [SignalsUpdatedEvent](#scalar-schema-signalsupdatedevent)
- [StimulationUpdatedEvent](#scalar-schema-stimulationupdatedevent)
- [OrgasmOnsetEvent](#scalar-schema-orgasmonsetevent)
- [OrgasmPeakEvent](#scalar-schema-orgasmpeakevent)
- [OrgasmEndEvent](#scalar-schema-orgasmendevent)
- [EdgeCompletedEvent](#scalar-schema-edgecompletedevent)
- [SubjectIdentifiedEvent](#scalar-schema-subjectidentifiedevent)
- [SessionStatusEvent](#scalar-schema-sessionstatusevent)
- [InputWarningEvent](#scalar-schema-inputwarningevent)
- [RecordingCompletedEvent](#scalar-schema-recordingcompletedevent)
- [RecordingFailedEvent](#scalar-schema-recordingfailedevent)
- [CreditsLowData](#scalar-schema-creditslowdata)
- [CreditsLowEvent](#scalar-schema-creditslowevent)
- [Event](#scalar-schema-event)
- [Problem](#scalar-schema-problem)
- [ErrorCode](#scalar-schema-errorcode)
- [Consent](#scalar-schema-consent)
- [DeclaredInputs](#scalar-schema-declaredinputs)
- [ScenarioName](#scalar-schema-scenarioname)
- [SandboxOptions](#scalar-schema-sandboxoptions)
- [Metadata](#scalar-schema-metadata)
- [UserReference](#scalar-schema-userreference)
- [ClientReferenceId](#scalar-schema-clientreferenceid)
- [LiveSessionStatus](#scalar-schema-livesessionstatus)
- [LiveSessionCreateRequest](#scalar-schema-livesessioncreaterequest)
- [VideoRequirements](#scalar-schema-videorequirements)
- [Ingest](#scalar-schema-ingest)
- [Results](#scalar-schema-results)
- [LatestImminence](#scalar-schema-latestimminence)
- [LiveSession](#scalar-schema-livesession)
- [LiveSessionCharges](#scalar-schema-livesessioncharges)
- [LiveSessionList](#scalar-schema-livesessionlist)
- [LiveSessionPurgeRequest](#scalar-schema-livesessionpurgerequest)
- [LiveSessionPurgeResult](#scalar-schema-livesessionpurgeresult)
- [EventUnion](#scalar-schema-eventunion)
- [EventList](#scalar-schema-eventlist)
- [StimulationReport](#scalar-schema-stimulationreport)
- [CreateViewTokenRequest](#scalar-schema-createviewtokenrequest)
- [ViewToken](#scalar-schema-viewtoken)
- [StimulationReceipt](#scalar-schema-stimulationreceipt)
- [RecordingStatus](#scalar-schema-recordingstatus)
- [RecordingSourceUpload](#scalar-schema-recordingsourceupload)
- [RecordingSourceUrl](#scalar-schema-recordingsourceurl)
- [RecordingCreateRequest](#scalar-schema-recordingcreaterequest)
- [Upload](#scalar-schema-upload)
- [OrgasmSummary](#scalar-schema-orgasmsummary)
- [RecordingResult](#scalar-schema-recordingresult)
- [Recording](#scalar-schema-recording)
- [RecordingList](#scalar-schema-recordinglist)
- [UploadReceipt](#scalar-schema-uploadreceipt)
- [WebhookEventType](#scalar-schema-webhookeventtype)
- [WebhookEndpointCreateRequest](#scalar-schema-webhookendpointcreaterequest)
- [WebhookEndpointUpdateRequest](#scalar-schema-webhookendpointupdaterequest)
- [WebhookEndpoint](#scalar-schema-webhookendpoint)
- [WebhookEndpointList](#scalar-schema-webhookendpointlist)
- [TestWebhookRequest](#scalar-schema-testwebhookrequest)
- [TestWebhookResult](#scalar-schema-testwebhookresult)
- [UsageDay](#scalar-schema-usageday)
- [Usage](#scalar-schema-usage)
- [CreditPackage](#scalar-schema-creditpackage)
- [CreditBalance](#scalar-schema-creditbalance)
- [ChargeUnit](#scalar-schema-chargeunit)
- [Charge](#scalar-schema-charge)
- [ChargeTotals](#scalar-schema-chargetotals)
- [ChargeList](#scalar-schema-chargelist)
- [Model](#scalar-schema-model)
- [ModelList](#scalar-schema-modellist)
- [ApiKeyType](#scalar-schema-apikeytype)
- [ApiKeyCreateRequest](#scalar-schema-apikeycreaterequest)
- [ApiKeyRollRequest](#scalar-schema-apikeyrollrequest)
- [ApiKey](#scalar-schema-apikey)
- [ApiKeyList](#scalar-schema-apikeylist)
- [AttestationPolicy](#scalar-schema-attestationpolicy)
- [VerifierValues](#scalar-schema-verifiervalues)
- [EnclaveReceipt](#scalar-schema-enclavereceipt)
- [Deleted](#scalar-schema-deleted)

<a id="scalar-context-global-servers"></a>

## 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.

<a id="scalar-context-global-authentication"></a>

## Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  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.

## Tags

### live-sessions

A live camera stream from the end user's device, analysed as it arrives.

### recordings

A recorded video, analysed after upload. Same events, delivered as a timeline.

### webhooks

Endpoints on your server that receive events as signed HTTP POSTs.

### account

Usage, credits, charges, models and API keys.

### trust

What a device verifies before it sends any media.

### sandbox

Endpoints that exist only in test mode.

## Operations

<a id="scalar-operation-post-v1live-sessions"></a>

### Create a live session

- **Method:** `POST`
- **Path:** `/v1/live-sessions`
- **Operation ID:** `createLiveSession`
- **Tags:** live-sessions

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  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`.

#### Request body

The consent attestation, the inputs the device will publish, and options.

**Required:** `true`

**Content type:** `application/json`

[LiveSessionCreateRequest](#scalar-schema-livesessioncreaterequest)

What to create a live session with. Only `consent` is required.

**Example: sandbox**

Sandbox session that plays a woman's onset and end

```json
{
  "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"
  }
}
```

**Example: live**

Live session with a device capability

```json
{
  "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 The session was created. Its status starts at \`starting\`.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Idempotent-Replayed`**

  `true` when the response is a replay of an earlier request with the same `Idempotency-Key`.

  `boolean`

**Content type:** `application/json`

[LiveSession](#scalar-schema-livesession)

One person's live camera stream, from creation to its final status.

**Example: sandbox**

A sandbox session just created

Returned by createLiveSession in the sandbox.

```json
{
  "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
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 402 Your company's credits are used up, so no new live session starts. Sessions already running finish, and test keys are unaffected.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 409 The request conflicts with the resource's state, or an idempotency key was reused.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 503 No analysis capacity is available right now; retry after \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1live-sessions"></a>

### List live sessions

- **Method:** `GET`
- **Path:** `/v1/live-sessions`
- **Operation ID:** `listLiveSessions`
- **Tags:** live-sessions

Lists your company's live sessions, newest first.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Query parameters

- **`limit`**: `integer`, default: `20`, minimum: `1`, maximum: `100`

  How many items to return.
- **`cursor`**: `string`

  The `nextCursor` of the previous page.
- **`status`**: `string`, possible values: `"starting", "ready", "calibrating", "analyzing", "ended"`

  Only sessions with this status.

  Where a live session is in its life: `starting`, `ready`, `calibrating`, `analyzing`, `ended`.
- **`userReference`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  Only those created with this `userReference`.

  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.
- **`clientReferenceId`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  Only those created with this `clientReferenceId`.

  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`.

#### Responses

##### 200 A page of sessions.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[LiveSessionList](#scalar-schema-livesessionlist)

A page of live sessions.

<a id="scalar-example-1"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "live_session",
      "mode": "test",
      "status": "starting",
      "degraded": true,
      "inputs": {
        "face": {
          "present": true,
          "baselineReady": true
        },
        "audio": {
          "declared": true,
          "present": true
        },
        "body": {
          "declared": true,
          "present": true
        }
      },
      "signals": [
        "imminence.updated"
      ],
      "subject": {
        "sex": "woman",
        "pWoman": null,
        "secondsObserved": 0,
        "decidedAtS": 1,
        "hint": "woman",
        "detectors": [
          "onset_end"
        ]
      },
      "latestImminence": {
        "p30": null,
        "p60": null,
        "streamTimeS": 1,
        "eventId": ""
      },
      "ingest": {
        "protocol": "whip",
        "url": "",
        "bodyUrl": null,
        "attestationUrl": "",
        "seal": "v1",
        "iceServersUrl": "",
        "expiresAt": "",
        "video": {
          "codecs": [
            "H264"
          ],
          "maxLongEdgePx": 1,
          "recommendedFps": 1
        },
        "audio": {
          "codecs": [
            "opus"
          ],
          "expected": true
        }
      },
      "enclave": {
        "imageDigest": "",
        "release": null,
        "commit": null,
        "releaseUrl": null,
        "signers": [
          ""
        ],
        "hardware": {
          "cpu": "",
          "gpus": [
            ""
          ],
          "gpuConfidentialComputing": true,
          "secureBoot": true
        },
        "debugging": "",
        "confidentialSpace": [
          ""
        ],
        "projectId": null,
        "zone": null,
        "instanceId": "",
        "tlsBound": true,
        "attestedAt": "",
        "verifiedAt": "",
        "attestationToken": ""
      },
      "charges": {
        "orgasms": 0,
        "ruins": 0,
        "edges": 0,
        "sessionMinimum": true,
        "credits": 0
      },
      "results": {
        "streamUrl": "",
        "websocketUrl": "",
        "eventsUrl": "",
        "clientToken": "",
        "clientTokenExpiresAt": ""
      },
      "subjectHint": "woman",
      "maxDurationS": 1,
      "retentionDays": 1,
      "webhookEndpointId": null,
      "userReference": "",
      "clientReferenceId": "",
      "metadata": {
        "additionalProperty": ""
      },
      "sandbox": {
        "scenario": "woman-onset-end",
        "speed": 1
      },
      "createdAt": "",
      "startedAt": null,
      "endedAt": null,
      "endedReason": "client_ended",
      "resultsExpireAt": null
    }
  ],
  "hasMore": true,
  "nextCursor": null
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1live-sessionspurge"></a>

### Purge a person's live sessions

- **Method:** `POST`
- **Path:** `/v1/live-sessions/purge`
- **Operation ID:** `purgeLiveSessionsByUserReference`
- **Tags:** live-sessions

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  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`.

#### Request body

The person's `userReference`.

**Required:** `true`

**Content type:** `application/json`

[LiveSessionPurgeRequest](#scalar-schema-livesessionpurgerequest)

Whose live sessions to purge.

**Example: person**

Every session of one person

```json
{
  "userReference": "9f2c41ab7e05d3a86b1c"
}
```

#### Responses

##### 200 The sessions that were purged, possibly none.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Idempotent-Replayed`**

  `true` when the response is a replay of an earlier request with the same `Idempotency-Key`.

  `boolean`

**Content type:** `application/json`

[LiveSessionPurgeResult](#scalar-schema-livesessionpurgeresult)

The live sessions a purge deleted.

**Example: purged**

A person's two sessions, purged

Returned by purgeLiveSessionsByUserReference.

```json
{
  "object": "live_session_purge",
  "userReference": "9f2c41ab7e05d3a86b1c",
  "deleted": 2,
  "ids": [
    "ls_8f3kq2m7x9w4c1n6t5ra",
    "ls_2w5e8r1t4y7u0i3o6p9a"
  ]
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1live-sessionssessionid"></a>

### Get a live session

- **Method:** `GET`
- **Path:** `/v1/live-sessions/{sessionId}`
- **Operation ID:** `getLiveSession`
- **Tags:** live-sessions

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  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.

Or:

- **clientToken**: HTTP bearer (`ct_…`)

  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.

#### Path parameters

- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`

  The live session's `id`.

  **Example:**

  ```json
  "ls_8f3kq2m7x9w4c1n6t5ra"
  ```

#### Responses

##### 200 The session.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[LiveSession](#scalar-schema-livesession)

One person's live camera stream, from creation to its final status.

**Example: analyzing**

A sandbox session nine minutes in

Returned by getLiveSession once the scenario is past its onset.

```json
{
  "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
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-delete-v1live-sessionssessionid"></a>

### End a live session

- **Method:** `DELETE`
- **Path:** `/v1/live-sessions/{sessionId}`
- **Operation ID:** `endLiveSession`
- **Tags:** live-sessions

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`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`

  The live session's `id`.

  **Example:**

  ```json
  "ls_8f3kq2m7x9w4c1n6t5ra"
  ```

#### Responses

##### 200 The ended session.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[LiveSession](#scalar-schema-livesession)

One person's live camera stream, from creation to its final status.

<a id="scalar-example-2"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "live_session",
  "mode": "test",
  "status": "starting",
  "degraded": true,
  "inputs": {
    "face": {
      "present": true,
      "baselineReady": true
    },
    "audio": {
      "declared": true,
      "present": true
    },
    "body": {
      "declared": true,
      "present": true
    }
  },
  "signals": [
    "imminence.updated"
  ],
  "subject": {
    "sex": "woman",
    "pWoman": null,
    "secondsObserved": 0,
    "decidedAtS": 1,
    "hint": "woman",
    "detectors": [
      "onset_end"
    ]
  },
  "latestImminence": {
    "p30": null,
    "p60": null,
    "streamTimeS": 1,
    "eventId": ""
  },
  "ingest": {
    "protocol": "whip",
    "url": "",
    "bodyUrl": null,
    "attestationUrl": "",
    "seal": "v1",
    "iceServersUrl": "",
    "expiresAt": "",
    "video": {
      "codecs": [
        "H264"
      ],
      "maxLongEdgePx": 1,
      "recommendedFps": 1
    },
    "audio": {
      "codecs": [
        "opus"
      ],
      "expected": true
    }
  },
  "enclave": {
    "imageDigest": "",
    "release": null,
    "commit": null,
    "releaseUrl": null,
    "signers": [
      ""
    ],
    "hardware": {
      "cpu": "",
      "gpus": [
        ""
      ],
      "gpuConfidentialComputing": true,
      "secureBoot": true
    },
    "debugging": "",
    "confidentialSpace": [
      ""
    ],
    "projectId": null,
    "zone": null,
    "instanceId": "",
    "tlsBound": true,
    "attestedAt": "",
    "verifiedAt": "",
    "attestationToken": ""
  },
  "charges": {
    "orgasms": 0,
    "ruins": 0,
    "edges": 0,
    "sessionMinimum": true,
    "credits": 0
  },
  "results": {
    "streamUrl": "",
    "websocketUrl": "",
    "eventsUrl": "",
    "clientToken": "",
    "clientTokenExpiresAt": ""
  },
  "subjectHint": "woman",
  "maxDurationS": 1,
  "retentionDays": 1,
  "webhookEndpointId": null,
  "userReference": "",
  "clientReferenceId": "",
  "metadata": {
    "additionalProperty": ""
  },
  "sandbox": {
    "scenario": "woman-onset-end",
    "speed": 1
  },
  "createdAt": "",
  "startedAt": null,
  "endedAt": null,
  "endedReason": "client_ended",
  "resultsExpireAt": null
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1live-sessionssessionidpurge"></a>

### Purge a live session

- **Method:** `POST`
- **Path:** `/v1/live-sessions/{sessionId}/purge`
- **Operation ID:** `purgeLiveSession`
- **Tags:** live-sessions

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`

  The live session's `id`.

  **Example:**

  ```json
  "ls_8f3kq2m7x9w4c1n6t5ra"
  ```

#### Responses

##### 200 The session and its events were deleted.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[Deleted](#scalar-schema-deleted)

Confirms a deletion.

**Example: purged**

```json
{
  "id": "ls_8f3kq2m7x9w4c1n6t5ra",
  "object": "live_session",
  "deleted": true
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1live-sessionssessionidevents"></a>

### List a live session's events

- **Method:** `GET`
- **Path:** `/v1/live-sessions/{sessionId}/events`
- **Operation ID:** `listLiveSessionEvents`
- **Tags:** live-sessions

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  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.

Or:

- **clientToken**: HTTP bearer (`ct_…`)

  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.

Or:

- **viewToken**: HTTP bearer (`vt_…`)

  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.

#### Path parameters

- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`

  The live session's `id`.

  **Example:**

  ```json
  "ls_8f3kq2m7x9w4c1n6t5ra"
  ```

#### Query parameters

- **`after`**: `string`, pattern: `^evt_[0-9a-z]{20}$`

  Return only events after the event with this `id`.
- **`types`**: `array`, style: `form`, explode: `false`

  Return only events of these types, comma-separated, for example `orgasm.onset,orgasm.peak,orgasm.end`.

  **Array of:**

  `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

  The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
- **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `500`

  How many events to return.
- **`wait`**: `integer`, default: `0`, minimum: `0`, maximum: `30`

  When no events match yet, hold the request open up to this many seconds until one does. `0` answers at once.

#### Responses

##### 200 A page of events.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[EventList](#scalar-schema-eventlist)

A page of events, oldest first.

**Example: onset**

The onset call, after the imminence update before it

Returned by listLiveSessionEvents around an onset call.

```json
{
  "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"
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1live-sessionssessionidstream"></a>

### Stream a live session's events

- **Method:** `GET`
- **Path:** `/v1/live-sessions/{sessionId}/stream`
- **Operation ID:** `streamLiveSessionEvents`
- **Tags:** live-sessions

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).

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  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.

Or:

- **clientToken**: HTTP bearer (`ct_…`)

  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.

Or:

- **clientTokenQuery**: API key in query `token`

  The client token as a `token` query parameter, for the event stream in a browser, where an `EventSource` cannot set headers.

Or:

- **viewToken**: HTTP bearer (`vt_…`)

  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.

#### Path parameters

- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`

  The live session's `id`.

  **Example:**

  ```json
  "ls_8f3kq2m7x9w4c1n6t5ra"
  ```

#### Query parameters

- **`after`**: `string`, pattern: `^evt_[0-9a-z]{20}$`

  Return only events after the event with this `id`.
- **`types`**: `array`, style: `form`, explode: `false`

  Return only events of these types, comma-separated, for example `orgasm.onset,orgasm.peak,orgasm.end`.

  **Array of:**

  `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

  The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
- **`frames`**: `array`, style: `form`, explode: `false`

  Messages besides the events to receive, comma-separated: `face`, the face about five times a second (`face.frame`).

  **Array of:**

  `string`, possible values: `"face"`

#### Header parameters

- **`Last-Event-ID`**: `string`, pattern: `^evt_[0-9a-z]{20}$`

  The `id` of the last event you received; events after it are replayed.

#### Responses

##### 200 The stream.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `text/event-stream`

`string`

**Example:**

```json
"id: evt_1ayxm16hy930duw499dv\nevent: imminence.updated\ndata: {\"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\"}\n\nid: evt_2099smltv0t2c2wzzyzq\nevent: orgasm.onset\ndata: {\"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\"}\n\n"
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1live-sessionssessionidview-tokens"></a>

### Create a view token

- **Method:** `POST`
- **Path:** `/v1/live-sessions/{sessionId}/view-tokens`
- **Operation ID:** `createViewToken`
- **Tags:** live-sessions

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  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.

#### Path parameters

- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`

  The live session's `id`.

  **Example:**

  ```json
  "ls_8f3kq2m7x9w4c1n6t5ra"
  ```

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  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`.

#### Request body

What the token may read, and for how long.

**Required:** `false`

**Content type:** `application/json`

[CreateViewTokenRequest](#scalar-schema-createviewtokenrequest)

What a view token may read, and for how long.

**Example: overlay**

For a stream overlay, for three hours

```json
{
  "expiresInS": 10800
}
```

**Example: coach**

For a coach who also sees the face read and the face

```json
{
  "includeSubject": true,
  "includeFace": true
}
```

#### Responses

##### 201 The token. It is shown only here.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Idempotent-Replayed`**

  `true` when the response is a replay of an earlier request with the same `Idempotency-Key`.

  `boolean`

**Content type:** `application/json`

[ViewToken](#scalar-schema-viewtoken)

A read-only token for one session's events (`createViewToken`).

**Example: created**

A view token for a stream overlay

```json
{
  "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"
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 409 The request conflicts with the resource's state, or an idempotency key was reused.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1live-sessionssessionidstimulation"></a>

### Report stimulation

- **Method:** `POST`
- **Path:** `/v1/live-sessions/{sessionId}/stimulation`
- **Operation ID:** `reportStimulation`
- **Tags:** live-sessions

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`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  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.

Or:

- **clientToken**: HTTP bearer (`ct_…`)

  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.

#### Path parameters

- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`

  The live session's `id`.

  **Example:**

  ```json
  "ls_8f3kq2m7x9w4c1n6t5ra"
  ```

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  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`.

#### Request body

The new stimulation state.

**Required:** `true`

**Content type:** `application/json`

[StimulationReport](#scalar-schema-stimulationreport)

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.

**Example: on**

Stimulation started at 40 % intensity

```json
{
  "state": "on",
  "intensity": 0.4
}
```

**Example: device**

A two-channel unit in its waves mode, set by your product

```json
{
  "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"
}
```

**Example: level**

Only the level changed

```json
{
  "state": "on",
  "level": 34
}
```

**Example: off**

Stimulation stopped

```json
{
  "state": "off"
}
```

#### Responses

##### 200 The report was recorded.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Idempotent-Replayed`**

  `true` when the response is a replay of an earlier request with the same `Idempotency-Key`.

  `boolean`

**Content type:** `application/json`

[StimulationReceipt](#scalar-schema-stimulationreceipt)

Confirms a stimulation report, with the stimulation as it now stands: this report merged over the ones before it.

**Example:**

```json
{
  "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
  }
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 409 The request conflicts with the resource's state, or an idempotency key was reused.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1recordings"></a>

### Submit a recording

- **Method:** `POST`
- **Path:** `/v1/recordings`
- **Operation ID:** `submitRecording`
- **Tags:** recordings

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`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  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`.

#### Request body

The consent attestation, where the video comes from, and options.

**Required:** `true`

**Content type:** `application/json`

[RecordingCreateRequest](#scalar-schema-recordingcreaterequest)

What to submit a recording with. `consent` and `source` are required.

**Example: upload**

Upload a file (sandbox)

```json
{
  "consent": {
    "subjectIsAdult": true,
    "subjectConsented": true,
    "ageVerification": "document",
    "consentedAt": "2026-10-16T13:58:00Z"
  },
  "source": {
    "type": "upload"
  },
  "sandbox": {
    "scenario": "man-peak",
    "speed": 60
  }
}
```

**Example: url**

Let the enclave fetch a file

```json
{
  "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 The recording was created: \`awaiting_upload\` for uploads, \`queued\` for URLs.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Idempotent-Replayed`**

  `true` when the response is a replay of an earlier request with the same `Idempotency-Key`.

  `boolean`

**Content type:** `application/json`

[Recording](#scalar-schema-recording)

One recorded video, from submission to its result.

**Example: awaitingUpload**

A sandbox recording waiting for its file

Returned by submitRecording for an upload.

```json
{
  "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
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 409 The request conflicts with the resource's state, or an idempotency key was reused.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1recordings"></a>

### List recordings

- **Method:** `GET`
- **Path:** `/v1/recordings`
- **Operation ID:** `listRecordings`
- **Tags:** recordings

Lists your company's recordings, newest first.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Query parameters

- **`limit`**: `integer`, default: `20`, minimum: `1`, maximum: `100`

  How many items to return.
- **`cursor`**: `string`

  The `nextCursor` of the previous page.
- **`status`**: `string`, possible values: `"awaiting_upload", "queued", "processing", "completed", "failed"`

  Only recordings with this status.

  Where a recording is in processing.
- **`userReference`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  Only those created with this `userReference`.

  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.
- **`clientReferenceId`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  Only those created with this `clientReferenceId`.

  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`.

#### Responses

##### 200 A page of recordings.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[RecordingList](#scalar-schema-recordinglist)

A page of recordings.

<a id="scalar-example-3"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "recording",
      "mode": "test",
      "status": "awaiting_upload",
      "source": {
        "type": "upload",
        "url": ""
      },
      "uploads": {
        "face": {
          "url": "",
          "method": "PUT",
          "headers": {
            "additionalProperty": ""
          },
          "maxBytes": 1,
          "expiresAt": "",
          "sealed": true
        },
        "body": {
          "url": "",
          "method": "PUT",
          "headers": {
            "additionalProperty": ""
          },
          "maxBytes": 1,
          "expiresAt": "",
          "sealed": true
        }
      },
      "inputs": {
        "audio": true,
        "body": true
      },
      "progress": {
        "processedS": 1,
        "durationS": null
      },
      "result": {
        "subject": {
          "sex": "woman",
          "pWoman": null,
          "secondsObserved": 0,
          "decidedAtS": 1,
          "hint": "woman",
          "detectors": [
            "onset_end"
          ]
        },
        "summary": {
          "durationS": 1,
          "orgasmCount": 0,
          "orgasms": [
            {
              "orgasmIndex": 1,
              "detectors": [
                "onset_end"
              ],
              "onsetAtS": null,
              "peakAtS": null,
              "endAtS": null,
              "durationS": null,
              "confidence": "high"
            }
          ]
        },
        "timeline": [
          {
            "id": "evt_4q7m2k9x8w1c3n6b5v0z",
            "object": "event",
            "type": "imminence.updated",
            "mode": "test",
            "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
            "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
            "sequence": 1,
            "streamTimeS": 0,
            "wallTime": "",
            "confidence": "high",
            "data": {
              "p30": null,
              "p60": null,
              "logit30": null,
              "logit60": null,
              "featuresPresent": 0,
              "faceVisible": true,
              "baselineReady": true,
              "stimulationAware": true,
              "recentCalls": [
                {
                  "id": "",
                  "type": "orgasm.onset",
                  "eventAtS": 1
                }
              ]
            }
          }
        ]
      },
      "failure": {
        "code": "unreadable_media",
        "message": ""
      },
      "subjectHint": "woman",
      "retentionDays": 1,
      "webhookEndpointId": null,
      "userReference": "",
      "clientReferenceId": "",
      "metadata": {
        "additionalProperty": ""
      },
      "sandbox": {
        "scenario": "woman-onset-end",
        "speed": 1
      },
      "createdAt": "",
      "startedAt": null,
      "completedAt": null,
      "resultsExpireAt": null
    }
  ],
  "hasMore": true,
  "nextCursor": null
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1recordingsrecordingid"></a>

### Get a recording

- **Method:** `GET`
- **Path:** `/v1/recordings/{recordingId}`
- **Operation ID:** `getRecording`
- **Tags:** recordings

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`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`recordingId` (required)**: `string`, pattern: `^rec_[0-9a-z]{20}$`

  The recording's `id`.

  **Example:**

  ```json
  "rec_2n5v8c1x4m7q0w3e6r9t"
  ```

#### Responses

##### 200 The recording.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[Recording](#scalar-schema-recording)

One recorded video, from submission to its result.

**Example: completed**

A sandbox recording after processing

Returned by getRecording after processing.

```json
{
  "id": "rec_2n5v8c1x4m7q0w3e6r9t",
  "object": "recording",
  "mode": "test",
  "status": "completed",
  "source": {
    "type": "upload"
  },
  "uploads": null,
  "inputs": {
    "audio": true,
    "body": false
  },
  "progress": null,
  "result": {
    "subject": {
      "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": {
          "sex": "man",
          "pWoman": 0.07,
          "secondsObserved": 30,
          "decidedAtS": 31,
          "hint": null,
          "detectors": [
            "peak",
            "face_end"
          ]
        },
        "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-delete-v1recordingsrecordingid"></a>

### Delete a recording

- **Method:** `DELETE`
- **Path:** `/v1/recordings/{recordingId}`
- **Operation ID:** `deleteRecording`
- **Tags:** recordings

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`recordingId` (required)**: `string`, pattern: `^rec_[0-9a-z]{20}$`

  The recording's `id`.

  **Example:**

  ```json
  "rec_2n5v8c1x4m7q0w3e6r9t"
  ```

#### Responses

##### 200 The recording was deleted.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[Deleted](#scalar-schema-deleted)

Confirms a deletion.

<a id="scalar-example-4"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "",
  "deleted": true
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1recordingsrecordingidevents"></a>

### List a recording's events

- **Method:** `GET`
- **Path:** `/v1/recordings/{recordingId}/events`
- **Operation ID:** `listRecordingEvents`
- **Tags:** recordings

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`recordingId` (required)**: `string`, pattern: `^rec_[0-9a-z]{20}$`

  The recording's `id`.

  **Example:**

  ```json
  "rec_2n5v8c1x4m7q0w3e6r9t"
  ```

#### Query parameters

- **`after`**: `string`, pattern: `^evt_[0-9a-z]{20}$`

  Return only events after the event with this `id`.
- **`types`**: `array`, style: `form`, explode: `false`

  Return only events of these types, comma-separated, for example `orgasm.onset,orgasm.peak,orgasm.end`.

  **Array of:**

  `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

  The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
- **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `500`

  How many events to return.

#### Responses

##### 200 A page of the recording's events.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[EventList](#scalar-schema-eventlist)

A page of events, oldest first.

<a id="scalar-example-5"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "evt_4q7m2k9x8w1c3n6b5v0z",
      "object": "event",
      "type": "imminence.updated",
      "mode": "test",
      "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
      "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
      "sequence": 1,
      "streamTimeS": 0,
      "wallTime": "",
      "confidence": "high",
      "data": {
        "p30": null,
        "p60": null,
        "logit30": null,
        "logit60": null,
        "featuresPresent": 0,
        "faceVisible": true,
        "baselineReady": true,
        "stimulationAware": true,
        "recentCalls": [
          {
            "id": "",
            "type": "orgasm.onset",
            "eventAtS": 1
          }
        ]
      }
    }
  ],
  "hasMore": true,
  "nextCursor": null
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1webhook-endpoints"></a>

### Create a webhook endpoint

- **Method:** `POST`
- **Path:** `/v1/webhook-endpoints`
- **Operation ID:** `createWebhookEndpoint`
- **Tags:** webhooks

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  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`.

#### Request body

The URL and the event types to deliver.

**Required:** `true`

**Content type:** `application/json`

[WebhookEndpointCreateRequest](#scalar-schema-webhookendpointcreaterequest)

Where to deliver events, and which.

**Example: orgasmEvents**

Orgasm calls and session status

```json
{
  "url": "https://api.example.com/hooks/orgasm-dev",
  "events": [
    "orgasm.onset",
    "orgasm.peak",
    "orgasm.end",
    "subject.identified",
    "session.status"
  ],
  "description": "Production receiver"
}
```

#### Responses

##### 201 The endpoint, with its signing secret.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Idempotent-Replayed`**

  `true` when the response is a replay of an earlier request with the same `Idempotency-Key`.

  `boolean`

**Content type:** `application/json`

[WebhookEndpoint](#scalar-schema-webhookendpoint)

A URL on your server that receives events.

**Example: created**

A new endpoint and its secret

Returned by createWebhookEndpoint.

```json
{
  "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"
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 409 The request conflicts with the resource's state, or an idempotency key was reused.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1webhook-endpoints"></a>

### List webhook endpoints

- **Method:** `GET`
- **Path:** `/v1/webhook-endpoints`
- **Operation ID:** `listWebhookEndpoints`
- **Tags:** webhooks

Lists your company's webhook endpoints for the key's mode, newest first, without their secrets.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Query parameters

- **`limit`**: `integer`, default: `20`, minimum: `1`, maximum: `100`

  How many items to return.
- **`cursor`**: `string`

  The `nextCursor` of the previous page.

#### Responses

##### 200 A page of endpoints. Secrets are not included.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[WebhookEndpointList](#scalar-schema-webhookendpointlist)

A page of webhook endpoints.

<a id="scalar-example-6"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "webhook_endpoint",
      "mode": "test",
      "url": "",
      "events": [
        "orgasm.onset"
      ],
      "description": null,
      "enabled": true,
      "secret": null,
      "previousSecretExpiresAt": null,
      "createdAt": ""
    }
  ],
  "hasMore": true,
  "nextCursor": null
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1webhook-endpointswebhookendpointid"></a>

### Get a webhook endpoint

- **Method:** `GET`
- **Path:** `/v1/webhook-endpoints/{webhookEndpointId}`
- **Operation ID:** `getWebhookEndpoint`
- **Tags:** webhooks

Returns one webhook endpoint and the event types it receives, without its secret.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`webhookEndpointId` (required)**: `string`, pattern: `^we_[0-9a-z]{20}$`

  The webhook endpoint's `id`.

  **Example:**

  ```json
  "we_5h8j1k4l7z0x3c6v9b2n"
  ```

#### Responses

##### 200 The endpoint. Its secret is not included.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[WebhookEndpoint](#scalar-schema-webhookendpoint)

A URL on your server that receives events.

<a id="scalar-example-7"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "webhook_endpoint",
  "mode": "test",
  "url": "",
  "events": [
    "orgasm.onset"
  ],
  "description": null,
  "enabled": true,
  "secret": null,
  "previousSecretExpiresAt": null,
  "createdAt": ""
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-patch-v1webhook-endpointswebhookendpointid"></a>

### Update a webhook endpoint

- **Method:** `PATCH`
- **Path:** `/v1/webhook-endpoints/{webhookEndpointId}`
- **Operation ID:** `updateWebhookEndpoint`
- **Tags:** webhooks

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).

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`webhookEndpointId` (required)**: `string`, pattern: `^we_[0-9a-z]{20}$`

  The webhook endpoint's `id`.

  **Example:**

  ```json
  "we_5h8j1k4l7z0x3c6v9b2n"
  ```

#### Request body

The fields to change.

**Required:** `true`

**Content type:** `application/json`

[WebhookEndpointUpdateRequest](#scalar-schema-webhookendpointupdaterequest)

What to change on an endpoint. What you leave out stays as it is.

**Example: pause**

Stop deliveries for now

```json
{
  "enabled": false
}
```

**Example: events**

Receive edges as well

```json
{
  "events": [
    "orgasm.onset",
    "orgasm.peak",
    "orgasm.end",
    "edge.completed",
    "session.status"
  ]
}
```

#### Responses

##### 200 The endpoint as it now is. Its secret is not included.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[WebhookEndpoint](#scalar-schema-webhookendpoint)

A URL on your server that receives events.

[Generated example](#scalar-example-7)

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-delete-v1webhook-endpointswebhookendpointid"></a>

### Delete a webhook endpoint

- **Method:** `DELETE`
- **Path:** `/v1/webhook-endpoints/{webhookEndpointId}`
- **Operation ID:** `deleteWebhookEndpoint`
- **Tags:** webhooks

Stops all deliveries to the endpoint, including retries in flight.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`webhookEndpointId` (required)**: `string`, pattern: `^we_[0-9a-z]{20}$`

  The webhook endpoint's `id`.

  **Example:**

  ```json
  "we_5h8j1k4l7z0x3c6v9b2n"
  ```

#### Responses

##### 200 The endpoint was deleted.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[Deleted](#scalar-schema-deleted)

Confirms a deletion.

[Generated example](#scalar-example-4)

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1webhook-endpointswebhookendpointidroll-secret"></a>

### Roll a webhook endpoint's secret

- **Method:** `POST`
- **Path:** `/v1/webhook-endpoints/{webhookEndpointId}/roll-secret`
- **Operation ID:** `rollWebhookSecret`
- **Tags:** webhooks

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`webhookEndpointId` (required)**: `string`, pattern: `^we_[0-9a-z]{20}$`

  The webhook endpoint's `id`.

  **Example:**

  ```json
  "we_5h8j1k4l7z0x3c6v9b2n"
  ```

#### Responses

##### 200 The endpoint, with its new signing secret.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[WebhookEndpoint](#scalar-schema-webhookendpoint)

A URL on your server that receives events.

**Example: rolled**

An endpoint with a new secret, the old one valid for a day

Returned by rollWebhookSecret.

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1webhook-endpointswebhookendpointidtest"></a>

### Send a test webhook

- **Method:** `POST`
- **Path:** `/v1/webhook-endpoints/{webhookEndpointId}/test`
- **Operation ID:** `sendTestWebhook`
- **Tags:** webhooks

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`webhookEndpointId` (required)**: `string`, pattern: `^we_[0-9a-z]{20}$`

  The webhook endpoint's `id`.

  **Example:**

  ```json
  "we_5h8j1k4l7z0x3c6v9b2n"
  ```

#### Request body

Optionally, the event type of the sample.

**Required:** `false`

**Content type:** `application/json`

[TestWebhookRequest](#scalar-schema-testwebhookrequest)

Which event type to send as the sample. Defaults to `orgasm.onset`.

<a id="scalar-example-8"></a>

**Generated example:**

```json
{
  "type": "orgasm.onset"
}
```

#### Responses

##### 200 The delivery attempt. \`delivered\` is true when your server answered with a 2xx status.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[TestWebhookResult](#scalar-schema-testwebhookresult)

How your server answered a test delivery.

<a id="scalar-example-9"></a>

**Generated example:**

```json
{
  "object": "webhook_test",
  "delivered": true,
  "statusCode": null,
  "durationMs": 1,
  "error": null,
  "headers": {
    "webhookId": "",
    "webhookTimestamp": "",
    "webhookSignature": ""
  },
  "event": {
    "id": "evt_4q7m2k9x8w1c3n6b5v0z",
    "object": "event",
    "type": "imminence.updated",
    "mode": "test",
    "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
    "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
    "sequence": 1,
    "streamTimeS": 0,
    "wallTime": "",
    "confidence": "high",
    "data": {
      "p30": null,
      "p60": null,
      "logit30": null,
      "logit60": null,
      "featuresPresent": 0,
      "faceVisible": true,
      "baselineReady": true,
      "stimulationAware": true,
      "recentCalls": [
        {
          "id": "",
          "type": "orgasm.onset",
          "eventAtS": 1
        }
      ]
    }
  }
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1usage"></a>

### Get usage

- **Method:** `GET`
- **Path:** `/v1/usage`
- **Operation ID:** `getUsage`
- **Tags:** account

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  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.

Or:

- **billingKey**: HTTP bearer (`rk_live_…`)

  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`.

#### Query parameters

- **`from`**: `string`, format: `date`

  First day, inclusive (UTC).
- **`to`**: `string`, format: `date`

  Last day, inclusive (UTC).

#### Responses

##### 200 Usage per day, and totals.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[Usage](#scalar-schema-usage)

Usage per day over a range of days.

**Example: threeDays**

Sandbox usage over three days

Returned by getUsage.

```json
{
  "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
  }
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1credits"></a>

### Get credits

- **Method:** `GET`
- **Path:** `/v1/credits`
- **Operation ID:** `getCredits`
- **Tags:** account

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  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.

Or:

- **billingKey**: HTTP bearer (`rk_live_…`)

  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`.

#### Responses

##### 200 The balance.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[CreditBalance](#scalar-schema-creditbalance)

Your company's credits, shared by its members and keys. Free credits are used first, then the package that expires soonest.

**Example: growth**

A company on a Growth package, with free credits used up

Returned by getCredits.

```json
{
  "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
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1charges"></a>

### List charges

- **Method:** `GET`
- **Path:** `/v1/charges`
- **Operation ID:** `listCharges`
- **Tags:** account

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

- **secretKey**: HTTP bearer (`sk_test_… or sk_live_…`)

  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.

Or:

- **billingKey**: HTTP bearer (`rk_live_…`)

  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`.

#### Query parameters

- **`from`**: `string`, format: `date`

  First day, inclusive (UTC). Defaults to 30 days ago.
- **`to`**: `string`, format: `date`

  Last day, inclusive (UTC). Defaults to today.
- **`sessionId`**: `string`, pattern: `^ls_[0-9a-z]{20}$`

  Only this session's charges.
- **`userReference`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  Only those created with this `userReference`.

  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.
- **`clientReferenceId`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  Only those created with this `clientReferenceId`.

  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`.
- **`metadata`**: `object`, style: `deepObject`, explode: `true`

  Only charges whose session has these metadata values, as `metadata[plan]=premium`.

  **Additional properties:**

  `string`
- **`limit`**: `integer`, default: `100`, minimum: `1`, maximum: `1000`

  How many charges to return.
- **`cursor`**: `string`

  The `nextCursor` of the previous page.

#### Responses

##### 200 A page of charges, and the totals of every charge that matches.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[ChargeList](#scalar-schema-chargelist)

A page of charges, newest first, and the totals of every charge that matches.

**Example: oneOrgasm**

A live session's orgasm, drawn from a Growth package

Returned by listCharges with a live key.

```json
{
  "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
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1models"></a>

### List models

- **Method:** `GET`
- **Path:** `/v1/models`
- **Operation ID:** `listModels`
- **Tags:** account

The models behind each signal: what each produces, which inputs it needs, who it applies to, and where it is available. No key needed.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

No authentication required.

#### Responses

##### 200 The models.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[ModelList](#scalar-schema-modellist)

Every model.

<a id="scalar-example-10"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "imminence",
      "object": "model",
      "version": "",
      "description": "",
      "produces": [
        "imminence.updated"
      ],
      "requires": [
        "face"
      ],
      "benefitsFrom": [
        "body"
      ],
      "appliesTo": "woman",
      "availability": {
        "test": true,
        "live": true
      }
    }
  ]
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1api-keys"></a>

### Create an API key

- **Method:** `POST`
- **Path:** `/v1/api-keys`
- **Operation ID:** `createApiKey`
- **Tags:** account

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  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`.

#### Request body

The new key's name and mode.

**Required:** `true`

**Content type:** `application/json`

[ApiKeyCreateRequest](#scalar-schema-apikeycreaterequest)

A name, a mode and, optionally, a type for a new key.

<a id="scalar-example-11"></a>

**Generated example:**

```json
{
  "name": "",
  "mode": "test",
  "type": "secret"
}
```

#### Responses

##### 201 The key, with its secret.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Idempotent-Replayed`**

  `true` when the response is a replay of an earlier request with the same `Idempotency-Key`.

  `boolean`

**Content type:** `application/json`

[ApiKey](#scalar-schema-apikey)

A key of your company's.

**Example: created**

A new test key and its secret

Returned by createApiKey.

```json
{
  "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
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1api-keys"></a>

### List API keys

- **Method:** `GET`
- **Path:** `/v1/api-keys`
- **Operation ID:** `listApiKeys`
- **Tags:** account

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Query parameters

- **`limit`**: `integer`, default: `20`, minimum: `1`, maximum: `100`

  How many items to return.
- **`cursor`**: `string`

  The `nextCursor` of the previous page.

#### Responses

##### 200 A page of keys. Secrets are not included.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[ApiKeyList](#scalar-schema-apikeylist)

A page of API keys.

**Example: oneKey**

One key

Returned by listApiKeys.

```json
{
  "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
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-post-v1api-keysapikeyidroll"></a>

### Roll an API key

- **Method:** `POST`
- **Path:** `/v1/api-keys/{apiKeyId}/roll`
- **Operation ID:** `rollApiKey`
- **Tags:** account

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`.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`apiKeyId` (required)**: `string`, pattern: `^key_[0-9a-z]{20}$`

  The API key's `id`.

  **Example:**

  ```json
  "key_9d2f5g8h1j4k7l0z3x6c"
  ```

#### Header parameters

- **`Idempotency-Key`**: `string`, minLength: `1`, maxLength: `255`

  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`.

#### Request body

When the old key stops working.

**Required:** `false`

**Content type:** `application/json`

[ApiKeyRollRequest](#scalar-schema-apikeyrollrequest)

When the key being replaced stops working.

**Example: aDay**

Keep the old key for a day

```json
{
  "expiresInS": 86400
}
```

#### Responses

##### 201 The new key, with its secret.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Idempotent-Replayed`**

  `true` when the response is a replay of an earlier request with the same `Idempotency-Key`.

  `boolean`

**Content type:** `application/json`

[ApiKey](#scalar-schema-apikey)

A key of your company's.

**Example: rolled**

The replacement for a key rolled with a day's grace

Returned by rollApiKey.

```json
{
  "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
}
```

##### 400 The request was malformed, or a parameter was invalid.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 422 The body did not match the contract, or consent was not attested.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-delete-v1api-keysapikeyid"></a>

### Delete an API key

- **Method:** `DELETE`
- **Path:** `/v1/api-keys/{apiKeyId}`
- **Operation ID:** `deleteApiKey`
- **Tags:** account

Revokes the key immediately. Requests with it fail from then on.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`apiKeyId` (required)**: `string`, pattern: `^key_[0-9a-z]{20}$`

  The API key's `id`.

  **Example:**

  ```json
  "key_9d2f5g8h1j4k7l0z3x6c"
  ```

#### Responses

##### 200 The key was deleted.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[Deleted](#scalar-schema-deleted)

Confirms a deletion.

**Example: deleted**

```json
{
  "id": "key_9d2f5g8h1j4k7l0z3x6c",
  "object": "api_key",
  "deleted": true
}
```

##### 401 The key is missing, malformed or revoked.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 403 The key cannot do this, or live mode is not available yet.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-get-v1attestation-policy"></a>

### Get the attestation policy

- **Method:** `GET`
- **Path:** `/v1/attestation-policy`
- **Operation ID:** `getAttestationPolicy`
- **Tags:** trust

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

No authentication required.

#### Query parameters

- **`mode`**: `string`, possible values: `"test", "live"`, default: `"live"`

  The policy for test or live sessions.

#### Responses

##### 200 The policy.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[AttestationPolicy](#scalar-schema-attestationpolicy)

What an enclave's attestation must show before a device sends it media. In test mode no enclave runs, and the policy says so.

<a id="scalar-example-12"></a>

**Generated example:**

```json
{
  "object": "attestation_policy",
  "mode": "test",
  "version": "",
  "enforced": true,
  "issuer": null,
  "hardware": [
    ""
  ],
  "image": {
    "source": null,
    "minRelease": null,
    "digests": [
      ""
    ],
    "signers": [
      ""
    ],
    "repository": null,
    "releasesUrl": null
  },
  "seal": {
    "schemes": [
      "v1"
    ]
  },
  "evidence": {
    "algorithm": "Ed25519"
  },
  "debugAllowed": true,
  "verify": {
    "sourceUri": "",
    "imageRepo": "",
    "signerKeyIds": [
      ""
    ],
    "minRelease": null,
    "readingsUrl": "",
    "invokers": [
      ""
    ],
    "captureBucket": "",
    "requestSeal": "",
    "projectIds": [
      ""
    ],
    "imageRefPrefixes": [
      ""
    ]
  },
  "note": "",
  "updatedAt": ""
}
```

##### 429 Too many requests; wait \`Retry-After\` seconds.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`
- **`Retry-After`**

  Seconds to wait before retrying.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

<a id="scalar-operation-put-v1sandboxuploadsuploadtoken"></a>

### Upload a sandbox recording

- **Method:** `PUT`
- **Path:** `/v1/sandbox/uploads/{uploadToken}`
- **Operation ID:** `uploadSandboxRecording`
- **Tags:** sandbox

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.

**Servers:** [Inherited servers](#scalar-context-global-servers)

#### Authentication

No authentication required.

#### Path parameters

- **`uploadToken` (required)**: `string`, pattern: `^up_[0-9a-z]{24}$`

  The token in a sandbox `uploads.*.url`.

#### Request body

The video file. Its bytes are read and discarded.

**Required:** `true`

**Content type:** `video/mp4`

`string`

<a id="scalar-example-13"></a>

**Generated example:**

```json
""
```

**Content type:** `video/quicktime`

`string`

<a id="scalar-example-14"></a>

**Generated example:**

```json
""
```

**Content type:** `application/octet-stream`

`string`

<a id="scalar-example-15"></a>

**Generated example:**

```json
""
```

#### Responses

##### 200 The upload was accepted.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/json`

[UploadReceipt](#scalar-schema-uploadreceipt)

Confirms a sandbox upload.

<a id="scalar-example-16"></a>

**Generated example:**

```json
{
  "object": "upload_receipt",
  "recordingId": "",
  "view": "face",
  "bytesReceived": 1
}
```

##### 404 No such resource for this key's mode.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 409 The request conflicts with the resource's state, or an idempotency key was reused.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

**Example:**

```json
{
  "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"
}
```

##### 413 The upload is larger than \`maxBytes\`.

**Headers:**

- **`Request-Id`**

  Identifies the request; include it when you contact support.

  `string`, pattern: `^req_[0-9a-z]{20}$`
- **`RateLimit-Limit`**

  Requests allowed in the current window.

  `integer`
- **`RateLimit-Remaining`**

  Requests left in the current window.

  `integer`
- **`RateLimit-Reset`**

  Seconds until the window resets.

  `integer`

**Content type:** `application/problem+json`

[Problem](#scalar-schema-problem)

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

<a id="scalar-example-17"></a>

**Generated example:**

```json
{
  "type": "",
  "title": "",
  "status": 1,
  "detail": "",
  "instance": "",
  "code": "invalid_request",
  "param": null,
  "requestId": "",
  "errors": [
    {
      "location": "path",
      "path": "",
      "message": ""
    }
  ]
}
```

## Schemas

<a id="scalar-schema-eventtype"></a>

### EventType

**Type:** `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.

<a id="scalar-schema-confidence"></a>

### Confidence

**Type:** `string | null`, possible values: `"high", "medium", "low", null`

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.

<a id="scalar-schema-detector"></a>

### Detector

**Type:** `string`, possible values: `"onset_end", "peak", "face_end"`

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.

<a id="scalar-schema-eventbase"></a>

### EventBase

**Type:** `object`

The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.

**One of:**

- `object`

  **Required fields:** `sessionId`
- `object`

  **Required fields:** `recordingId`

* **`confidence` (required)**: `string | null`, possible values: `"high", "medium", "low", null`

  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.
* **`data` (required)**: `object`

  The event's own fields; see each event type.
* **`id` (required)**: `string`, pattern: `^evt_[0-9a-z]{20}$`

  Unique and stable. A redelivered event carries the same `id`, so deduplicate on it.
* **`mode` (required)**: `string`, possible values: `"test", "live"`

  `test` for sandbox events, `live` for live analysis.
* **`object` (required)**: `string`, const: `"event"`
* **`sequence` (required)**: `integer`, minimum: `1`

  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.
* **`streamTimeS` (required)**: `number`, minimum: `0`

  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` (required)**: `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

  The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
* **`wallTime` (required)**: `string`, format: `date-time`

  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.
* **`recordingId`**: `string`, pattern: `^rec_[0-9a-z]{20}$`

  The recording the event belongs to. Absent on live-session events.
* **`sessionId`**: `string`, pattern: `^ls_[0-9a-z]{20}$`

  The live session the event belongs to. Absent on recording events.

<a id="scalar-example-18"></a>

**Generated example:**

```json
{
  "id": "evt_4q7m2k9x8w1c3n6b5v0z",
  "object": "event",
  "type": "imminence.updated",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
  "sequence": 1,
  "streamTimeS": 0,
  "wallTime": "",
  "confidence": "high",
  "data": {}
}
```

<a id="scalar-schema-recentcall"></a>

### RecentCall

**Type:** `object`

An orgasm call, as repeated in every `imminence.updated`.

- **`eventAtS` (required)**: `number`

  The moment the call names, in stream seconds.
- **`id` (required)**: `string`, pattern: `^evt_[0-9a-z]{20}$`

  The `id` of the call's own event.
- **`type` (required)**: `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end"`

<a id="scalar-example-19"></a>

**Generated example:**

```json
{
  "id": "",
  "type": "orgasm.onset",
  "eventAtS": 1
}
```

<a id="scalar-schema-imminencedata"></a>

### ImminenceData

**Type:** `object`

- **`baselineReady` (required)**: `boolean`

  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.
- **`faceVisible` (required)**: `boolean`

  Whether a face was tracked in the last second.
- **`featuresPresent` (required)**: `number`, minimum: `0`, maximum: `1`

  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.
- **`logit30` (required)**: `number | null`

  `p30` as a logit, ln(p / (1 - p)). Add your own prior on this scale to combine it with what your product knows.
- **`logit60` (required)**: `number | null`

  `p60` as a logit.
- **`p30` (required)**: `number | null`, minimum: `0`, maximum: `1`

  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.
- **`p60` (required)**: `number | null`, minimum: `0`, maximum: `1`

  The same probability over 60 seconds. Never lower than `p30`.
- **`recentCalls` (required)**: array of [RecentCall](#scalar-schema-recentcall), maxItems: `8`

  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.
- **`stimulationAware` (required)**: `boolean`

  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.

<a id="scalar-example-20"></a>

**Generated example:**

```json
{
  "p30": null,
  "p60": null,
  "logit30": null,
  "logit60": null,
  "featuresPresent": 0,
  "faceVisible": true,
  "baselineReady": true,
  "stimulationAware": true,
  "recentCalls": [
    {
      "id": "",
      "type": "orgasm.onset",
      "eventAtS": 1
    }
  ]
}
```

<a id="scalar-schema-orgasmonsetdata"></a>

### OrgasmOnsetData

**Type:** `object`

- **`calledAtS` (required)**: `number`

  The moment the detector made the call, in stream seconds.
- **`detector` (required)**: `string`, const: `"onset_end"`
- **`eventAtS` (required)**: `number`

  The moment the orgasm began, in stream seconds.
- **`lagS` (required)**: `number`, minimum: `0`

  `calledAtS - eventAtS`: how late the call is.
- **`orgasmIndex` (required)**: `integer`, minimum: `1`

  Which orgasm of the session this is, from 1. The onset and the end of the same orgasm share it.
- **`score` (required)**: `number`, minimum: `0`, maximum: `1`

  The detector's score for the call, on the scale of `threshold`.
- **`threshold` (required)**: `number`, minimum: `0`, maximum: `1`

  The level the detector calls at. A score at or above it made the call.

<a id="scalar-example-21"></a>

**Generated example:**

```json
{
  "orgasmIndex": 1,
  "eventAtS": 1,
  "calledAtS": 1,
  "lagS": 0,
  "detector": "onset_end",
  "score": 0,
  "threshold": 0
}
```

<a id="scalar-schema-orgasmpeakdata"></a>

### OrgasmPeakData

**Type:** `object`

- **`calledAtS` (required)**: `number`

  The moment the detector made the call, in stream seconds.
- **`detector` (required)**: `string`, const: `"peak"`
- **`eventAtS` (required)**: `number`

  The moment of the peak, in stream seconds.
- **`lagS` (required)**: `number`, minimum: `0`

  `calledAtS - eventAtS`.
- **`orgasmIndex` (required)**: `integer`, minimum: `1`

  Which orgasm of the session this is, from 1. The peak and the face-based end of the same orgasm share it.
- **`score` (required)**: `number`, minimum: `0`, maximum: `1`
- **`threshold` (required)**: `number`, minimum: `0`, maximum: `1`

<a id="scalar-example-22"></a>

**Generated example:**

```json
{
  "orgasmIndex": 1,
  "eventAtS": 1,
  "calledAtS": 1,
  "lagS": 0,
  "detector": "peak",
  "score": 0,
  "threshold": 0
}
```

<a id="scalar-schema-orgasmenddata"></a>

### OrgasmEndData

**Type:** `object`

- **`calledAtS` (required)**: `number`

  The moment the detector made the call, in stream seconds.
- **`detector` (required)**: `string`, possible values: `"onset_end", "face_end"`
- **`durationS` (required)**: `number`, minimum: `0`

  `eventAtS - startedAtS`.
- **`eventAtS` (required)**: `number`

  The moment the orgasm ended, in stream seconds.
- **`lagS` (required)**: `number`, minimum: `0`

  `calledAtS - eventAtS`.
- **`orgasmIndex` (required)**: `integer`, minimum: `1`

  Which orgasm of the session ended.
- **`ruined` (required)**: `boolean`

  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.
- **`score` (required)**: `number | null`, minimum: `0`, maximum: `1`

  The detector's score, or `null` for `face_end`, which has none.
- **`startedAtS` (required)**: `number`

  When the same orgasm began: its onset (`onset_end`) or its peak (`face_end`).
- **`threshold` (required)**: `number | null`, minimum: `0`, maximum: `1`

  The detector's calling level, or `null` for `face_end`.

<a id="scalar-example-23"></a>

**Generated example:**

```json
{
  "orgasmIndex": 1,
  "eventAtS": 1,
  "startedAtS": 1,
  "durationS": 0,
  "calledAtS": 1,
  "lagS": 0,
  "detector": "onset_end",
  "score": null,
  "threshold": null,
  "ruined": true
}
```

<a id="scalar-schema-edgecompleteddata"></a>

### EdgeCompletedData

**Type:** `object`

- **`durationS` (required)**: `number`, minimum: `0`

  `eventAtS - startedAtS`.
- **`edgeIndex` (required)**: `integer`, minimum: `1`

  Which edge of the session this is, from 1.
- **`eventAtS` (required)**: `number`

  When `p30` fell back below 0.3, the preset's resume level, which made the approach an edge, in stream seconds.
- **`peakP30` (required)**: `number`, minimum: `0.6`, maximum: `1`

  The highest `p30` of the approach.
- **`startedAtS` (required)**: `number`

  When `p30` reached 0.6, the edge preset's back-off level, in stream seconds.

<a id="scalar-example-24"></a>

**Generated example:**

```json
{
  "edgeIndex": 1,
  "startedAtS": 1,
  "eventAtS": 1,
  "durationS": 0,
  "peakP30": 0.6
}
```

<a id="scalar-schema-subjectidentifieddata"></a>

### SubjectIdentifiedData

**Type:** `object`

- **`decidedAtS` (required)**: `number`

  When the read was made, in stream seconds.
- **`detectors` (required)**: `array`, minItems: `1`, uniqueItems: `true`

  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`.

  **Items:**

  `string`, possible values: `"onset_end", "peak", "face_end"`

  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.
- **`hint` (required)**: `string | null`, possible values: `"woman", "man", null`

  The `subjectHint` you gave when you created the session, or `null`.
- **`pWoman` (required)**: `number | null`, minimum: `0`, maximum: `1`

  The read's probability that the face is a woman's, or `null` when the face could not be read.
- **`secondsObserved` (required)**: `integer`, minimum: `0`, maximum: `30`

  Seconds of visible face the read was made from (at most 30).
- **`sex` (required)**: `string`, possible values: `"woman", "man", "undetermined"`

  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.

<a id="scalar-example-25"></a>

**Generated example:**

```json
{
  "sex": "woman",
  "pWoman": null,
  "secondsObserved": 0,
  "decidedAtS": 1,
  "hint": "woman",
  "detectors": [
    "onset_end"
  ]
}
```

<a id="scalar-schema-inputspresence"></a>

### InputsPresence

**Type:** `object`

Which inputs are arriving right now.

- **`audio` (required)**: `object`
  - **`declared` (required)**: `boolean`

    You said the stream would carry the microphone.
  - **`present` (required)**: `boolean`

    Audio is arriving.
- **`body` (required)**: `object`
  - **`declared` (required)**: `boolean`

    You said a body view would be published.
  - **`present` (required)**: `boolean`

    The body view is arriving.
- **`face` (required)**: `object`
  - **`baselineReady` (required)**: `boolean`

    The person's resting baseline is in.
  - **`present` (required)**: `boolean`

    A face was tracked in the last second.

<a id="scalar-example-26"></a>

**Generated example:**

```json
{
  "face": {
    "present": true,
    "baselineReady": true
  },
  "audio": {
    "declared": true,
    "present": true
  },
  "body": {
    "declared": true,
    "present": true
  }
}
```

<a id="scalar-schema-sessionstatusdata"></a>

### SessionStatusData

**Type:** `object`

- **`degraded` (required)**: `boolean`

  An input the session declared is missing, or the face is not visible. The open `input.warning` events say which.
- **`endedReason` (required)**: `string | null`, possible values: `"client_ended", "media_ended", "media_timeout", "max_duration", "interrupted", "policy", "error", null`

  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.
- **`inputs` (required)**: [InputsPresence](#scalar-schema-inputspresence)

  Which inputs are arriving right now.
- **`previousStatus` (required)**: `string | null`, possible values: `"starting", "ready", "calibrating", "analyzing", "ended", null`
- **`status` (required)**: `string`, possible values: `"starting", "ready", "calibrating", "analyzing", "ended"`

  `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.

<a id="scalar-example-27"></a>

**Generated example:**

```json
{
  "status": "starting",
  "previousStatus": "starting",
  "degraded": true,
  "inputs": {
    "face": {
      "present": true,
      "baselineReady": true
    },
    "audio": {
      "declared": true,
      "present": true
    },
    "body": {
      "declared": true,
      "present": true
    }
  },
  "endedReason": "client_ended"
}
```

<a id="scalar-schema-inputwarningdata"></a>

### InputWarningData

**Type:** `object`

- **`code` (required)**: `string`, possible values: `"face_not_visible", "multiple_faces", "audio_absent", "baseline_pending", "body_stream_absent", "low_confidence"`

  `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.
- **`message` (required)**: `string`

  A sentence you can show the person, in English.
- **`sinceS` (required)**: `number`

  When the condition started, in stream seconds.
- **`state` (required)**: `string`, possible values: `"raised", "cleared"`

  `raised` when the condition starts, `cleared` when it ends.

<a id="scalar-example-28"></a>

**Generated example:**

```json
{
  "code": "face_not_visible",
  "state": "raised",
  "message": "",
  "sinceS": 1
}
```

<a id="scalar-schema-faceregions"></a>

### FaceRegions

**Type:** `object`

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.

- **`brows` (required)**: `number`, minimum: `0`, maximum: `1`
- **`cheeks` (required)**: `number`, minimum: `0`, maximum: `1`
- **`corners` (required)**: `number`, minimum: `0`, maximum: `1`
- **`eyes` (required)**: `number`, minimum: `0`, maximum: `1`
- **`jaw` (required)**: `number`, minimum: `0`, maximum: `1`
- **`lips` (required)**: `number`, minimum: `0`, maximum: `1`
- **`nose` (required)**: `number`, minimum: `0`, maximum: `1`

<a id="scalar-example-29"></a>

**Generated example:**

```json
{
  "brows": 0,
  "eyes": 0,
  "cheeks": 0,
  "nose": 0,
  "lips": 0,
  "corners": 0,
  "jaw": 0
}
```

<a id="scalar-schema-faceexpression"></a>

### FaceExpression

**Type:** `object`

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.

- **`browDownL` (required)**: `number`, minimum: `0`, maximum: `1`
- **`browDownR` (required)**: `number`, minimum: `0`, maximum: `1`
- **`browInnerUp` (required)**: `number`, minimum: `0`, maximum: `1`
- **`browOuterUpL` (required)**: `number`, minimum: `0`, maximum: `1`
- **`browOuterUpR` (required)**: `number`, minimum: `0`, maximum: `1`
- **`browTogether` (required)**: `number`, minimum: `0`, maximum: `1`
- **`cheekSquintL` (required)**: `number`, minimum: `0`, maximum: `1`
- **`cheekSquintR` (required)**: `number`, minimum: `0`, maximum: `1`
- **`chinRaise` (required)**: `number`, minimum: `0`, maximum: `1`
- **`eyeBlinkL` (required)**: `number`, minimum: `0`, maximum: `1`
- **`eyeBlinkR` (required)**: `number`, minimum: `0`, maximum: `1`
- **`eyeWideL` (required)**: `number`, minimum: `0`, maximum: `1`
- **`eyeWideR` (required)**: `number`, minimum: `0`, maximum: `1`
- **`jawOpen` (required)**: `number`, minimum: `0`, maximum: `1`
- **`lidRaise` (required)**: `number`, minimum: `0`, maximum: `1`
- **`lidTighten` (required)**: `number`, minimum: `0`, maximum: `1`
- **`lipsPart` (required)**: `number`, minimum: `0`, maximum: `1`
- **`mouthPucker` (required)**: `number`, minimum: `0`, maximum: `1`
- **`mouthSmileL` (required)**: `number`, minimum: `0`, maximum: `1`
- **`mouthSmileR` (required)**: `number`, minimum: `0`, maximum: `1`
- **`mouthStretch` (required)**: `number`, minimum: `0`, maximum: `1`
- **`noseFlare` (required)**: `number`, minimum: `0`, maximum: `1`
- **`noseSneer` (required)**: `number`, minimum: `0`, maximum: `1`
- **`noseWrinkle` (required)**: `number`, minimum: `0`, maximum: `1`

**Additional properties:**

`number`, minimum: `0`, maximum: `1`

<a id="scalar-example-30"></a>

**Generated example:**

```json
{
  "eyeBlinkL": 0,
  "eyeBlinkR": 0,
  "eyeWideL": 0,
  "eyeWideR": 0,
  "browDownL": 0,
  "browDownR": 0,
  "browInnerUp": 0,
  "browOuterUpL": 0,
  "browOuterUpR": 0,
  "jawOpen": 0,
  "lipsPart": 0,
  "mouthSmileL": 0,
  "mouthSmileR": 0,
  "mouthStretch": 0,
  "mouthPucker": 0,
  "noseSneer": 0,
  "noseFlare": 0,
  "cheekSquintL": 0,
  "cheekSquintR": 0,
  "chinRaise": 0,
  "lidTighten": 0,
  "browTogether": 0,
  "noseWrinkle": 0,
  "lidRaise": 0,
  "additionalProperty": 0
}
```

<a id="scalar-schema-headpose"></a>

### HeadPose

**Type:** `object`

How far the head has turned from the person's own resting pose, in degrees, as someone facing them sees it.

- **`pitchDeg` (required)**: `number`, minimum: `-90`, maximum: `90`

  Positive raises the chin; negative lowers it.
- **`rollDeg` (required)**: `number`, minimum: `-90`, maximum: `90`

  Positive tips the top of the head toward the viewer's right.
- **`yawDeg` (required)**: `number`, minimum: `-90`, maximum: `90`

  Positive turns the face toward the viewer's right, the person's own left.

<a id="scalar-example-31"></a>

**Generated example:**

```json
{
  "yawDeg": -90,
  "pitchDeg": -90,
  "rollDeg": -90
}
```

<a id="scalar-schema-cameraheadpose"></a>

### CameraHeadPose

**Type:** `object`

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.

- **`pitchDeg` (required)**: `number`, minimum: `-90`, maximum: `90`

  Positive raises the chin; negative lowers it.
- **`rollDeg` (required)**: `number`, minimum: `-180`, maximum: `180`

  Positive tips the top of the head toward the viewer's right; a head lying on its side reads about 90 either way.
- **`yawDeg` (required)**: `number`, minimum: `-180`, maximum: `180`

  Positive turns the face toward the viewer's right, the person's own left.

<a id="scalar-example-32"></a>

**Generated example:**

```json
{
  "yawDeg": -180,
  "pitchDeg": -90,
  "rollDeg": -180
}
```

<a id="scalar-schema-facechannels"></a>

### FaceChannels

**Type:** `object`

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.

- **`expression` (required)**: [FaceExpression](#scalar-schema-faceexpression)

  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.
- **`head` (required)**: [HeadPose](#scalar-schema-headpose)

  How far the head has turned from the person's own resting pose, in degrees, as someone facing them sees it.

<a id="scalar-example-33"></a>

**Generated example:**

```json
{
  "expression": {
    "eyeBlinkL": 0,
    "eyeBlinkR": 0,
    "eyeWideL": 0,
    "eyeWideR": 0,
    "browDownL": 0,
    "browDownR": 0,
    "browInnerUp": 0,
    "browOuterUpL": 0,
    "browOuterUpR": 0,
    "jawOpen": 0,
    "lipsPart": 0,
    "mouthSmileL": 0,
    "mouthSmileR": 0,
    "mouthStretch": 0,
    "mouthPucker": 0,
    "noseSneer": 0,
    "noseFlare": 0,
    "cheekSquintL": 0,
    "cheekSquintR": 0,
    "chinRaise": 0,
    "lidTighten": 0,
    "browTogether": 0,
    "noseWrinkle": 0,
    "lidRaise": 0,
    "additionalProperty": 0
  },
  "head": {
    "yawDeg": -90,
    "pitchDeg": -90,
    "rollDeg": -90
  }
}
```

<a id="scalar-schema-signalsdata"></a>

### SignalsData

**Type:** `object`

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.

- **`contractionsPerMin` (required)**: `number | null`, minimum: `0`

  Pelvic floor contractions a minute, from the body view; null without it.
- **`face` (required)**: [FaceChannels](#scalar-schema-facechannels) | `null`

  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`.
- **`faceRegions` (required)**: [FaceRegions](#scalar-schema-faceregions) | `null`

  Null while the face is out of view or before the baseline is in.
- **`loudnessAboveBaselineDb` (required)**: `number | null`

  How much louder the voice is than at the baseline, in decibels; null without the microphone or before its baseline.
- **`movement` (required)**: `string | null`, possible values: `"settled", "shifting", "unsettled", null`

  How still the body is, from the body view; null without it.
- **`vocalizationsPerMin` (required)**: `number | null`, minimum: `0`

  Vocalizations a minute, from the microphone; null without it.

<a id="scalar-example-34"></a>

**Generated example:**

```json
{
  "vocalizationsPerMin": null,
  "loudnessAboveBaselineDb": null,
  "contractionsPerMin": null,
  "movement": "settled",
  "faceRegions": {
    "brows": 0,
    "eyes": 0,
    "cheeks": 0,
    "nose": 0,
    "lips": 0,
    "corners": 0,
    "jaw": 0
  },
  "face": {
    "expression": {
      "eyeBlinkL": 0,
      "eyeBlinkR": 0,
      "eyeWideL": 0,
      "eyeWideR": 0,
      "browDownL": 0,
      "browDownR": 0,
      "browInnerUp": 0,
      "browOuterUpL": 0,
      "browOuterUpR": 0,
      "jawOpen": 0,
      "lipsPart": 0,
      "mouthSmileL": 0,
      "mouthSmileR": 0,
      "mouthStretch": 0,
      "mouthPucker": 0,
      "noseSneer": 0,
      "noseFlare": 0,
      "cheekSquintL": 0,
      "cheekSquintR": 0,
      "chinRaise": 0,
      "lidTighten": 0,
      "browTogether": 0,
      "noseWrinkle": 0,
      "lidRaise": 0,
      "additionalProperty": 0
    },
    "head": {
      "yawDeg": -90,
      "pitchDeg": -90,
      "rollDeg": -90
    }
  }
}
```

<a id="scalar-schema-stimulationchannel"></a>

### StimulationChannel

**Type:** `object`

One output of a device with more than one, such as an e-stim unit's channels.

- **`id` (required)**: `string`, pattern: `^[a-z0-9]{1,8}$`

  The output's name, such as `a` or `b`.
- **`level` (required)**: `number`, minimum: `0`

  The output's level now, on the device's own scale.
- **`levelMax` (required)**: `number | null`, exclusiveMinimum: `0`

  The highest level the output will go to now, on the same scale; null when your product did not say.

<a id="scalar-example-35"></a>

**Generated example:**

```json
{
  "id": "",
  "level": 0,
  "levelMax": null
}
```

<a id="scalar-schema-stimulationdevice"></a>

### StimulationDevice

**Type:** `object`

The device your product drives, as a display names it.

- **`connected` (required)**: `boolean`

  False while your product cannot reach the device; a display shows it as disconnected.
- **`label` (required)**: `string | null`, maxLength: `40`

  What a display calls the device, such as `Wand` or `Unit`; null when your product did not say. Never the person's name.

<a id="scalar-example-36"></a>

**Generated example:**

```json
{
  "label": null,
  "connected": true
}
```

<a id="scalar-schema-stimulationdata"></a>

### StimulationData

**Type:** `object`

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.

- **`changedAtS` (required)**: `number`, minimum: `0`

  When the change happened, in stream seconds. The event's own `streamTimeS` is when orgasm.dev received the report, which can be later.
- **`channels` (required)**: array of [StimulationChannel](#scalar-schema-stimulationchannel) | `null`, maxItems: `4`

  Each output's level, for a device with more than one.
- **`device` (required)**: [StimulationDevice](#scalar-schema-stimulationdevice) | `null`

  The device your product drives, as a display names it.
- **`drive` (required)**: `string | null`, possible values: `"auto", "manual", "hold", "paused", null`

  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`.
- **`intensity` (required)**: `number | null`, minimum: `0`, maximum: `1`

  The intensity from 0 to 1 on your product's own scale.
- **`level` (required)**: `number | null`, minimum: `0`

  The device's level on its own scale, such as 0 to 100.
- **`levelMax` (required)**: `number | null`, exclusiveMinimum: `0`

  The highest level the device will go to now, on the same scale.
- **`mode` (required)**: `string | null`, maxLength: `40`

  The device's mode or pattern, as your product names it.
- **`modeLabel` (required)**: `string | null`, maxLength: `40`

  The mode's name to show; without it a display shows `mode` in words.
- **`state` (required)**: `string`, possible values: `"on", "off"`

  Whether stimulation is on or off.

<a id="scalar-example-37"></a>

**Generated example:**

```json
{
  "state": "on",
  "intensity": null,
  "level": null,
  "levelMax": null,
  "channels": [
    {
      "id": "",
      "level": 0,
      "levelMax": null
    }
  ],
  "mode": null,
  "modeLabel": null,
  "device": {
    "label": null,
    "connected": true
  },
  "drive": "auto",
  "changedAtS": 0
}
```

<a id="scalar-schema-stimulationreportchannel"></a>

### StimulationReportChannel

**Type:** `object`

One output's level.

- **`id` (required)**: `string`, pattern: `^[a-z0-9]{1,8}$`

  The output's name, such as `a` or `b`.
- **`level` (required)**: `number`, minimum: `0`
- **`levelMax`**: `number | null`, exclusiveMinimum: `0`

<a id="scalar-example-38"></a>

**Generated example:**

```json
{
  "id": "",
  "level": 0,
  "levelMax": null
}
```

<a id="scalar-schema-stimulationreportdevice"></a>

### StimulationReportDevice

**Type:** `object`

The device your product drives.

- **`connected`**: `boolean`

  False while your product cannot reach the device. Omitted, it keeps its last value, true at first.
- **`label`**: `string | null`, maxLength: `40`

  What a display calls it, such as `Wand` or `Unit`. Never the person's name.

<a id="scalar-example-39"></a>

**Generated example:**

```json
{
  "label": null,
  "connected": true
}
```

<a id="scalar-schema-faceframe"></a>

### FaceFrame

**Type:** `object`

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.

- **`face` (required)**: [FaceChannels](#scalar-schema-facechannels) | `null`

  Null while the face is out of view or before the baseline is in.
- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`
- **`streamTimeS` (required)**: `number`, minimum: `0`

  When the frame was measured, in stream seconds.
- **`type` (required)**: `string`, const: `"face.frame"`
- **`cameraHead`**: [CameraHeadPose](#scalar-schema-cameraheadpose) | `null`

  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.

<a id="scalar-example-40"></a>

**Generated example:**

```json
{
  "type": "face.frame",
  "sessionId": "",
  "streamTimeS": 0,
  "face": {
    "expression": {
      "eyeBlinkL": 0,
      "eyeBlinkR": 0,
      "eyeWideL": 0,
      "eyeWideR": 0,
      "browDownL": 0,
      "browDownR": 0,
      "browInnerUp": 0,
      "browOuterUpL": 0,
      "browOuterUpR": 0,
      "jawOpen": 0,
      "lipsPart": 0,
      "mouthSmileL": 0,
      "mouthSmileR": 0,
      "mouthStretch": 0,
      "mouthPucker": 0,
      "noseSneer": 0,
      "noseFlare": 0,
      "cheekSquintL": 0,
      "cheekSquintR": 0,
      "chinRaise": 0,
      "lidTighten": 0,
      "browTogether": 0,
      "noseWrinkle": 0,
      "lidRaise": 0,
      "additionalProperty": 0
    },
    "head": {
      "yawDeg": -90,
      "pitchDeg": -90,
      "rollDeg": -90
    }
  },
  "cameraHead": {
    "yawDeg": -180,
    "pitchDeg": -90,
    "rollDeg": -180
  }
}
```

<a id="scalar-schema-recordingcompleteddata"></a>

### RecordingCompletedData

**Type:** `object`

- **`durationS` (required)**: `number`

  Length of the recording, in seconds.
- **`orgasmCount` (required)**: `integer`, minimum: `0`

  How many orgasms the analysis called in the recording.
- **`subject` (required)**: `object`
  - **`pWoman` (required)**: `number | null`, minimum: `0`, maximum: `1`
  - **`sex` (required)**: `string`, possible values: `"woman", "man", "undetermined"`

<a id="scalar-example-41"></a>

**Generated example:**

```json
{
  "durationS": 1,
  "orgasmCount": 0,
  "subject": {
    "sex": "woman",
    "pWoman": null
  }
}
```

<a id="scalar-schema-recordingfaileddata"></a>

### RecordingFailedData

**Type:** `object`

- **`code` (required)**: `string`, possible values: `"unreadable_media", "no_face", "too_short", "too_long", "fetch_failed", "upload_expired", "internal"`

  `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.
- **`message` (required)**: `string`

<a id="scalar-example-42"></a>

**Generated example:**

```json
{
  "code": "unreadable_media",
  "message": ""
}
```

<a id="scalar-schema-imminenceupdatedevent"></a>

### imminence.updated

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.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [ImminenceData](#scalar-schema-imminencedata)
  - **`type` (required)**: `string`, const: `"imminence.updated"`

<a id="scalar-schema-signalsupdatedevent"></a>

### signals.updated

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.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [SignalsData](#scalar-schema-signalsdata)

    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` (required)**: `string`, const: `"signals.updated"`

<a id="scalar-schema-stimulationupdatedevent"></a>

### stimulation.updated

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.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [StimulationData](#scalar-schema-stimulationdata)

    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` (required)**: `string`, const: `"stimulation.updated"`

<a id="scalar-schema-orgasmonsetevent"></a>

### orgasm.onset

An orgasm began. Applies to women (the `onset_end` detector). Requires the microphone. The call arrives a few seconds after the moment it names.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [OrgasmOnsetData](#scalar-schema-orgasmonsetdata)
  - **`type` (required)**: `string`, const: `"orgasm.onset"`

<a id="scalar-schema-orgasmpeakevent"></a>

### orgasm.peak

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.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [OrgasmPeakData](#scalar-schema-orgasmpeakdata)
  - **`type` (required)**: `string`, const: `"orgasm.peak"`

<a id="scalar-schema-orgasmendevent"></a>

### orgasm.end

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`).

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [OrgasmEndData](#scalar-schema-orgasmenddata)
  - **`type` (required)**: `string`, const: `"orgasm.end"`

<a id="scalar-schema-edgecompletedevent"></a>

### edge.completed

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.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [EdgeCompletedData](#scalar-schema-edgecompleteddata)
  - **`type` (required)**: `string`, const: `"edge.completed"`

<a id="scalar-schema-subjectidentifiedevent"></a>

### subject.identified

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.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [SubjectIdentifiedData](#scalar-schema-subjectidentifieddata)
  - **`type` (required)**: `string`, const: `"subject.identified"`

<a id="scalar-schema-sessionstatusevent"></a>

### session.status

The live session changed status, or its inputs changed.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [SessionStatusData](#scalar-schema-sessionstatusdata)
  - **`type` (required)**: `string`, const: `"session.status"`

<a id="scalar-schema-inputwarningevent"></a>

### input.warning

An input problem started (`raised`) or stopped (`cleared`). Show `message` to the person when it helps them fix it.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [InputWarningData](#scalar-schema-inputwarningdata)
  - **`type` (required)**: `string`, const: `"input.warning"`

<a id="scalar-schema-recordingcompletedevent"></a>

### recording.completed

A recording finished processing. Fetch its events with `listRecordingEvents`.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [RecordingCompletedData](#scalar-schema-recordingcompleteddata)
  - **`type` (required)**: `string`, const: `"recording.completed"`

<a id="scalar-schema-recordingfailedevent"></a>

### recording.failed

A recording could not be processed.

**All of:**

- [EventBase](#scalar-schema-eventbase)

  The envelope every event shares, on every channel: the stream, the socket, webhooks and the event lists. Unknown fields may be added; ignore them.
- `object`
  - **`data` (required)**: [RecordingFailedData](#scalar-schema-recordingfaileddata)
  - **`type` (required)**: `string`, const: `"recording.failed"`

<a id="scalar-schema-creditslowdata"></a>

### CreditsLowData

**Type:** `object`

- **`balance` (required)**: `number`

  Credits available now, in halves.
- **`domain` (required)**: `string`

  The company domain the credits belong to.
- **`freeRemaining` (required)**: `number`, minimum: `0`

  How many of the free credits are left.
- **`packageId` (required)**: `string`, pattern: `^(free|pkg_[0-9a-z]{20})$`

  The package the threshold is measured against.
- **`threshold` (required)**: `number`

  The level that sent it: 20% of the credits the latest package posted (4 of the free 20).

<a id="scalar-example-43"></a>

**Generated example:**

```json
{
  "domain": "studio.example",
  "balance": 1,
  "threshold": 1,
  "freeRemaining": 0,
  "packageId": ""
}
```

<a id="scalar-schema-creditslowevent"></a>

### credits.low

**Type:** `object`

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.

- **`data` (required)**: [CreditsLowData](#scalar-schema-creditslowdata)
- **`id` (required)**: `string`, pattern: `^evt_[0-9a-z]{20}$`

  Unique and stable; deduplicate on it.
- **`mode` (required)**: `string`, const: `"live"`

  Credits are live mode's.
- **`object` (required)**: `string`, const: `"event"`
- **`type` (required)**: `string`, const: `"credits.low"`
- **`wallTime` (required)**: `string`, format: `date-time`

  When the balance crossed the threshold, as UTC wall-clock time.

<a id="scalar-example-44"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "event",
  "type": "credits.low",
  "mode": "live",
  "wallTime": "",
  "data": {
    "domain": "studio.example",
    "balance": 1,
    "threshold": 1,
    "freeRemaining": 0,
    "packageId": ""
  }
}
```

<a id="scalar-schema-event"></a>

### Event

**Type:** [ImminenceUpdatedEvent](#scalar-schema-imminenceupdatedevent) | [SignalsUpdatedEvent](#scalar-schema-signalsupdatedevent) | [StimulationUpdatedEvent](#scalar-schema-stimulationupdatedevent) | [OrgasmOnsetEvent](#scalar-schema-orgasmonsetevent) | [OrgasmPeakEvent](#scalar-schema-orgasmpeakevent) | [OrgasmEndEvent](#scalar-schema-orgasmendevent) | [EdgeCompletedEvent](#scalar-schema-edgecompletedevent) | [SubjectIdentifiedEvent](#scalar-schema-subjectidentifiedevent) | [SessionStatusEvent](#scalar-schema-sessionstatusevent) | [InputWarningEvent](#scalar-schema-inputwarningevent) | [RecordingCompletedEvent](#scalar-schema-recordingcompletedevent) | [RecordingFailedEvent](#scalar-schema-recordingfailedevent)

Any event. Switch on `type`.

<a id="scalar-schema-problem"></a>

### Problem

**Type:** `object`

An error, as RFC 9457 problem details. `type` links to the explanation of `code` in the docs.

- **`code` (required)**: `string`, possible values: `"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"`

  A stable, machine-readable error code.
- **`status` (required)**: `integer`

  The HTTP status code.
- **`title` (required)**: `string`

  A short summary of the error.
- **`type` (required)**: `string`, format: `uri`

  A link to the docs for this error.
- **`detail`**: `string`

  What went wrong in this request, and what to do.
- **`errors`**: `array`

  Each contract violation, when the body or a parameter did not match the contract.

  **Items:**
  - **`location` (required)**: `string`, possible values: `"path", "query", "header", "cookie", "body"`
  - **`message` (required)**: `string`
  - **`path` (required)**: `string`

    JSON pointer to the value at fault.
- **`instance`**: `string`

  The request path.
- **`param`**: `string | null`

  The request field at fault, as a dotted path, when there is one.
- **`requestId`**: `string`

<a id="scalar-example-45"></a>

**Generated example:**

```json
{
  "type": "",
  "title": "",
  "status": 1,
  "detail": "",
  "instance": "",
  "code": "invalid_request",
  "param": null,
  "requestId": "",
  "errors": [
    {
      "location": "path",
      "path": "",
      "message": ""
    }
  ]
}
```

<a id="scalar-schema-errorcode"></a>

### ErrorCode

**Type:** `string`, possible values: `"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"`

A stable, machine-readable error code.

<a id="scalar-schema-consent"></a>

### Consent

**Type:** `object`

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.

- **`ageVerification` (required)**: `string`, possible values: `"document", "facial_age_estimation", "payment_card", "third_party_service", "other"`

  How you verified the person's age.
- **`subjectConsented` (required)**: `boolean`, const: `true`

  The person on camera was told what is measured and who receives it, agreed to it, and can stop it at any time.
- **`subjectIsAdult` (required)**: `boolean`, const: `true`

  The person on camera is 18 or older, or older where their local law requires, and you verified it.
- **`consentedAt`**: `string`, format: `date-time`

  When the person agreed.
- **`consentRecordId`**: `string`, maxLength: `255`

  Your reference to the stored consent record, for audits.

<a id="scalar-example-46"></a>

**Generated example:**

```json
{
  "subjectIsAdult": true,
  "subjectConsented": true,
  "ageVerification": "document",
  "consentedAt": "",
  "consentRecordId": ""
}
```

<a id="scalar-schema-declaredinputs"></a>

### DeclaredInputs

**Type:** `object`

What the device will publish besides the face, which is always required. Declaring an input you do not send raises an `input.warning`.

- **`audio`**: `boolean`, default: `true`

  The microphone is published with the camera. Recommended: onset, peak and end need it.
- **`body`**: `boolean`, default: `false`

  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.

<a id="scalar-example-47"></a>

**Generated example:**

```json
{
  "audio": true,
  "body": false
}
```

<a id="scalar-schema-scenarioname"></a>

### ScenarioName

**Type:** `string`, possible values: `"woman-onset-end", "man-peak", "undetermined", "face-only", "face-lost", "edge", "ruin", "finish"`

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.

<a id="scalar-schema-sandboxoptions"></a>

### SandboxOptions

**Type:** `object`

Test mode only. Refused with `sandbox_only` when sent with a live key.

- **`scenario`**: `string`, possible values: `"woman-onset-end", "man-peak", "undetermined", "face-only", "face-lost", "edge", "ruin", "finish"`

  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.
- **`speed`**: `number`, minimum: `1`, maximum: `60`

  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.

<a id="scalar-example-48"></a>

**Generated example:**

```json
{
  "scenario": "woman-onset-end",
  "speed": 1
}
```

<a id="scalar-schema-metadata"></a>

### Metadata

**Type:** `object`, maxProperties: `20`

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`.

**Additional properties:**

`string`, maxLength: `500`

<a id="scalar-example-49"></a>

**Generated example:**

```json
{
  "additionalProperty": ""
}
```

<a id="scalar-schema-userreference"></a>

### UserReference

**Type:** `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

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.

<a id="scalar-schema-clientreferenceid"></a>

### ClientReferenceId

**Type:** `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

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`.

<a id="scalar-schema-livesessionstatus"></a>

### LiveSessionStatus

**Type:** `string`, possible values: `"starting", "ready", "calibrating", "analyzing", "ended"`

Where a live session is in its life: `starting`, `ready`, `calibrating`, `analyzing`, `ended`.

<a id="scalar-schema-livesessioncreaterequest"></a>

### LiveSessionCreateRequest

**Type:** `object`

What to create a live session with. Only `consent` is required.

- **`consent` (required)**: [Consent](#scalar-schema-consent)

  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.
- **`capabilityHash`**: `string`, pattern: `^[0-9a-f]{64}$`

  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.
- **`clientReferenceId`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  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`.
- **`inputs`**: [DeclaredInputs](#scalar-schema-declaredinputs)

  What the device will publish besides the face, which is always required. Declaring an input you do not send raises an `input.warning`.
- **`maxDurationS`**: `integer`, default: `3600`, minimum: `60`, maximum: `14400`

  The session ends after this many seconds (`max_duration`).
- **`metadata`**: [Metadata](#scalar-schema-metadata)

  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`.
- **`retentionDays`**: `integer`, default: `30`, minimum: `0`, maximum: `90`

  How many days the session's events stay readable after it ends. `0` keeps nothing: events are only delivered as they happen.
- **`sandbox`**: [SandboxOptions](#scalar-schema-sandboxoptions)

  Test mode only. Refused with `sandbox_only` when sent with a live key.
- **`subjectHint`**: `string`, possible values: `"woman", "man"`

  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.
- **`userReference`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  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.
- **`webhookEndpointId`**: `string`, pattern: `^we_[0-9a-z]{20}$`

  Deliver this session's events to this endpoint only. Leave it out to deliver to every enabled endpoint subscribed to each event type.

<a id="scalar-example-50"></a>

**Generated example:**

```json
{
  "consent": {
    "subjectIsAdult": true,
    "subjectConsented": true,
    "ageVerification": "document",
    "consentedAt": "",
    "consentRecordId": ""
  },
  "inputs": {
    "audio": true,
    "body": false
  },
  "subjectHint": "woman",
  "capabilityHash": "",
  "maxDurationS": 3600,
  "retentionDays": 30,
  "webhookEndpointId": "",
  "userReference": "",
  "clientReferenceId": "",
  "metadata": {
    "additionalProperty": ""
  },
  "sandbox": {
    "scenario": "woman-onset-end",
    "speed": 1
  }
}
```

<a id="scalar-schema-videorequirements"></a>

### VideoRequirements

**Type:** `object`

What the video track must be.

- **`codecs` (required)**: `array`

  **Items:**

  `string`, possible values: `"H264", "H265"`
- **`maxLongEdgePx` (required)**: `integer`

  Larger frames are scaled down to this long edge.
- **`recommendedFps` (required)**: `integer`

<a id="scalar-example-51"></a>

**Generated example:**

```json
{
  "codecs": [
    "H264"
  ],
  "maxLongEdgePx": 1,
  "recommendedFps": 1
}
```

<a id="scalar-schema-ingest"></a>

### Ingest

**Type:** `object`

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.

- **`attestationUrl` (required)**: `string`, format: `uri`

  The enclave's attestation. Check it before publishing.
- **`audio` (required)**: `object`
  - **`codecs` (required)**: `array`

    **Items:**

    `string`, possible values: `"opus"`
  - **`expected` (required)**: `boolean`

    Whether the session declared the microphone.
- **`bodyUrl` (required)**: `string | null`, format: `uri`

  WHIP endpoint for the optional body view, when `inputs.body` is true.
- **`expiresAt` (required)**: `string`, format: `date-time`

  Publish before this time, or the session ends with `media_timeout`.
- **`iceServersUrl` (required)**: `string`, format: `uri`

  STUN and TURN servers for devices on strict networks; read with the client token.
- **`protocol` (required)**: `string`, const: `"whip"`
- **`seal` (required)**: `string`, const: `"v1"`

  The request-sealing scheme the enclave requires.
- **`url` (required)**: `string`, format: `uri`

  WHIP endpoint for the face camera (and the microphone). POST the SDP offer here, sealed with the capability.
- **`video` (required)**: [VideoRequirements](#scalar-schema-videorequirements)

  What the video track must be.

<a id="scalar-example-52"></a>

**Generated example:**

```json
{
  "protocol": "whip",
  "url": "",
  "bodyUrl": null,
  "attestationUrl": "",
  "seal": "v1",
  "iceServersUrl": "",
  "expiresAt": "",
  "video": {
    "codecs": [
      "H264"
    ],
    "maxLongEdgePx": 1,
    "recommendedFps": 1
  },
  "audio": {
    "codecs": [
      "opus"
    ],
    "expected": true
  }
}
```

<a id="scalar-schema-results"></a>

### Results

**Type:** `object`

Where the session's events arrive.

- **`clientToken` (required)**: `string`, pattern: `^ct_[0-9a-z]{32}$`

  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`).
- **`clientTokenExpiresAt` (required)**: `string`, format: `date-time`

  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.
- **`eventsUrl` (required)**: `string`, format: `uri`

  The event list, for polling (`listLiveSessionEvents`).
- **`streamUrl` (required)**: `string`, format: `uri`

  Server-sent events (`streamLiveSessionEvents`).
- **`websocketUrl` (required)**: `string`, format: `uri`

  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.

<a id="scalar-example-53"></a>

**Generated example:**

```json
{
  "streamUrl": "",
  "websocketUrl": "",
  "eventsUrl": "",
  "clientToken": "",
  "clientTokenExpiresAt": ""
}
```

<a id="scalar-schema-latestimminence"></a>

### LatestImminence

**Type:** `object`

The newest `imminence.updated`, in brief.

- **`eventId` (required)**: `string`, pattern: `^evt_[0-9a-z]{20}$`
- **`p30` (required)**: `number | null`, minimum: `0`, maximum: `1`
- **`p60` (required)**: `number | null`, minimum: `0`, maximum: `1`
- **`streamTimeS` (required)**: `number`

<a id="scalar-example-54"></a>

**Generated example:**

```json
{
  "p30": null,
  "p60": null,
  "streamTimeS": 1,
  "eventId": ""
}
```

<a id="scalar-schema-livesession"></a>

### LiveSession

**Type:** `object`

One person's live camera stream, from creation to its final status.

- **`charges` (required)**: [LiveSessionCharges](#scalar-schema-livesessioncharges)

  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.
- **`clientReferenceId` (required)**: `string | null`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  The `clientReferenceId` it was created with, or `null`.
- **`createdAt` (required)**: `string`, format: `date-time`
- **`degraded` (required)**: `boolean`

  A declared input is missing or the face is not visible.
- **`enclave` (required)**: [EnclaveReceipt](#scalar-schema-enclavereceipt) | `null`

  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.
- **`endedAt` (required)**: `string | null`, format: `date-time`
- **`endedReason` (required)**: `string | null`, possible values: `"client_ended", "media_ended", "media_timeout", "max_duration", "interrupted", "policy", "error", null`
- **`id` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`
- **`ingest` (required)**: [Ingest](#scalar-schema-ingest) | `null`

  `null` once the session has ended.
- **`inputs` (required)**: [InputsPresence](#scalar-schema-inputspresence)

  Which inputs are arriving right now.
- **`latestImminence` (required)**: [LatestImminence](#scalar-schema-latestimminence) | `null`

  The newest `imminence.updated`, in brief.
- **`maxDurationS` (required)**: `integer`
- **`metadata` (required)**: [Metadata](#scalar-schema-metadata)

  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`.
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`object` (required)**: `string`, const: `"live_session"`
- **`results` (required)**: [Results](#scalar-schema-results)

  Where the session's events arrive.
- **`resultsExpireAt` (required)**: `string | null`, format: `date-time`

  When the session's events are deleted, once it has ended.
- **`retentionDays` (required)**: `integer`
- **`sandbox` (required)**: [SandboxOptions](#scalar-schema-sandboxoptions) | `null`

  The sandbox options the session plays, or `null` in live mode.
- **`signals` (required)**: `array`

  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`.

  **Items:**

  `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

  The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
- **`startedAt` (required)**: `string | null`, format: `date-time`

  When media first arrived.
- **`status` (required)**: `string`, possible values: `"starting", "ready", "calibrating", "analyzing", "ended"`

  Where a live session is in its life: `starting`, `ready`, `calibrating`, `analyzing`, `ended`.
- **`subject` (required)**: [SubjectIdentifiedData](#scalar-schema-subjectidentifieddata) | `null`

  The subject read, once it is made (`subject.identified`).
- **`subjectHint` (required)**: `string | null`, possible values: `"woman", "man", null`
- **`userReference` (required)**: `string | null`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  The `userReference` it was created with, or `null`.
- **`webhookEndpointId` (required)**: `string | null`

<a id="scalar-example-55"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "live_session",
  "mode": "test",
  "status": "starting",
  "degraded": true,
  "inputs": {
    "face": {
      "present": true,
      "baselineReady": true
    },
    "audio": {
      "declared": true,
      "present": true
    },
    "body": {
      "declared": true,
      "present": true
    }
  },
  "signals": [
    "imminence.updated"
  ],
  "subject": {
    "sex": "woman",
    "pWoman": null,
    "secondsObserved": 0,
    "decidedAtS": 1,
    "hint": "woman",
    "detectors": [
      "onset_end"
    ]
  },
  "latestImminence": {
    "p30": null,
    "p60": null,
    "streamTimeS": 1,
    "eventId": ""
  },
  "ingest": {
    "protocol": "whip",
    "url": "",
    "bodyUrl": null,
    "attestationUrl": "",
    "seal": "v1",
    "iceServersUrl": "",
    "expiresAt": "",
    "video": {
      "codecs": [
        "H264"
      ],
      "maxLongEdgePx": 1,
      "recommendedFps": 1
    },
    "audio": {
      "codecs": [
        "opus"
      ],
      "expected": true
    }
  },
  "enclave": {
    "imageDigest": "",
    "release": null,
    "commit": null,
    "releaseUrl": null,
    "signers": [
      ""
    ],
    "hardware": {
      "cpu": "",
      "gpus": [
        ""
      ],
      "gpuConfidentialComputing": true,
      "secureBoot": true
    },
    "debugging": "",
    "confidentialSpace": [
      ""
    ],
    "projectId": null,
    "zone": null,
    "instanceId": "",
    "tlsBound": true,
    "attestedAt": "",
    "verifiedAt": "",
    "attestationToken": ""
  },
  "charges": {
    "orgasms": 0,
    "ruins": 0,
    "edges": 0,
    "sessionMinimum": true,
    "credits": 0
  },
  "results": {
    "streamUrl": "",
    "websocketUrl": "",
    "eventsUrl": "",
    "clientToken": "",
    "clientTokenExpiresAt": ""
  },
  "subjectHint": "woman",
  "maxDurationS": 1,
  "retentionDays": 1,
  "webhookEndpointId": null,
  "userReference": "",
  "clientReferenceId": "",
  "metadata": {
    "additionalProperty": ""
  },
  "sandbox": {
    "scenario": "woman-onset-end",
    "speed": 1
  },
  "createdAt": "",
  "startedAt": null,
  "endedAt": null,
  "endedReason": "client_ended",
  "resultsExpireAt": null
}
```

<a id="scalar-schema-livesessioncharges"></a>

### LiveSessionCharges

**Type:** `object`

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.

- **`credits` (required)**: `number`, minimum: `0`, multipleOf: `0.5`

  Credits drawn, in halves.
- **`edges` (required)**: `integer`, minimum: `0`

  Edges charged, half a credit each.
- **`orgasms` (required)**: `integer`, minimum: `0`

  Orgasms charged, a credit each.
- **`ruins` (required)**: `integer`, minimum: `0`

  Ruined orgasms charged, a credit each.
- **`sessionMinimum` (required)**: `boolean`

  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`.

<a id="scalar-example-56"></a>

**Generated example:**

```json
{
  "orgasms": 0,
  "ruins": 0,
  "edges": 0,
  "sessionMinimum": true,
  "credits": 0
}
```

<a id="scalar-schema-livesessionlist"></a>

### LiveSessionList

**Type:** `object`

A page of live sessions.

- **`data` (required)**: array of [LiveSession](#scalar-schema-livesession)
- **`hasMore` (required)**: `boolean`
- **`nextCursor` (required)**: `string | null`
- **`object` (required)**: `string`, const: `"list"`

<a id="scalar-example-57"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "live_session",
      "mode": "test",
      "status": "starting",
      "degraded": true,
      "inputs": {
        "face": {
          "present": true,
          "baselineReady": true
        },
        "audio": {
          "declared": true,
          "present": true
        },
        "body": {
          "declared": true,
          "present": true
        }
      },
      "signals": [
        "imminence.updated"
      ],
      "subject": {
        "sex": "woman",
        "pWoman": null,
        "secondsObserved": 0,
        "decidedAtS": 1,
        "hint": "woman",
        "detectors": [
          "onset_end"
        ]
      },
      "latestImminence": {
        "p30": null,
        "p60": null,
        "streamTimeS": 1,
        "eventId": ""
      },
      "ingest": {
        "protocol": "whip",
        "url": "",
        "bodyUrl": null,
        "attestationUrl": "",
        "seal": "v1",
        "iceServersUrl": "",
        "expiresAt": "",
        "video": {
          "codecs": [
            "H264"
          ],
          "maxLongEdgePx": 1,
          "recommendedFps": 1
        },
        "audio": {
          "codecs": [
            "opus"
          ],
          "expected": true
        }
      },
      "enclave": {
        "imageDigest": "",
        "release": null,
        "commit": null,
        "releaseUrl": null,
        "signers": [
          ""
        ],
        "hardware": {
          "cpu": "",
          "gpus": [
            ""
          ],
          "gpuConfidentialComputing": true,
          "secureBoot": true
        },
        "debugging": "",
        "confidentialSpace": [
          ""
        ],
        "projectId": null,
        "zone": null,
        "instanceId": "",
        "tlsBound": true,
        "attestedAt": "",
        "verifiedAt": "",
        "attestationToken": ""
      },
      "charges": {
        "orgasms": 0,
        "ruins": 0,
        "edges": 0,
        "sessionMinimum": true,
        "credits": 0
      },
      "results": {
        "streamUrl": "",
        "websocketUrl": "",
        "eventsUrl": "",
        "clientToken": "",
        "clientTokenExpiresAt": ""
      },
      "subjectHint": "woman",
      "maxDurationS": 1,
      "retentionDays": 1,
      "webhookEndpointId": null,
      "userReference": "",
      "clientReferenceId": "",
      "metadata": {
        "additionalProperty": ""
      },
      "sandbox": {
        "scenario": "woman-onset-end",
        "speed": 1
      },
      "createdAt": "",
      "startedAt": null,
      "endedAt": null,
      "endedReason": "client_ended",
      "resultsExpireAt": null
    }
  ],
  "hasMore": true,
  "nextCursor": null
}
```

<a id="scalar-schema-livesessionpurgerequest"></a>

### LiveSessionPurgeRequest

**Type:** `object`

Whose live sessions to purge.

- **`userReference` (required)**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  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.

<a id="scalar-example-58"></a>

**Generated example:**

```json
{
  "userReference": ""
}
```

<a id="scalar-schema-livesessionpurgeresult"></a>

### LiveSessionPurgeResult

**Type:** `object`

The live sessions a purge deleted.

- **`deleted` (required)**: `integer`, minimum: `0`

  How many sessions were deleted.
- **`ids` (required)**: `array`

  The deleted sessions' ids.

  **Items:**

  `string`, pattern: `^ls_[0-9a-z]{20}$`
- **`object` (required)**: `string`, const: `"live_session_purge"`
- **`userReference` (required)**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  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.

<a id="scalar-example-59"></a>

**Generated example:**

```json
{
  "object": "live_session_purge",
  "userReference": "",
  "deleted": 0,
  "ids": [
    ""
  ]
}
```

<a id="scalar-schema-eventunion"></a>

### EventUnion

Any event. Switch on `type`.

**One of:** discriminated by `type`

- [ImminenceUpdatedEvent](#scalar-schema-imminenceupdatedevent), type: `imminence.updated`

  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.
- [SignalsUpdatedEvent](#scalar-schema-signalsupdatedevent), type: `signals.updated`

  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.
- [StimulationUpdatedEvent](#scalar-schema-stimulationupdatedevent), type: `stimulation.updated`

  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.
- [OrgasmOnsetEvent](#scalar-schema-orgasmonsetevent), type: `orgasm.onset`

  An orgasm began. Applies to women (the `onset_end` detector). Requires the microphone. The call arrives a few seconds after the moment it names.
- [OrgasmPeakEvent](#scalar-schema-orgasmpeakevent), type: `orgasm.peak`

  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.
- [OrgasmEndEvent](#scalar-schema-orgasmendevent), type: `orgasm.end`

  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`).
- [EdgeCompletedEvent](#scalar-schema-edgecompletedevent), type: `edge.completed`

  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.
- [SubjectIdentifiedEvent](#scalar-schema-subjectidentifiedevent), type: `subject.identified`

  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.
- [SessionStatusEvent](#scalar-schema-sessionstatusevent), type: `session.status`

  The live session changed status, or its inputs changed.
- [InputWarningEvent](#scalar-schema-inputwarningevent), type: `input.warning`

  An input problem started (`raised`) or stopped (`cleared`). Show `message` to the person when it helps them fix it.
- [RecordingCompletedEvent](#scalar-schema-recordingcompletedevent), type: `recording.completed`

  A recording finished processing. Fetch its events with `listRecordingEvents`.
- [RecordingFailedEvent](#scalar-schema-recordingfailedevent), type: `recording.failed`

  A recording could not be processed.

<a id="scalar-schema-eventlist"></a>

### EventList

**Type:** `object`

A page of events, oldest first.

- **`data` (required)**: array of [EventUnion](#scalar-schema-eventunion)
- **`hasMore` (required)**: `boolean`

  More events are available now; ask again with `after` set to `nextCursor`.
- **`nextCursor` (required)**: `string | null`

  The `id` of the last event in `data`, to pass as `after`. `null` when `data` is empty.
- **`object` (required)**: `string`, const: `"list"`

<a id="scalar-example-60"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "evt_4q7m2k9x8w1c3n6b5v0z",
      "object": "event",
      "type": "imminence.updated",
      "mode": "test",
      "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
      "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
      "sequence": 1,
      "streamTimeS": 0,
      "wallTime": "",
      "confidence": "high",
      "data": {
        "p30": null,
        "p60": null,
        "logit30": null,
        "logit60": null,
        "featuresPresent": 0,
        "faceVisible": true,
        "baselineReady": true,
        "stimulationAware": true,
        "recentCalls": [
          {
            "id": "",
            "type": "orgasm.onset",
            "eventAtS": 1
          }
        ]
      }
    }
  ],
  "hasMore": true,
  "nextCursor": null
}
```

<a id="scalar-schema-stimulationreport"></a>

### StimulationReport

**Type:** `object`

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.

- **`state` (required)**: `string`, possible values: `"on", "off"`

  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.
- **`channels`**: array of [StimulationReportChannel](#scalar-schema-stimulationreportchannel) | `null`, maxItems: `4`

  Each output's level, for a device with more than one (at most four).
- **`device`**: [StimulationReportDevice](#scalar-schema-stimulationreportdevice) | `null`

  The device your product drives.
- **`drive`**: `string | null`, possible values: `"auto", "manual", "hold", "paused", null`

  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`.
- **`intensity`**: `number | null`, minimum: `0`, maximum: `1`

  The intensity now, from 0 to 1 on your product's own scale. Omit it if your product has no intensity.
- **`level`**: `number | null`, minimum: `0`

  The device's level now, on its own scale (for example 0 to 100).
- **`levelMax`**: `number | null`, exclusiveMinimum: `0`

  The highest level the device will go to now, on the same scale; a display fills a bar toward it.
- **`mode`**: `string | null`, maxLength: `40`

  The device's mode or pattern, as your product names it (for example `waves`).
- **`modeLabel`**: `string | null`, maxLength: `40`

  The mode's name to show the person; without it a display shows `mode` in words.
- **`streamTimeS`**: `number`, minimum: `0`

  When the change happened, in stream seconds. Omit it to mean now.

<a id="scalar-example-61"></a>

**Generated example:**

```json
{
  "state": "on",
  "intensity": null,
  "level": null,
  "levelMax": null,
  "channels": [
    {
      "id": "",
      "level": 0,
      "levelMax": null
    }
  ],
  "mode": null,
  "modeLabel": null,
  "device": {
    "label": null,
    "connected": true
  },
  "drive": "auto",
  "streamTimeS": 0
}
```

<a id="scalar-schema-createviewtokenrequest"></a>

### CreateViewTokenRequest

**Type:** `object`, no additional properties

What a view token may read, and for how long.

- **`expiresInS`**: `integer`, minimum: `60`, maximum: `86400`

  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.
- **`includeFace`**: `boolean`, default: `false`

  Include the face's channels: `signals.updated` with its `face`, and `face.frame` on a stream that asks for them. False by default.
- **`includeSubject`**: `boolean`, default: `false`

  Include `subject.identified`, the face read. False by default.

<a id="scalar-example-62"></a>

**Generated example:**

```json
{
  "includeSubject": false,
  "includeFace": false,
  "expiresInS": 60
}
```

<a id="scalar-schema-viewtoken"></a>

### ViewToken

**Type:** `object`

A read-only token for one session's events (`createViewToken`).

- **`createdAt` (required)**: `string`, format: `date-time`
- **`eventTypes` (required)**: `array`

  The event types the token reads.

  **Items:**

  `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

  The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
- **`expiresAt` (required)**: `string`, format: `date-time`

  The latest the token works; it stops sooner, five minutes after the session ends.
- **`face` (required)**: `boolean`

  Whether the token reads the face's channels (`includeFace`).
- **`object` (required)**: `string`, const: `"view_token"`
- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`
- **`token` (required)**: `string`, pattern: `^vt_[0-9a-z]{32}$`

  Sent as `Authorization: Bearer vt_…`. Shown only once.

<a id="scalar-example-63"></a>

**Generated example:**

```json
{
  "object": "view_token",
  "token": "",
  "sessionId": "",
  "eventTypes": [
    "imminence.updated"
  ],
  "face": true,
  "createdAt": "",
  "expiresAt": ""
}
```

<a id="scalar-schema-stimulationreceipt"></a>

### StimulationReceipt

**Type:** `object`

Confirms a stimulation report, with the stimulation as it now stands: this report merged over the ones before it.

- **`intensity` (required)**: `number | null`
- **`object` (required)**: `string`, const: `"stimulation_report"`
- **`sessionId` (required)**: `string`
- **`state` (required)**: `string`, possible values: `"on", "off"`
- **`stimulation` (required)**: [StimulationData](#scalar-schema-stimulationdata)

  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.
- **`stimulationAware` (required)**: `boolean`

  Imminence now accounts for time under stimulation.
- **`streamTimeS` (required)**: `number`

<a id="scalar-example-64"></a>

**Generated example:**

```json
{
  "object": "stimulation_report",
  "sessionId": "",
  "state": "on",
  "intensity": null,
  "streamTimeS": 1,
  "stimulationAware": true,
  "stimulation": {
    "state": "on",
    "intensity": null,
    "level": null,
    "levelMax": null,
    "channels": [
      {
        "id": "",
        "level": 0,
        "levelMax": null
      }
    ],
    "mode": null,
    "modeLabel": null,
    "device": {
      "label": null,
      "connected": true
    },
    "drive": "auto",
    "changedAtS": 0
  }
}
```

<a id="scalar-schema-recordingstatus"></a>

### RecordingStatus

**Type:** `string`, possible values: `"awaiting_upload", "queued", "processing", "completed", "failed"`

Where a recording is in processing.

<a id="scalar-schema-recordingsourceupload"></a>

### RecordingSourceUpload

**Type:** `object`

You upload the file to `uploads.face.url`.

- **`type` (required)**: `string`, const: `"upload"`
- **`bodyOffsetS`**: `number`, default: `0`

  The body video starts this many seconds after the face video.
- **`bodyView`**: `boolean`, default: `false`

  You will also upload a second video of the person's body, recorded at the same time.

<a id="scalar-example-65"></a>

**Generated example:**

```json
{
  "type": "upload",
  "bodyView": false,
  "bodyOffsetS": 0
}
```

<a id="scalar-schema-recordingsourceurl"></a>

### RecordingSourceUrl

**Type:** `object`

The enclave fetches the file from `url`.

- **`type` (required)**: `string`, const: `"url"`
- **`url` (required)**: `string`, format: `uri`

  An HTTPS URL the enclave can fetch the face video from, such as a signed URL valid for at least an hour.
- **`bodyOffsetS`**: `number`, default: `0`

  The body video starts this many seconds after the face video.
- **`bodyUrl`**: `string`, format: `uri`

  An HTTPS URL for an optional body video recorded at the same time.

<a id="scalar-example-66"></a>

**Generated example:**

```json
{
  "type": "url",
  "url": "",
  "bodyUrl": "",
  "bodyOffsetS": 0
}
```

<a id="scalar-schema-recordingcreaterequest"></a>

### RecordingCreateRequest

**Type:** `object`

What to submit a recording with. `consent` and `source` are required.

- **`consent` (required)**: [Consent](#scalar-schema-consent)

  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.
- **`source` (required)**

  **One of:** discriminated by `type`
  - [RecordingSourceUpload](#scalar-schema-recordingsourceupload), type: `upload`

    You upload the file to `uploads.face.url`.
  - [RecordingSourceUrl](#scalar-schema-recordingsourceurl), type: `url`

    The enclave fetches the file from `url`.
- **`clientReferenceId`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  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`.
- **`inputs`**: `object`

  Whether to analyse the recording's audio track (recommended).
  - **`audio`**: `boolean`, default: `true`
- **`metadata`**: [Metadata](#scalar-schema-metadata)

  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`.
- **`retentionDays`**: `integer`, default: `30`, minimum: `0`, maximum: `90`
- **`sandbox`**: [SandboxOptions](#scalar-schema-sandboxoptions)

  Test mode only. Refused with `sandbox_only` when sent with a live key.
- **`subjectHint`**: `string`, possible values: `"woman", "man"`
- **`userReference`**: `string`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  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.
- **`webhookEndpointId`**: `string`, pattern: `^we_[0-9a-z]{20}$`

<a id="scalar-example-67"></a>

**Generated example:**

```json
{
  "consent": {
    "subjectIsAdult": true,
    "subjectConsented": true,
    "ageVerification": "document",
    "consentedAt": "",
    "consentRecordId": ""
  },
  "source": {
    "type": "upload",
    "bodyView": false,
    "bodyOffsetS": 0
  },
  "inputs": {
    "audio": true
  },
  "subjectHint": "woman",
  "retentionDays": 30,
  "webhookEndpointId": "",
  "userReference": "",
  "clientReferenceId": "",
  "metadata": {
    "additionalProperty": ""
  },
  "sandbox": {
    "scenario": "woman-onset-end",
    "speed": 1
  }
}
```

<a id="scalar-schema-upload"></a>

### Upload

**Type:** `object`

Where to `PUT` one video file.

- **`expiresAt` (required)**: `string`, format: `date-time`
- **`headers` (required)**: `object`

  Headers to send with the upload.

  **Additional properties:**

  `string`
- **`maxBytes` (required)**: `integer`
- **`method` (required)**: `string`, const: `"PUT"`
- **`sealed` (required)**: `boolean`

  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.
- **`url` (required)**: `string`, format: `uri`

<a id="scalar-example-68"></a>

**Generated example:**

```json
{
  "url": "",
  "method": "PUT",
  "headers": {
    "additionalProperty": ""
  },
  "maxBytes": 1,
  "expiresAt": "",
  "sealed": true
}
```

<a id="scalar-schema-orgasmsummary"></a>

### OrgasmSummary

**Type:** `object`

One orgasm in a recording, assembled from its calls.

- **`confidence` (required)**: `string | null`, possible values: `"high", "medium", "low", null`

  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.
- **`detectors` (required)**: `array`

  **Items:**

  `string`, possible values: `"onset_end", "peak", "face_end"`

  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.
- **`durationS` (required)**: `number | null`
- **`endAtS` (required)**: `number | null`
- **`onsetAtS` (required)**: `number | null`
- **`orgasmIndex` (required)**: `integer`, minimum: `1`
- **`peakAtS` (required)**: `number | null`

<a id="scalar-example-69"></a>

**Generated example:**

```json
{
  "orgasmIndex": 1,
  "detectors": [
    "onset_end"
  ],
  "onsetAtS": null,
  "peakAtS": null,
  "endAtS": null,
  "durationS": null,
  "confidence": "high"
}
```

<a id="scalar-schema-recordingresult"></a>

### RecordingResult

**Type:** `object`

What the analysis found in a recording.

- **`subject` (required)**: [SubjectIdentifiedData](#scalar-schema-subjectidentifieddata) | `null`
- **`summary` (required)**: `object`
  - **`durationS` (required)**: `number`
  - **`orgasmCount` (required)**: `integer`, minimum: `0`
  - **`orgasms` (required)**: array of [OrgasmSummary](#scalar-schema-orgasmsummary)
- **`timeline` (required)**: array of [EventUnion](#scalar-schema-eventunion)

  The discrete events, in order: orgasm calls, the subject read and input warnings. Imminence is in `listRecordingEvents`.

<a id="scalar-example-70"></a>

**Generated example:**

```json
{
  "subject": {
    "sex": "woman",
    "pWoman": null,
    "secondsObserved": 0,
    "decidedAtS": 1,
    "hint": "woman",
    "detectors": [
      "onset_end"
    ]
  },
  "summary": {
    "durationS": 1,
    "orgasmCount": 0,
    "orgasms": [
      {
        "orgasmIndex": 1,
        "detectors": [
          "onset_end"
        ],
        "onsetAtS": null,
        "peakAtS": null,
        "endAtS": null,
        "durationS": null,
        "confidence": "high"
      }
    ]
  },
  "timeline": [
    {
      "id": "evt_4q7m2k9x8w1c3n6b5v0z",
      "object": "event",
      "type": "imminence.updated",
      "mode": "test",
      "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
      "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
      "sequence": 1,
      "streamTimeS": 0,
      "wallTime": "",
      "confidence": "high",
      "data": {
        "p30": null,
        "p60": null,
        "logit30": null,
        "logit60": null,
        "featuresPresent": 0,
        "faceVisible": true,
        "baselineReady": true,
        "stimulationAware": true,
        "recentCalls": [
          {
            "id": "",
            "type": "orgasm.onset",
            "eventAtS": 1
          }
        ]
      }
    }
  ]
}
```

<a id="scalar-schema-recording"></a>

### Recording

**Type:** `object`

One recorded video, from submission to its result.

- **`clientReferenceId` (required)**: `string | null`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  The `clientReferenceId` it was submitted with, or `null`.
- **`completedAt` (required)**: `string | null`, format: `date-time`
- **`createdAt` (required)**: `string`, format: `date-time`
- **`failure` (required)**: [RecordingFailedData](#scalar-schema-recordingfaileddata) | `null`

  Present once `status` is `failed`.
- **`id` (required)**: `string`, pattern: `^rec_[0-9a-z]{20}$`
- **`inputs` (required)**: `object`
  - **`audio` (required)**: `boolean`
  - **`body` (required)**: `boolean`
- **`metadata` (required)**: [Metadata](#scalar-schema-metadata)

  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`.
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`object` (required)**: `string`, const: `"recording"`
- **`progress` (required)**: `object | null`

  How far processing has got, while `processing`.
  - **`durationS` (required)**: `number | null`
  - **`processedS` (required)**: `number`
- **`result` (required)**: [RecordingResult](#scalar-schema-recordingresult) | `null`

  Present once `status` is `completed`.
- **`resultsExpireAt` (required)**: `string | null`, format: `date-time`
- **`retentionDays` (required)**: `integer`
- **`sandbox` (required)**: [SandboxOptions](#scalar-schema-sandboxoptions) | `null`

  Test mode only. Refused with `sandbox_only` when sent with a live key.
- **`source` (required)**: `object`
  - **`type` (required)**: `string`, possible values: `"upload", "url"`
  - **`url`**: `string`

    The URL the enclave fetched, without its query string.
- **`startedAt` (required)**: `string | null`, format: `date-time`

  When processing started.
- **`status` (required)**: `string`, possible values: `"awaiting_upload", "queued", "processing", "completed", "failed"`

  Where a recording is in processing.
- **`subjectHint` (required)**: `string | null`, possible values: `"woman", "man", null`
- **`uploads` (required)**: `object | null`

  Where to upload, while `status` is `awaiting_upload`; `null` after.
  - **`body` (required)**: [Upload](#scalar-schema-upload) | `null`

    Where to `PUT` one video file.
  - **`face` (required)**: [Upload](#scalar-schema-upload)

    Where to `PUT` one video file.
- **`userReference` (required)**: `string | null`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  The `userReference` it was submitted with, or `null`.
- **`webhookEndpointId` (required)**: `string | null`

<a id="scalar-example-71"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "recording",
  "mode": "test",
  "status": "awaiting_upload",
  "source": {
    "type": "upload",
    "url": ""
  },
  "uploads": {
    "face": {
      "url": "",
      "method": "PUT",
      "headers": {
        "additionalProperty": ""
      },
      "maxBytes": 1,
      "expiresAt": "",
      "sealed": true
    },
    "body": {
      "url": "",
      "method": "PUT",
      "headers": {
        "additionalProperty": ""
      },
      "maxBytes": 1,
      "expiresAt": "",
      "sealed": true
    }
  },
  "inputs": {
    "audio": true,
    "body": true
  },
  "progress": {
    "processedS": 1,
    "durationS": null
  },
  "result": {
    "subject": {
      "sex": "woman",
      "pWoman": null,
      "secondsObserved": 0,
      "decidedAtS": 1,
      "hint": "woman",
      "detectors": [
        "onset_end"
      ]
    },
    "summary": {
      "durationS": 1,
      "orgasmCount": 0,
      "orgasms": [
        {
          "orgasmIndex": 1,
          "detectors": [
            "onset_end"
          ],
          "onsetAtS": null,
          "peakAtS": null,
          "endAtS": null,
          "durationS": null,
          "confidence": "high"
        }
      ]
    },
    "timeline": [
      {
        "id": "evt_4q7m2k9x8w1c3n6b5v0z",
        "object": "event",
        "type": "imminence.updated",
        "mode": "test",
        "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
        "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
        "sequence": 1,
        "streamTimeS": 0,
        "wallTime": "",
        "confidence": "high",
        "data": {
          "p30": null,
          "p60": null,
          "logit30": null,
          "logit60": null,
          "featuresPresent": 0,
          "faceVisible": true,
          "baselineReady": true,
          "stimulationAware": true,
          "recentCalls": [
            {
              "id": "",
              "type": "orgasm.onset",
              "eventAtS": 1
            }
          ]
        }
      }
    ]
  },
  "failure": {
    "code": "unreadable_media",
    "message": ""
  },
  "subjectHint": "woman",
  "retentionDays": 1,
  "webhookEndpointId": null,
  "userReference": "",
  "clientReferenceId": "",
  "metadata": {
    "additionalProperty": ""
  },
  "sandbox": {
    "scenario": "woman-onset-end",
    "speed": 1
  },
  "createdAt": "",
  "startedAt": null,
  "completedAt": null,
  "resultsExpireAt": null
}
```

<a id="scalar-schema-recordinglist"></a>

### RecordingList

**Type:** `object`

A page of recordings.

- **`data` (required)**: array of [Recording](#scalar-schema-recording)
- **`hasMore` (required)**: `boolean`
- **`nextCursor` (required)**: `string | null`
- **`object` (required)**: `string`, const: `"list"`

<a id="scalar-example-72"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "recording",
      "mode": "test",
      "status": "awaiting_upload",
      "source": {
        "type": "upload",
        "url": ""
      },
      "uploads": {
        "face": {
          "url": "",
          "method": "PUT",
          "headers": {
            "additionalProperty": ""
          },
          "maxBytes": 1,
          "expiresAt": "",
          "sealed": true
        },
        "body": {
          "url": "",
          "method": "PUT",
          "headers": {
            "additionalProperty": ""
          },
          "maxBytes": 1,
          "expiresAt": "",
          "sealed": true
        }
      },
      "inputs": {
        "audio": true,
        "body": true
      },
      "progress": {
        "processedS": 1,
        "durationS": null
      },
      "result": {
        "subject": {
          "sex": "woman",
          "pWoman": null,
          "secondsObserved": 0,
          "decidedAtS": 1,
          "hint": "woman",
          "detectors": [
            "onset_end"
          ]
        },
        "summary": {
          "durationS": 1,
          "orgasmCount": 0,
          "orgasms": [
            {
              "orgasmIndex": 1,
              "detectors": [
                "onset_end"
              ],
              "onsetAtS": null,
              "peakAtS": null,
              "endAtS": null,
              "durationS": null,
              "confidence": "high"
            }
          ]
        },
        "timeline": [
          {
            "id": "evt_4q7m2k9x8w1c3n6b5v0z",
            "object": "event",
            "type": "imminence.updated",
            "mode": "test",
            "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
            "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
            "sequence": 1,
            "streamTimeS": 0,
            "wallTime": "",
            "confidence": "high",
            "data": {
              "p30": null,
              "p60": null,
              "logit30": null,
              "logit60": null,
              "featuresPresent": 0,
              "faceVisible": true,
              "baselineReady": true,
              "stimulationAware": true,
              "recentCalls": [
                {
                  "id": "",
                  "type": "orgasm.onset",
                  "eventAtS": 1
                }
              ]
            }
          }
        ]
      },
      "failure": {
        "code": "unreadable_media",
        "message": ""
      },
      "subjectHint": "woman",
      "retentionDays": 1,
      "webhookEndpointId": null,
      "userReference": "",
      "clientReferenceId": "",
      "metadata": {
        "additionalProperty": ""
      },
      "sandbox": {
        "scenario": "woman-onset-end",
        "speed": 1
      },
      "createdAt": "",
      "startedAt": null,
      "completedAt": null,
      "resultsExpireAt": null
    }
  ],
  "hasMore": true,
  "nextCursor": null
}
```

<a id="scalar-schema-uploadreceipt"></a>

### UploadReceipt

**Type:** `object`

Confirms a sandbox upload.

- **`bytesReceived` (required)**: `integer`
- **`object` (required)**: `string`, const: `"upload_receipt"`
- **`recordingId` (required)**: `string`
- **`view` (required)**: `string`, possible values: `"face", "body"`

<a id="scalar-example-73"></a>

**Generated example:**

```json
{
  "object": "upload_receipt",
  "recordingId": "",
  "view": "face",
  "bytesReceived": 1
}
```

<a id="scalar-schema-webhookeventtype"></a>

### WebhookEventType

**Type:** `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed", "credits.low"`

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).

<a id="scalar-schema-webhookendpointcreaterequest"></a>

### WebhookEndpointCreateRequest

**Type:** `object`

Where to deliver events, and which.

- **`events` (required)**: `array`, minItems: `1`, uniqueItems: `true`

  The event types to deliver.

  **Items:**

  `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed", "credits.low"`

  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).
- **`url` (required)**: `string`, format: `uri`, pattern: `^(https://|http://localhost(:[0-9]+)?/|http://127\.0\.0\.1(:[0-9]+)?/)`

  An HTTPS URL on your server. In test mode `http://localhost` and `http://127.0.0.1` are accepted too, for local development.
- **`description`**: `string`, maxLength: `500`
- **`enabled`**: `boolean`, default: `true`

<a id="scalar-example-74"></a>

**Generated example:**

```json
{
  "url": "",
  "events": [
    "orgasm.onset"
  ],
  "description": "",
  "enabled": true
}
```

<a id="scalar-schema-webhookendpointupdaterequest"></a>

### WebhookEndpointUpdateRequest

**Type:** `object`, minProperties: `1`

What to change on an endpoint. What you leave out stays as it is.

- **`description`**: `string | null`, maxLength: `500`
- **`enabled`**: `boolean`
- **`events`**: `array`, minItems: `1`, uniqueItems: `true`

  The event types to deliver, replacing the current ones.

  **Items:**

  `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed", "credits.low"`

  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).
- **`url`**: `string`, format: `uri`, pattern: `^(https://|http://localhost(:[0-9]+)?/|http://127\.0\.0\.1(:[0-9]+)?/)`

  An HTTPS URL on your server. In test mode `http://localhost` and `http://127.0.0.1` are accepted too, for local development.

<a id="scalar-example-75"></a>

**Generated example:**

```json
{
  "url": "",
  "events": [
    "orgasm.onset"
  ],
  "description": null,
  "enabled": true
}
```

<a id="scalar-schema-webhookendpoint"></a>

### WebhookEndpoint

**Type:** `object`

A URL on your server that receives events.

- **`createdAt` (required)**: `string`, format: `date-time`
- **`description` (required)**: `string | null`
- **`enabled` (required)**: `boolean`
- **`events` (required)**: `array`

  **Items:**

  `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed", "credits.low"`

  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).
- **`id` (required)**: `string`, pattern: `^we_[0-9a-z]{20}$`
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`object` (required)**: `string`, const: `"webhook_endpoint"`
- **`previousSecretExpiresAt` (required)**: `string | null`, format: `date-time`

  After `rollWebhookSecret`, until when deliveries are also signed with the previous secret; `null` otherwise.
- **`secret` (required)**: `string | null`

  The signing secret (`whsec_` and base64), only in the response that created the endpoint or rolled its secret; `null` afterwards.
- **`url` (required)**: `string`, format: `uri`

<a id="scalar-example-76"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "webhook_endpoint",
  "mode": "test",
  "url": "",
  "events": [
    "orgasm.onset"
  ],
  "description": null,
  "enabled": true,
  "secret": null,
  "previousSecretExpiresAt": null,
  "createdAt": ""
}
```

<a id="scalar-schema-webhookendpointlist"></a>

### WebhookEndpointList

**Type:** `object`

A page of webhook endpoints.

- **`data` (required)**: array of [WebhookEndpoint](#scalar-schema-webhookendpoint)
- **`hasMore` (required)**: `boolean`
- **`nextCursor` (required)**: `string | null`
- **`object` (required)**: `string`, const: `"list"`

<a id="scalar-example-77"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "webhook_endpoint",
      "mode": "test",
      "url": "",
      "events": [
        "orgasm.onset"
      ],
      "description": null,
      "enabled": true,
      "secret": null,
      "previousSecretExpiresAt": null,
      "createdAt": ""
    }
  ],
  "hasMore": true,
  "nextCursor": null
}
```

<a id="scalar-schema-testwebhookrequest"></a>

### TestWebhookRequest

**Type:** `object`

Which event type to send as the sample. Defaults to `orgasm.onset`.

- **`type`**: `string`, possible values: `"orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed", "credits.low"`

  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).

<a id="scalar-example-78"></a>

**Generated example:**

```json
{
  "type": "orgasm.onset"
}
```

<a id="scalar-schema-testwebhookresult"></a>

### TestWebhookResult

**Type:** `object`

How your server answered a test delivery.

- **`delivered` (required)**: `boolean`
- **`durationMs` (required)**: `integer`
- **`error` (required)**: `string | null`

  Why the delivery failed, when it did.
- **`event` (required)**: [EventUnion](#scalar-schema-eventunion) | [CreditsLowEvent](#scalar-schema-creditslowevent)

  The sample that was sent.
- **`headers` (required)**: `object`

  The signature headers that were sent.
  - **`webhookId` (required)**: `string`

    The `webhook-id` header.
  - **`webhookSignature` (required)**: `string`

    The `webhook-signature` header.
  - **`webhookTimestamp` (required)**: `string`

    The `webhook-timestamp` header.
- **`object` (required)**: `string`, const: `"webhook_test"`
- **`statusCode` (required)**: `integer | null`

  Your server's status code, or `null` when no response arrived.

<a id="scalar-example-79"></a>

**Generated example:**

```json
{
  "object": "webhook_test",
  "delivered": true,
  "statusCode": null,
  "durationMs": 1,
  "error": null,
  "headers": {
    "webhookId": "",
    "webhookTimestamp": "",
    "webhookSignature": ""
  },
  "event": {
    "id": "evt_4q7m2k9x8w1c3n6b5v0z",
    "object": "event",
    "type": "imminence.updated",
    "mode": "test",
    "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
    "recordingId": "rec_2n5v8c1x4m7q0w3e6r9t",
    "sequence": 1,
    "streamTimeS": 0,
    "wallTime": "",
    "confidence": "high",
    "data": {
      "p30": null,
      "p60": null,
      "logit30": null,
      "logit60": null,
      "featuresPresent": 0,
      "faceVisible": true,
      "baselineReady": true,
      "stimulationAware": true,
      "recentCalls": [
        {
          "id": "",
          "type": "orgasm.onset",
          "eventAtS": 1
        }
      ]
    }
  }
}
```

<a id="scalar-schema-usageday"></a>

### UsageDay

**Type:** `object`

Usage on one UTC day.

- **`credits` (required)**: `number`

  Credits drawn; 0 in test mode, which is free.
- **`date` (required)**: `string`, format: `date`
- **`edges` (required)**: `integer`

  Edges counted.
- **`liveSeconds` (required)**: `integer`

  Seconds of analysed live media.
- **`liveSessions` (required)**: `integer`
- **`orgasms` (required)**: `integer`

  Orgasms counted in live sessions.
- **`recordings` (required)**: `integer`
- **`recordingSeconds` (required)**: `integer`

  Seconds of analysed recordings.
- **`ruins` (required)**: `integer`

  Ruined orgasms counted.
- **`sessionMinimums` (required)**: `integer`

  Sessions charged the minimum.

<a id="scalar-example-80"></a>

**Generated example:**

```json
{
  "date": "",
  "liveSessions": 1,
  "liveSeconds": 1,
  "recordings": 1,
  "recordingSeconds": 1,
  "orgasms": 1,
  "ruins": 1,
  "edges": 1,
  "sessionMinimums": 1,
  "credits": 1
}
```

<a id="scalar-schema-usage"></a>

### Usage

**Type:** `object`

Usage per day over a range of days.

- **`days` (required)**: array of [UsageDay](#scalar-schema-usageday)
- **`from` (required)**: `string`, format: `date`
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`object` (required)**: `string`, const: `"usage"`
- **`to` (required)**: `string`, format: `date`
- **`totals` (required)**: `object`
  - **`credits` (required)**: `number`
  - **`edges` (required)**: `integer`
  - **`liveSeconds` (required)**: `integer`
  - **`liveSessions` (required)**: `integer`
  - **`orgasms` (required)**: `integer`
  - **`recordings` (required)**: `integer`
  - **`recordingSeconds` (required)**: `integer`
  - **`ruins` (required)**: `integer`
  - **`sessionMinimums` (required)**: `integer`

<a id="scalar-example-81"></a>

**Generated example:**

```json
{
  "object": "usage",
  "mode": "test",
  "from": "",
  "to": "",
  "days": [
    {
      "date": "",
      "liveSessions": 1,
      "liveSeconds": 1,
      "recordings": 1,
      "recordingSeconds": 1,
      "orgasms": 1,
      "ruins": 1,
      "edges": 1,
      "sessionMinimums": 1,
      "credits": 1
    }
  ],
  "totals": {
    "liveSessions": 1,
    "liveSeconds": 1,
    "recordings": 1,
    "recordingSeconds": 1,
    "orgasms": 1,
    "ruins": 1,
    "edges": 1,
    "sessionMinimums": 1,
    "credits": 1
  }
}
```

<a id="scalar-schema-creditpackage"></a>

### CreditPackage

**Type:** `object`

Credits your company received: the free 20, or a package bought under a statement of work, posted once its invoice was paid.

- **`credits` (required)**: `number`

  Credits it posted.
- **`expiresAt` (required)**: `string | null`, format: `date-time`

  When what it still holds expires, 12 months after it posted; `null` for the free credits, which do not expire.
- **`id` (required)**: `string`, pattern: `^(free|pkg_[0-9a-z]{20})$`
- **`object` (required)**: `string`, const: `"credit_package"`
- **`package` (required)**: `string`, possible values: `"free", "pilot", "launch", "growth", "scale", "enterprise"`

  Which package it is.
- **`postedAt` (required)**: `string`, format: `date-time`
- **`pricePerCredit` (required)**: `number`, minimum: `0`

  The price of each of its credits in US dollars; 0 for the free credits.
- **`remaining` (required)**: `number`

  Credits it still holds.

<a id="scalar-example-82"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "credit_package",
  "package": "free",
  "credits": 1,
  "remaining": 1,
  "pricePerCredit": 0,
  "postedAt": "",
  "expiresAt": null
}
```

<a id="scalar-schema-creditbalance"></a>

### CreditBalance

**Type:** `object`

Your company's credits, shared by its members and keys. Free credits are used first, then the package that expires soonest.

- **`balance` (required)**: `number`

  Credits available, in halves. Below zero when sessions that were running at zero used more; the next package that posts covers it.
- **`domain` (required)**: `string`

  The company domain the credits belong to.
- **`enforced` (required)**: `boolean`

  Whether a new live session is refused at zero (`credits_exhausted`). `false` while orgasm.dev is only counting.
- **`expiringSoon` (required)**: `object | null`

  Credits that expire within 30 days, and the first such expiry, or `null`.
  - **`at` (required)**: `string`, format: `date-time`
  - **`credits` (required)**: `number`
- **`free` (required)**: `object`
  - **`granted` (required)**: `number`
  - **`remaining` (required)**: `number`
- **`object` (required)**: `string`, const: `"credit_balance"`
- **`packages` (required)**: array of [CreditPackage](#scalar-schema-creditpackage)

  Every package with credits left, in the order they are used, then the used and expired ones.

<a id="scalar-example-83"></a>

**Generated example:**

```json
{
  "object": "credit_balance",
  "domain": "",
  "balance": 1,
  "free": {
    "granted": 1,
    "remaining": 1
  },
  "packages": [
    {
      "id": "",
      "object": "credit_package",
      "package": "free",
      "credits": 1,
      "remaining": 1,
      "pricePerCredit": 0,
      "postedAt": "",
      "expiresAt": null
    }
  ],
  "expiringSoon": {
    "credits": 1,
    "at": ""
  },
  "enforced": true
}
```

<a id="scalar-schema-chargeunit"></a>

### ChargeUnit

**Type:** `string`, possible values: `"orgasm", "ruin", "edge", "session_minimum"`

What a charge is for: an orgasm, a ruin, an edge, or the session minimum.

<a id="scalar-schema-charge"></a>

### Charge

**Type:** `object`

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.

- **`amountUsd` (required)**: `number`, minimum: `0`

  What it cost in US dollars: its paid credits at their packages' prices. 0 when a review returned it.
- **`apiKeyId` (required)**: `string | null`

  The key the session was created with.
- **`at` (required)**: `string`, format: `date-time`

  When it was charged.
- **`clientReferenceId` (required)**: `string | null`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  The session's `clientReferenceId`, erased with its `userReference`.
- **`credits` (required)**: `number`, minimum: `0`, multipleOf: `0.5`

  Credits it drew, in halves; 0 in test mode, which is free.
- **`freeCredits` (required)**: `number`, minimum: `0`

  Of them, free credits.
- **`id` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}\.(orgasm|ruin|edge|session_minimum)\.[0-9]+$`

  The session, the unit and its index. A charge is made once, so this never repeats.
- **`index` (required)**: `integer`, minimum: `1`

  The orgasm's `orgasmIndex` or the edge's `edgeIndex`; 1 for the session minimum.
- **`metadata` (required)**: [Metadata](#scalar-schema-metadata)

  The session's metadata, `{}` once erased.
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`object` (required)**: `string`, const: `"charge"`
- **`ownGpu` (required)**: `boolean`

  The session ran on your own GPUs.
- **`packages` (required)**: `array`

  The packages its credits came from, and at what price.

  **Items:**
  - **`credits` (required)**: `number`
  - **`id` (required)**: `string`, pattern: `^(free|pkg_[0-9a-z]{20})$`
  - **`pricePerCredit` (required)**: `number`, minimum: `0`
- **`paidCredits` (required)**: `number`, minimum: `0`

  Of them, credits from a package, including credits used past zero that a later package covered.
- **`pendingCredits` (required)**: `number`, minimum: `0`

  Of them, credits used past zero that no package has covered yet.
- **`returned` (required)**: `boolean`

  A review found the call wrong and returned its credits.
- **`sessionId` (required)**: `string`, pattern: `^ls_[0-9a-z]{20}$`
- **`unit` (required)**: `string`, possible values: `"orgasm", "ruin", "edge", "session_minimum"`

  What a charge is for: an orgasm, a ruin, an edge, or the session minimum.
- **`userReference` (required)**: `string | null`, minLength: `1`, maxLength: `128`, pattern: `^(?=.*[A-Za-z])[A-Za-z0-9._:-]{1,128}$`

  The session's `userReference`; `null` when it had none, once the session is purged, and 13 months after it ended.

<a id="scalar-example-84"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "charge",
  "mode": "test",
  "sessionId": "",
  "unit": "orgasm",
  "index": 1,
  "at": "",
  "credits": 0,
  "freeCredits": 0,
  "paidCredits": 0,
  "pendingCredits": 0,
  "amountUsd": 0,
  "packages": [
    {
      "id": "",
      "credits": 1,
      "pricePerCredit": 0
    }
  ],
  "returned": true,
  "ownGpu": true,
  "apiKeyId": null,
  "userReference": "",
  "clientReferenceId": "",
  "metadata": {
    "additionalProperty": ""
  }
}
```

<a id="scalar-schema-chargetotals"></a>

### ChargeTotals

**Type:** `object`

Every charge the filters match, across all pages.

- **`amountUsd` (required)**: `number`, minimum: `0`
- **`charges` (required)**: `integer`, minimum: `0`
- **`credits` (required)**: `number`, minimum: `0`
- **`freeCredits` (required)**: `number`, minimum: `0`
- **`paidCredits` (required)**: `number`, minimum: `0`
- **`pendingCredits` (required)**: `number`, minimum: `0`

<a id="scalar-example-85"></a>

**Generated example:**

```json
{
  "charges": 0,
  "credits": 0,
  "freeCredits": 0,
  "paidCredits": 0,
  "pendingCredits": 0,
  "amountUsd": 0
}
```

<a id="scalar-schema-chargelist"></a>

### ChargeList

**Type:** `object`

A page of charges, newest first, and the totals of every charge that matches.

- **`data` (required)**: array of [Charge](#scalar-schema-charge)
- **`hasMore` (required)**: `boolean`
- **`nextCursor` (required)**: `string | null`
- **`object` (required)**: `string`, const: `"list"`
- **`totals` (required)**: [ChargeTotals](#scalar-schema-chargetotals)

  Every charge the filters match, across all pages.

<a id="scalar-example-86"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "charge",
      "mode": "test",
      "sessionId": "",
      "unit": "orgasm",
      "index": 1,
      "at": "",
      "credits": 0,
      "freeCredits": 0,
      "paidCredits": 0,
      "pendingCredits": 0,
      "amountUsd": 0,
      "packages": [
        {
          "id": "",
          "credits": 1,
          "pricePerCredit": 0
        }
      ],
      "returned": true,
      "ownGpu": true,
      "apiKeyId": null,
      "userReference": "",
      "clientReferenceId": "",
      "metadata": {
        "additionalProperty": ""
      }
    }
  ],
  "totals": {
    "charges": 0,
    "credits": 0,
    "freeCredits": 0,
    "paidCredits": 0,
    "pendingCredits": 0,
    "amountUsd": 0
  },
  "hasMore": true,
  "nextCursor": null
}
```

<a id="scalar-schema-model"></a>

### Model

**Type:** `object`

A model behind one or more signals.

- **`appliesTo` (required)**: `string`, possible values: `"woman", "man", "any"`
- **`availability` (required)**: `object`
  - **`live` (required)**: `boolean`

    Available with live keys.
  - **`test` (required)**: `boolean`

    Simulated in the sandbox.
- **`benefitsFrom` (required)**: `array`

  Optional inputs that add to the model's calls.

  **Items:**

  `string`, possible values: `"body", "stimulation"`
- **`description` (required)**: `string`
- **`id` (required)**: `string`, possible values: `"imminence", "onset-end", "peak", "face-end", "subject"`
- **`object` (required)**: `string`, const: `"model"`
- **`produces` (required)**: `array`

  **Items:**

  `string`, possible values: `"imminence.updated", "signals.updated", "stimulation.updated", "orgasm.onset", "orgasm.peak", "orgasm.end", "edge.completed", "subject.identified", "session.status", "input.warning", "recording.completed", "recording.failed"`

  The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
- **`requires` (required)**: `array`

  Inputs without which the model does not run.

  **Items:**

  `string`, possible values: `"face", "audio"`
- **`version` (required)**: `string`

<a id="scalar-example-87"></a>

**Generated example:**

```json
{
  "id": "imminence",
  "object": "model",
  "version": "",
  "description": "",
  "produces": [
    "imminence.updated"
  ],
  "requires": [
    "face"
  ],
  "benefitsFrom": [
    "body"
  ],
  "appliesTo": "woman",
  "availability": {
    "test": true,
    "live": true
  }
}
```

<a id="scalar-schema-modellist"></a>

### ModelList

**Type:** `object`

Every model.

- **`data` (required)**: array of [Model](#scalar-schema-model)
- **`object` (required)**: `string`, const: `"list"`

<a id="scalar-example-88"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "imminence",
      "object": "model",
      "version": "",
      "description": "",
      "produces": [
        "imminence.updated"
      ],
      "requires": [
        "face"
      ],
      "benefitsFrom": [
        "body"
      ],
      "appliesTo": "woman",
      "availability": {
        "test": true,
        "live": true
      }
    }
  ]
}
```

<a id="scalar-schema-apikeytype"></a>

### ApiKeyType

**Type:** `string`, possible values: `"secret", "billing"`

`secret`: everything in this API. `billing`: reads `getCredits`, `getUsage` and `listCharges` and nothing else, in live mode only.

<a id="scalar-schema-apikeycreaterequest"></a>

### ApiKeyCreateRequest

**Type:** `object`

A name, a mode and, optionally, a type for a new key.

- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`name` (required)**: `string`, minLength: `1`, maxLength: `100`
- **`type`**: `string`, possible values: `"secret", "billing"`

  `secret` by default. A `billing` key must be `live`.

<a id="scalar-example-89"></a>

**Generated example:**

```json
{
  "name": "",
  "mode": "test",
  "type": "secret"
}
```

<a id="scalar-schema-apikeyrollrequest"></a>

### ApiKeyRollRequest

**Type:** `object`

When the key being replaced stops working.

- **`expiresInS`**: `integer`, possible values: `0, 3600, 86400, 604800`, default: `0`

  Seconds until the old key stops working: 0 (at once, the default), an hour, a day or a week.

<a id="scalar-example-90"></a>

**Generated example:**

```json
{
  "expiresInS": 0
}
```

<a id="scalar-schema-apikey"></a>

### ApiKey

**Type:** `object`

A key of your company's.

- **`createdAt` (required)**: `string`, format: `date-time`
- **`createdBy` (required)**: `string | null`

  The email of the member who made it in the console, or `null` for a key made through this API.
- **`expiresAt` (required)**: `string | null`, format: `date-time`

  When a rolled key stops working; `null` for a key that does not expire.
- **`id` (required)**: `string`, pattern: `^key_[0-9a-z]{20}$`
- **`lastUsedAt` (required)**: `string | null`, format: `date-time`
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`name` (required)**: `string`
- **`object` (required)**: `string`, const: `"api_key"`
- **`redacted` (required)**: `string`

  The key's prefix and last four characters.
- **`secret` (required)**: `string | null`

  The whole key, only in the response that created or rolled it.
- **`type` (required)**: `string`, possible values: `"secret", "billing"`

  `secret`: everything in this API. `billing`: reads `getCredits`, `getUsage` and `listCharges` and nothing else, in live mode only.

<a id="scalar-example-91"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "api_key",
  "name": "",
  "mode": "test",
  "type": "secret",
  "redacted": "",
  "secret": null,
  "createdBy": null,
  "createdAt": "",
  "lastUsedAt": null,
  "expiresAt": null
}
```

<a id="scalar-schema-apikeylist"></a>

### ApiKeyList

**Type:** `object`

A page of API keys.

- **`data` (required)**: array of [ApiKey](#scalar-schema-apikey)
- **`hasMore` (required)**: `boolean`
- **`nextCursor` (required)**: `string | null`
- **`object` (required)**: `string`, const: `"list"`

<a id="scalar-example-92"></a>

**Generated example:**

```json
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "api_key",
      "name": "",
      "mode": "test",
      "type": "secret",
      "redacted": "",
      "secret": null,
      "createdBy": null,
      "createdAt": "",
      "lastUsedAt": null,
      "expiresAt": null
    }
  ],
  "hasMore": true,
  "nextCursor": null
}
```

<a id="scalar-schema-attestationpolicy"></a>

### AttestationPolicy

**Type:** `object`

What an enclave's attestation must show before a device sends it media. In test mode no enclave runs, and the policy says so.

- **`debugAllowed` (required)**: `boolean`

  Whether a debuggable enclave is accepted. Never in live mode.
- **`enforced` (required)**: `boolean`

  Whether devices must verify an attestation in this mode.
- **`evidence` (required)**: `object`

  How the enclave signs its answers to the device.
  - **`algorithm` (required)**: `string`, const: `"Ed25519"`
- **`hardware` (required)**: `array of string`

  The confidential-computing hardware the enclave must run on.
- **`image` (required)**: `object`
  - **`digests` (required)**: `array`

    Accepted image digests. Empty: any digest that carries an accepted signature and an accepted release.

    **Items:**

    `string`, pattern: `^sha256:[0-9a-f]{64}$`
  - **`minRelease` (required)**: `string | null`

    The oldest enclave release accepted.
  - **`releasesUrl` (required)**: `string | null`, format: `uri`

    Every release, the digest it built and the commands that check it.
  - **`repository` (required)**: `string | null`

    The public registry that holds each released digest with its SLSA provenance and keyless signature.
  - **`signers` (required)**: `array`

    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`.

    **Items:**

    `string`, pattern: `^[0-9a-f]{64}$`
  - **`source` (required)**: `string | null`, format: `uri`

    The public source the enclave image is built from.
- **`issuer` (required)**: `string | null`, format: `uri`

  The issuer the attestation token must be signed by.
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`object` (required)**: `string`, const: `"attestation_policy"`
- **`seal` (required)**: `object`
  - **`schemes` (required)**: `array`

    **Items:**

    `string`, possible values: `"v1"`
- **`updatedAt` (required)**: `string`, format: `date-time`
- **`verify` (required)**: [VerifierValues](#scalar-schema-verifiervalues) | `null`

  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.
- **`version` (required)**: `string`
- **`note`**: `string`

<a id="scalar-example-93"></a>

**Generated example:**

```json
{
  "object": "attestation_policy",
  "mode": "test",
  "version": "",
  "enforced": true,
  "issuer": null,
  "hardware": [
    ""
  ],
  "image": {
    "source": null,
    "minRelease": null,
    "digests": [
      ""
    ],
    "signers": [
      ""
    ],
    "repository": null,
    "releasesUrl": null
  },
  "seal": {
    "schemes": [
      "v1"
    ]
  },
  "evidence": {
    "algorithm": "Ed25519"
  },
  "debugAllowed": true,
  "verify": {
    "sourceUri": "",
    "imageRepo": "",
    "signerKeyIds": [
      ""
    ],
    "minRelease": null,
    "readingsUrl": "",
    "invokers": [
      ""
    ],
    "captureBucket": "",
    "requestSeal": "",
    "projectIds": [
      ""
    ],
    "imageRefPrefixes": [
      ""
    ]
  },
  "note": "",
  "updatedAt": ""
}
```

<a id="scalar-schema-verifiervalues"></a>

### VerifierValues

**Type:** `object`

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.

- **`captureBucket` (required)**: `string`

  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.
- **`imageRefPrefixes` (required)**: `array of string`

  Where the enclave's image may have been pulled from (`-image-ref-prefix`).
- **`imageRepo` (required)**: `string`

  The public registry that holds the digest with its provenance (`-image-repo`).
- **`invokers` (required)**: `array of string`

  Exactly the identities the enclave's control routes may take a token from, its attested `TRAINER_INVOKER_SERVICE_ACCOUNT` (`-trainer-invoker`).
- **`minRelease` (required)**: `string | null`

  The oldest release accepted (`-min-release`).
- **`projectIds` (required)**: `array of string`

  The Google Cloud projects the enclave may run in (`-project-id`).
- **`readingsUrl` (required)**: `string`, format: `uri`

  Where the enclave must post its readings, its attested `TRAINER_URL` (`-trainer-url`).
- **`requestSeal` (required)**: `string`

  The sealing scheme requests must use, its attested `TEE_REQUEST_SEAL` (`-request-seal`).
- **`signerKeyIds` (required)**: `array`

  Accepted image signing keys (`-signer-key-ids`).

  **Items:**

  `string`, pattern: `^[0-9a-f]{64}$`
- **`sourceUri` (required)**: `string`

  The repository the image's SLSA provenance must name (`-source-uri`).

<a id="scalar-example-94"></a>

**Generated example:**

```json
{
  "sourceUri": "",
  "imageRepo": "",
  "signerKeyIds": [
    ""
  ],
  "minRelease": null,
  "readingsUrl": "",
  "invokers": [
    ""
  ],
  "captureBucket": "",
  "requestSeal": "",
  "projectIds": [
    ""
  ],
  "imageRefPrefixes": [
    ""
  ]
}
```

<a id="scalar-schema-enclavereceipt"></a>

### EnclaveReceipt

**Type:** `object`

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.

- **`attestationToken` (required)**: `string`

  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>.
- **`attestedAt` (required)**: `string`, format: `date-time`

  When Google's attestation service signed the token.
- **`commit` (required)**: `string | null`

  The source commit the image is stamped with (`TEE_IMAGE_COMMIT`).
- **`confidentialSpace` (required)**: `array of string`

  The Confidential Space image's support attributes, `STABLE` among them.
- **`debugging` (required)**: `string`

  The machine image's debug status, `disabled-since-boot` in live mode.
- **`hardware` (required)**: `object`
  - **`cpu` (required)**: `string`

    The attested platform, `GCP_INTEL_TDX`.
  - **`gpuConfidentialComputing` (required)**: `boolean`
  - **`gpus` (required)**: `array of string`

    The attested GPUs, `GCP_NVIDIA_H100`.
  - **`secureBoot` (required)**: `boolean`
- **`imageDigest` (required)**: `string`, pattern: `^sha256:[0-9a-f]{64}$`

  The digest of the image the enclave runs.
- **`instanceId` (required)**: `string`
- **`projectId` (required)**: `string | null`

  The Google Cloud project the enclave runs in.
- **`release` (required)**: `string | null`

  The release the image is stamped with (`TEE_IMAGE_VERSION`).
- **`releaseUrl` (required)**: `string | null`, format: `uri`

  The release's page, with its digest and the commands that check its SLSA provenance and signature.
- **`signers` (required)**: `array of string`

  The keys the launcher verified the image's signature with.
- **`tlsBound` (required)**: `boolean`

  The TLS connection orgasm.dev made to the enclave ended inside it: the token names that connection's key.
- **`verifiedAt` (required)**: `string`, format: `date-time`

  When orgasm.dev checked it.
- **`zone` (required)**: `string | null`

<a id="scalar-example-95"></a>

**Generated example:**

```json
{
  "imageDigest": "",
  "release": null,
  "commit": null,
  "releaseUrl": null,
  "signers": [
    ""
  ],
  "hardware": {
    "cpu": "",
    "gpus": [
      ""
    ],
    "gpuConfidentialComputing": true,
    "secureBoot": true
  },
  "debugging": "",
  "confidentialSpace": [
    ""
  ],
  "projectId": null,
  "zone": null,
  "instanceId": "",
  "tlsBound": true,
  "attestedAt": "",
  "verifiedAt": "",
  "attestationToken": ""
}
```

<a id="scalar-schema-deleted"></a>

### Deleted

**Type:** `object`

Confirms a deletion.

- **`deleted` (required)**: `boolean`, const: `true`
- **`id` (required)**: `string`
- **`object` (required)**: `string`

<a id="scalar-example-96"></a>

**Generated example:**

```json
{
  "id": "",
  "object": "",
  "deleted": true
}
```


---

# Events reference

The events orgasm.dev sends about a live session or a recording: imminence
once a second, orgasm onset, peak and end as they are called, each edge
orgasm.dev counts, the subject read, status changes and input warnings;
and, by webhook, `credits.low` when your company's balance runs low.

The same event objects travel on three channels:

- **Stream**: server-sent events from `GET /v1/live-sessions/{sessionId}/stream`.
- **Socket**: a WebSocket at `/v1/live-sessions/{sessionId}/ws`, which also
  accepts stimulation reports from the client.
- **Webhooks**: signed HTTP POSTs to endpoints you register, for every
  event type except `imminence.updated`, `signals.updated` and
  `stimulation.updated`, which come often and are only streamed, and for
  `credits.low`, which belongs to your company rather than a session.

A stream or socket that asks with `frames=face` also receives
`face.frame`, the face about five times a second for a display that draws
it. A frame is not an event: it has no `id` or `sequence` and is never
stored, replayed or sent to webhooks.

They are also listed by `GET /v1/live-sessions/{sessionId}/events` and
`GET /v1/recordings/{recordingId}/events` (see the OpenAPI document,
<https://orgasm.dev/openapi.json>).

**Delivery.** At least once. A redelivered event keeps its `id`;
deduplicate on it. `sequence` numbers the events of a session or recording
from 1 without gaps, so sort by it and use it to notice a gap; webhook
retries in particular can arrive out of order.

**Replay.** The stream and the socket replay what you missed when you
reconnect with the last `id` you saw (`Last-Event-ID`, `after`, or a
`resume` message). Every `imminence.updated` also repeats the session's
last eight orgasm calls in `data.recentCalls`, so a call whose own message
was lost is seen within a second.

**Timing.** Calls are retrospective: `data.eventAtS` is the moment named,
`data.calledAtS` when the detector was sure enough to call it, typically a
few seconds later. Times ending in `S` are seconds on the media's clock;
`wallTime` is UTC.

## The event envelope

Every event, on every channel, has these fields:

- `id` (string, required): Unique and stable. A redelivered event carries the same `id`, so deduplicate on it.
- `object` (`"event"`, required)
- `type` (`imminence.updated` | `signals.updated` | `stimulation.updated` | `orgasm.onset` | `orgasm.peak` | `orgasm.end` | `edge.completed` | `subject.identified` | `session.status` | `input.warning` | `recording.completed` | `recording.failed`, required): The kind of event. New types can be added at any time; ignore a type you do not recognise rather than failing.
- `mode` (`test` | `live`, required): `test` for sandbox events, `live` for live analysis.
- `sessionId` (string): The live session the event belongs to. Absent on recording events.
- `recordingId` (string): The recording the event belongs to. Absent on live-session events.
- `sequence` (integer, required): 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.
- `streamTimeS` (number, required): 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`).
- `wallTime` (string, required): 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.
- `confidence` (`high` | `medium` | `low` | `null`, required): 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.
- `data` (object, required): The event's own fields; see each event type.

## Channels

### Live session stream

`https://orgasm.dev/v1/live-sessions/{sessionId}/stream`

`GET` with `Accept: text/event-stream`. Each message is sent as one
server-sent event whose `id:` is the event `id`, `event:` its `type`,
and `data:` the event as JSON. A comment line is sent every 15 seconds.
The stream closes after the session's final `session.status`.

Authenticate with a secret key or the session's client token in
`Authorization`, or, in a browser, with `?token=` and the client token.
Reconnect with `Last-Event-ID` or `?after=` to replay what you missed.
Filter with `?types=`. With `?frames=face` the stream also sends
`face.frame` about five times a second, as server-sent events with
`event: face.frame` and no `id:` line.

### Live session socket

`wss://orgasm.dev/v1/live-sessions/{sessionId}/ws`

Connect with `?token=` and the session's client token, or an
`Authorization` header with the secret key or the client token where
your client can set one. View tokens read the stream instead, since
they never go in a URL. Add `?after=` to replay from an event,
`?types=` to filter, and `?frames=face` for `face.frame`. orgasm.dev
sends each event as one JSON text frame, in `sequence` order. A socket
counts toward the session's 12 streams; another is refused with a
`socket.error` (`rate_limited`) and closed.

The client may send `stimulation` reports and a `resume` request;
anything else is answered with a `socket.error` frame and the socket
stays open. The server closes the socket with code 1000 after the
final `session.status`, and with 1008 when its token stops working.

### Webhook delivery

Address: the URL of your webhook endpoint.

orgasm.dev POSTs one event per request to each enabled endpoint
subscribed to its type, at the URL you registered (so the address is
yours). Requests are signed per the Standard Webhooks specification.

Verify `webhook-signature` before trusting the body: it is `v1,`
followed by the base64 HMAC-SHA256, keyed with the base64 part of your
endpoint's `whsec_` secret, of `{webhook-id}.{webhook-timestamp}.{body}`.
Refuse a `webhook-timestamp` more than five minutes from your clock.

Answer with any 2xx status within 10 seconds. Anything else, or no
answer, is retried with exponential backoff for up to 24 hours. Process
the event after you answer, and deduplicate on `webhook-id`, which is
the event `id`.

## Messages

### `imminence.updated`: Imminence updated

The probability that the next orgasm begins within 30 and 60 seconds, about once a second.

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.

Fields of `data`:

- `p30` (number | null, required): 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.
- `p60` (number | null, required): The same probability over 60 seconds. Never lower than `p30`.
- `logit30` (number | null, required): `p30` as a logit, ln(p / (1 - p)). Add your own prior on this scale to combine it with what your product knows.
- `logit60` (number | null, required): `p60` as a logit.
- `featuresPresent` (number, required): 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.
- `faceVisible` (boolean, required): Whether a face was tracked in the last second.
- `baselineReady` (boolean, required): 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.
- `stimulationAware` (boolean, required): 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.
- `recentCalls` (array of object, required): 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.

Example (A second after a woman’s onset call, which it repeats in recentCalls.):

```json
{
  "id": "evt_1yohem6b9mw24jlm4lp7",
  "object": "event",
  "type": "imminence.updated",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 970,
  "streamTimeS": 543,
  "confidence": "high",
  "data": {
    "p30": 0.883,
    "p60": 0.986,
    "logit30": 2.02,
    "logit60": 4.28,
    "featuresPresent": 0.93,
    "faceVisible": true,
    "baselineReady": true,
    "stimulationAware": false,
    "recentCalls": [
      {
        "id": "evt_2099smltv0t2c2wzzyzq",
        "type": "orgasm.onset",
        "eventAtS": 538
      }
    ]
  },
  "wallTime": "2026-10-16T14:00:55.300Z"
}
```

### `signals.updated`: Signals updated

Vocalizations, contractions, movement, the face's regions and its channels, once a second with imminence; for a heads-up display.

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.

Fields of `data`:

- `vocalizationsPerMin` (number | null, required): Vocalizations a minute, from the microphone; null without it.
- `loudnessAboveBaselineDb` (number | null, required): How much louder the voice is than at the baseline, in decibels; null without the microphone or before its baseline.
- `contractionsPerMin` (number | null, required): Pelvic floor contractions a minute, from the body view; null without it.
- `movement` (`settled` | `shifting` | `unsettled` | `null`, required): How still the body is, from the body view; null without it.
- `faceRegions` (any, required): Null while the face is out of view or before the baseline is in.
- `face` (any, required): 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`.

Example (Five minutes in: the voice, the face’s regions, and its channels for a display that draws the face.):

```json
{
  "id": "evt_16jli44dbp220eivj30s",
  "object": "event",
  "type": "signals.updated",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 484,
  "streamTimeS": 300,
  "confidence": "high",
  "data": {
    "vocalizationsPerMin": 3,
    "loudnessAboveBaselineDb": 2,
    "contractionsPerMin": null,
    "movement": null,
    "faceRegions": {
      "brows": 0.13,
      "eyes": 0.11,
      "cheeks": 0.13,
      "nose": 0.09,
      "lips": 0.13,
      "corners": 0.11,
      "jaw": 0.19
    },
    "face": {
      "expression": {
        "eyeBlinkL": 0.03,
        "eyeBlinkR": 0.08,
        "eyeWideL": 0.05,
        "eyeWideR": 0.11,
        "browDownL": 0.03,
        "browDownR": 0.11,
        "browInnerUp": 0.11,
        "browOuterUpL": 0.13,
        "browOuterUpR": 0.03,
        "jawOpen": 0.19,
        "lipsPart": 0.13,
        "mouthSmileL": 0.11,
        "mouthSmileR": 0.03,
        "mouthStretch": 0.12,
        "mouthPucker": 0,
        "noseSneer": 0.09,
        "noseFlare": 0.04,
        "cheekSquintL": 0.13,
        "cheekSquintR": 0.08,
        "chinRaise": 0.08,
        "lidTighten": 0.07,
        "browTogether": 0.08,
        "noseWrinkle": 0.04,
        "lidRaise": 0.06
      },
      "head": {
        "yawDeg": 4.8,
        "pitchDeg": -0.7,
        "rollDeg": 3.5
      }
    }
  },
  "wallTime": "2026-10-16T14:00:31.000Z"
}
```

### `stimulation.updated`: Stimulation updated

The device's state, level, channels and mode, as your product reported them; at most four a second.

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.

Fields of `data`:

- `state` (`on` | `off`, required): Whether stimulation is on or off.
- `intensity` (number | null, required): The intensity from 0 to 1 on your product's own scale.
- `level` (number | null, required): The device's level on its own scale, such as 0 to 100.
- `levelMax` (number | null, required): The highest level the device will go to now, on the same scale.
- `channels` (array | null, required): Each output's level, for a device with more than one.
- `mode` (string | null, required): The device's mode or pattern, as your product names it.
- `modeLabel` (string | null, required): The mode's name to show; without it a display shows `mode` in words.
- `device` (any, required)
- `drive` (`auto` | `manual` | `hold` | `paused` | `null`, required): 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`.
- `changedAtS` (number, required): When the change happened, in stream seconds. The event's own `streamTimeS` is when orgasm.dev received the report, which can be later.

Example (A two-channel unit in its waves mode, set by your product.):

```json
{
  "id": "evt_27agnfxkudp0cl1yesg8",
  "object": "event",
  "type": "stimulation.updated",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 365,
  "streamTimeS": 240,
  "confidence": null,
  "data": {
    "state": "on",
    "intensity": null,
    "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",
    "changedAtS": 240
  },
  "wallTime": "2026-10-16T14:00:25.000Z"
}
```

### `face.frame`: Face frame

The face's channels and the head as the camera sees it, about five times a second, for a display that draws them; with `frames=face` only, never stored.

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.

Fields:

- `type` (`"face.frame"`, required)
- `sessionId` (string, required)
- `streamTimeS` (number, required): When the frame was measured, in stream seconds.
- `face` (any, required): Null while the face is out of view or before the baseline is in.
- `cameraHead` (any): 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.

Example (The face between two readings, five minutes in.):

```json
{
  "type": "face.frame",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "streamTimeS": 312.4,
  "face": {
    "expression": {
      "eyeBlinkL": 0.04,
      "eyeBlinkR": 0.06,
      "eyeWideL": 0.09,
      "eyeWideR": 0.09,
      "browDownL": 0.03,
      "browDownR": 0.07,
      "browInnerUp": 0.19,
      "browOuterUpL": 0.05,
      "browOuterUpR": 0.06,
      "jawOpen": 0.18,
      "lipsPart": 0.17,
      "mouthSmileL": 0.05,
      "mouthSmileR": 0.07,
      "mouthStretch": 0.09,
      "mouthPucker": 0.06,
      "noseSneer": 0.01,
      "noseFlare": 0.06,
      "cheekSquintL": 0.15,
      "cheekSquintR": 0.09,
      "chinRaise": 0.02,
      "lidTighten": 0.12,
      "browTogether": 0.07,
      "noseWrinkle": 0.04,
      "lidRaise": 0.04
    },
    "head": {
      "yawDeg": 5.4,
      "pitchDeg": -1.6,
      "rollDeg": -2.8
    }
  },
  "cameraHead": {
    "yawDeg": 5.4,
    "pitchDeg": -1.6,
    "rollDeg": -2.8
  }
}
```

### `orgasm.onset`: Orgasm onset

An orgasm began (women; needs the microphone).

An orgasm began. Applies to women (the `onset_end` detector). Requires the microphone. The call arrives a few seconds after the moment it names.

Fields of `data`:

- `orgasmIndex` (integer, required): Which orgasm of the session this is, from 1. The onset and the end of the same orgasm share it.
- `eventAtS` (number, required): The moment the orgasm began, in stream seconds.
- `calledAtS` (number, required): The moment the detector made the call, in stream seconds.
- `lagS` (number, required): `calledAtS - eventAtS`: how late the call is.
- `detector` (`"onset_end"`, required)
- `score` (number, required): The detector's score for the call, on the scale of `threshold`.
- `threshold` (number, required): The level the detector calls at. A score at or above it made the call.

Example (The onset of a woman’s orgasm, called 4.6 seconds after it began.):

```json
{
  "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"
}
```

### `orgasm.peak`: Orgasm peak

The peak of an orgasm (men; needs the microphone).

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.

Fields of `data`:

- `orgasmIndex` (integer, required): Which orgasm of the session this is, from 1. The peak and the face-based end of the same orgasm share it.
- `eventAtS` (number, required): The moment of the peak, in stream seconds.
- `calledAtS` (number, required): The moment the detector made the call, in stream seconds.
- `lagS` (number, required): `calledAtS - eventAtS`.
- `detector` (`"peak"`, required)
- `score` (number, required)
- `threshold` (number, required)

Example (A man’s peak, called 3.2 seconds after it.):

```json
{
  "id": "evt_26m8iv7m9ik1q6bbpxah",
  "object": "event",
  "type": "orgasm.peak",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 1293,
  "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:01:11.420Z"
}
```

### `orgasm.end`: Orgasm end

An orgasm ended.

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`).

Fields of `data`:

- `orgasmIndex` (integer, required): Which orgasm of the session ended.
- `eventAtS` (number, required): The moment the orgasm ended, in stream seconds.
- `startedAtS` (number, required): When the same orgasm began: its onset (`onset_end`) or its peak (`face_end`).
- `durationS` (number, required): `eventAtS - startedAtS`.
- `calledAtS` (number, required): The moment the detector made the call, in stream seconds.
- `lagS` (number, required): `calledAtS - eventAtS`.
- `detector` (`onset_end` | `face_end`, required)
- `score` (number | null, required): The detector's score, or `null` for `face_end`, which has none.
- `threshold` (number | null, required): The detector's calling level, or `null` for `face_end`.
- `ruined` (boolean, required): 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.

Example (The end of a woman’s orgasm, from the onset-and-end detector.):

```json
{
  "id": "evt_2b9vobycwv70h1fs0mre",
  "object": "event",
  "type": "orgasm.end",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 1046,
  "streamTimeS": 580.2,
  "confidence": "high",
  "data": {
    "orgasmIndex": 1,
    "eventAtS": 575,
    "startedAtS": 538,
    "durationS": 37,
    "calledAtS": 580.2,
    "lagS": 5.2,
    "detector": "onset_end",
    "score": 0.68,
    "threshold": 0.5,
    "ruined": false
  },
  "wallTime": "2026-10-16T14:00:59.020Z"
}
```

### `edge.completed`: Edge completed

Imminence reached 0.6 and fell back below 0.3 with no orgasm called; half a credit in live mode.

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.

Fields of `data`:

- `edgeIndex` (integer, required): Which edge of the session this is, from 1.
- `startedAtS` (number, required): When `p30` reached 0.6, the edge preset's back-off level, in stream seconds.
- `eventAtS` (number, required): When `p30` fell back below 0.3, the preset's resume level, which made the approach an edge, in stream seconds.
- `durationS` (number, required): `eventAtS - startedAtS`.
- `peakP30` (number, required): The highest `p30` of the approach.

Example (The first of three edges: imminence reached 0.6 and fell back below 0.3.):

```json
{
  "id": "evt_2gi9on772qb0beswjxgp",
  "object": "event",
  "type": "edge.completed",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 706,
  "streamTimeS": 411,
  "confidence": "high",
  "data": {
    "edgeIndex": 1,
    "startedAtS": 362,
    "eventAtS": 411,
    "durationS": 49,
    "peakP30": 0.687
  },
  "wallTime": "2026-10-16T14:00:42.100Z"
}
```

### `subject.identified`: Subject identified

Whether the face reads as a woman's or a man's, and which detectors apply.

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.

Fields of `data`:

- `sex` (`woman` | `man` | `undetermined`, required): 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.
- `pWoman` (number | null, required): The read's probability that the face is a woman's, or `null` when the face could not be read.
- `secondsObserved` (integer, required): Seconds of visible face the read was made from (at most 30).
- `decidedAtS` (number, required): When the read was made, in stream seconds.
- `hint` (`woman` | `man` | `null`, required): The `subjectHint` you gave when you created the session, or `null`.
- `detectors` (array of `onset_end` | `peak` | `face_end`, required): 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`.

Example (The face reads as a woman’s.):

```json
{
  "id": "evt_0z6tc53e7py0ep61nm8s",
  "object": "event",
  "type": "subject.identified",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 4,
  "streamTimeS": 32,
  "confidence": "high",
  "data": {
    "sex": "woman",
    "pWoman": 0.94,
    "secondsObserved": 30,
    "decidedAtS": 32,
    "hint": null,
    "detectors": [
      "onset_end"
    ]
  },
  "wallTime": "2026-10-16T14:00:04.200Z"
}
```

### `session.status`: Session status

The session's status or inputs changed.

The live session changed status, or its inputs changed.

Fields of `data`:

- `status` (`starting` | `ready` | `calibrating` | `analyzing` | `ended`, required): `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.
- `previousStatus` (`starting` | `ready` | `calibrating` | `analyzing` | `ended` | `null`, required)
- `degraded` (boolean, required): An input the session declared is missing, or the face is not visible. The open `input.warning` events say which.
- `inputs` (object, required): Which inputs are arriving right now.
  - `face` (object, required)
  - `audio` (object, required)
  - `body` (object, required)
- `endedReason` (`client_ended` | `media_ended` | `media_timeout` | `max_duration` | `interrupted` | `policy` | `error` | `null`, required): 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.

Example (The baseline is in and every signal runs.):

```json
{
  "id": "evt_0a8shq12uin1saa234wn",
  "object": "event",
  "type": "session.status",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 5,
  "streamTimeS": 62,
  "confidence": null,
  "data": {
    "status": "analyzing",
    "previousStatus": "calibrating",
    "degraded": false,
    "inputs": {
      "face": {
        "present": true,
        "baselineReady": true
      },
      "audio": {
        "declared": true,
        "present": true
      },
      "body": {
        "declared": false,
        "present": false
      }
    },
    "endedReason": null
  },
  "wallTime": "2026-10-16T14:00:07.200Z"
}
```

### `input.warning`: Input warning

An input problem started or stopped.

An input problem started (`raised`) or stopped (`cleared`). Show `message` to the person when it helps them fix it.

Fields of `data`:

- `code` (`face_not_visible` | `multiple_faces` | `audio_absent` | `baseline_pending` | `body_stream_absent` | `low_confidence`, required): `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.
- `state` (`raised` | `cleared`, required): `raised` when the condition starts, `cleared` when it ends.
- `message` (string, required): A sentence you can show the person, in English.
- `sinceS` (number, required): When the condition started, in stream seconds.

Example (The face left the frame.):

```json
{
  "id": "evt_1x82ikl67c70dowtacc7",
  "object": "event",
  "type": "input.warning",
  "mode": "test",
  "sessionId": "ls_8f3kq2m7x9w4c1n6t5ra",
  "sequence": 483,
  "streamTimeS": 300,
  "confidence": null,
  "data": {
    "code": "face_not_visible",
    "state": "raised",
    "message": "Your face is not visible. Move back into view of the front camera.",
    "sinceS": 300
  },
  "wallTime": "2026-10-16T14:00:31.000Z"
}
```

### `socket.error`: Socket error

A client message was refused.

Sent on the socket when a client message is refused.

Fields:

- `type` (`"socket.error"`, required)
- `code` (`invalid_message` | `unknown_action` | `session_ended` | `forbidden` | `rate_limited`, required)
- `detail` (string, required)

Example (The client sent an action the socket does not know.):

```json
{
  "type": "socket.error",
  "code": "unknown_action",
  "detail": "Unknown action \"pause\". Send \"stimulation\" or \"resume\"."
}
```

### `stimulation`: Stimulation report

The client reports that stimulation started, stopped or changed.

A stimulation report, as on `POST /v1/live-sessions/{sessionId}/stimulation`: every field but `state` is optional, one you omit keeps the value you last reported, and `null` clears it. Each reaches the session's readers as `stimulation.updated`.

Fields:

- `action` (`"stimulation"`, required)
- `state` (`on` | `off`, required)
- `intensity` (number | null)
- `level` (number | null)
- `levelMax` (number | null)
- `channels` (array | null)
- `mode` (string | null)
- `modeLabel` (string | null)
- `device` (any)
- `drive` (`auto` | `manual` | `hold` | `paused` | `null`)
- `streamTimeS` (number)

Example (Stimulation started at 40 % intensity.):

```json
{
  "action": "stimulation",
  "state": "on",
  "intensity": 0.4
}
```

### `resume`: Resume

The client asks for missed events again.

Ask for every event after `after` to be sent again, in order.

Fields:

- `action` (`"resume"`, required)
- `after` (string, required)

Example (Replay everything after the onset call.):

```json
{
  "action": "resume",
  "after": "evt_4q7m2k9x8w1c3n6b5v0z"
}
```

### Webhook headers

- `webhook-id` (string, required): The event `id`. The same on every retry; deduplicate on it.
- `webhook-timestamp` (string, required): When this attempt was sent, in Unix seconds.
- `webhook-signature` (string, required): `v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}`, keyed with your endpoint's secret. Several space-separated signatures may appear while a secret is being rotated; accept any that verifies.
- `content-type` (`"application/json"`, required)
- `user-agent` (string)