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

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

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

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

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

  **Additional properties:**

  `string`, maxLength: `500`
- **`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.
  - **`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.
- **`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:**

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

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

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

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

*Schema `Problem` is shown above.*

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

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

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

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

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