# Report stimulation (https://orgasm.dev/docs/api/live-sessions/reportStimulation)

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

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

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`

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.

- **`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 | null`, maxItems: `4`

  Each output's level, for a device with more than one (at most four).

  **Items:**

  schema: `StimulationReportChannel`

  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`
- **`device`**: `object | null`, schema: `StimulationReportDevice`

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

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

schema: `StimulationReceipt`

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

    Each output's level, for a device with more than one.

    **Items:**

    schema: `StimulationChannel`

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

    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.
  - **`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.
- **`stimulationAware` (required)**: `boolean`

  Imminence now accounts for time under stimulation.
- **`streamTimeS` (required)**: `number`

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

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

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

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

## Schemas

- `StimulationChannel` — shown above.
- `StimulationDevice` — shown above.
- `StimulationData` — shown above.
- `StimulationReportChannel` — shown above.
- `StimulationReportDevice` — 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.

- `StimulationReport` — shown above.
- `StimulationReceipt` — shown above.
