# Create a live session (https://orgasm.dev/docs/api/live-sessions/createLiveSession)

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

## Effective servers

- `https://orgasm.dev`

  `sk_test_` keys reach the sandbox. `sk_live_` keys are refused until live analysis is available.
- `http://localhost:3000`

  The docs site running locally (`npm run dev`), which serves the sandbox.
- `http://localhost:4010`

  The standalone sandbox (`npm run mock`), which also serves the WebSocket channel.

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

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

schema: `LiveSessionCreateRequest`

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

- **`consent` (required)**: `object`, 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.
  - **`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.
- **`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`**: `object`, 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`.
  - **`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.
- **`maxDurationS`**: `integer`, default: `3600`, minimum: `60`, maximum: `14400`

  The session ends after this many seconds (`max_duration`).
- **`metadata`**: `object`, schema: `Metadata`, 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`
- **`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`**: `object`, schema: `SandboxOptions`

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

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

schema: `LiveSession`

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

- **`charges` (required)**: `object`, 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.
  - **`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`.
- **`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)**: `object | null`, schema: `EnclaveReceipt`

  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.
  - **`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`
- **`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)**: `object | null`, schema: `Ingest`

  `null` once the session has ended.
  - **`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)**: `object`, schema: `VideoRequirements`

    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`
- **`inputs` (required)**: `object`, schema: `InputsPresence`

  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.
- **`latestImminence` (required)**: `object | null`, schema: `LatestImminence`

  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`
- **`maxDurationS` (required)**: `integer`
- **`metadata` (required)**: `object`, schema: `Metadata`, 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`.

  *Schema `Metadata` is shown above.*
- **`mode` (required)**: `string`, possible values: `"test", "live"`
- **`object` (required)**: `string`, const: `"live_session"`
- **`results` (required)**: `object`, schema: `Results`

  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.
- **`resultsExpireAt` (required)**: `string | null`, format: `date-time`

  When the session's events are deleted, once it has ended.
- **`retentionDays` (required)**: `integer`
- **`sandbox` (required)**: `object | null`, schema: `SandboxOptions`

  The sandbox options the session plays, or `null` in live mode.

  *Schema `SandboxOptions` is shown above.*
- **`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)**: `object | null`, schema: `SubjectIdentifiedData`

  The subject read, once it is made (`subject.identified`).
  - **`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.
- **`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`

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

schema: `Problem`

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`

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

*Schema `Problem` is shown above.*

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

*Schema `Problem` is shown above.*

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

*Schema `Problem` is shown above.*

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

*Schema `Problem` is shown above.*

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

*Schema `Problem` is shown above.*

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

*Schema `Problem` is shown above.*

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

*Schema `Problem` is shown above.*

**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"
}
```

## Schemas

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

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

- `SubjectIdentifiedData` — shown above.
- `InputsPresence` — shown above.
- `Problem` — shown above.

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

- `Consent` — shown above.
- `DeclaredInputs` — shown above.

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

- `SandboxOptions` — shown above.
- `Metadata` — shown above.

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

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

### LiveSessionStatus

**Type:** `string`, possible values: `"starting", "ready", "calibrating", "analyzing", "ended"`

Where a live session is in its life: `starting`, `ready`, `calibrating`, `analyzing`, `ended`.

- `LiveSessionCreateRequest` — shown above.
- `VideoRequirements` — shown above.
- `Ingest` — shown above.
- `Results` — shown above.
- `LatestImminence` — shown above.
- `LiveSession` — shown above.
- `LiveSessionCharges` — shown above.
- `EnclaveReceipt` — shown above.
