orgasm.dev
Live sessions

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

Authorization

headerAuthorizationBearer <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*string

The live session's id.

Match^ls_[0-9a-z]{20}$

Header Parameters

Idempotency-Key?string

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.

Length1 <= length <= 255

Request Body

The new stimulation state.

application/json
  1. body

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

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.

Value in"on""off"
intensity?|

The intensity now, from 0 to 1 on your product's own scale. Omit it if your product has no intensity.

Range0 <= value <= 1
level?|

The device's level now, on its own scale (for example 0 to 100).

Range0 <= value
levelMax?|

The highest level the device will go to now, on the same scale; a display fills a bar toward it.

Range0 < value
channels?array<>|

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

Itemsitems <= 4
mode?|

The device's mode or pattern, as your product names it (for example waves).

Lengthlength <= 40
modeLabel?|

The mode's name to show the person; without it a display shows mode in words.

Lengthlength <= 40
device?|null
drive?|

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.

Value in"auto""manual""hold""paused"null
streamTimeS?number

When the change happened, in stream seconds. Omit it to mean now.

Range0 <= value

Response Body

The report was recorded.

application/json
  1. response

Confirms a stimulation report, with the stimulation as it now stands: this report merged over the ones before it.

object*string
sessionId*string
state*string
Value in"on""off"
intensity*number|null
streamTimeS*number
stimulationAware*boolean

Imminence now accounts for time under stimulation.

stimulation*

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.

curl -X POST 'https://orgasm.dev/v1/live-sessions/ls_8f3kq2m7x9w4c1n6t5ra/stimulation' \  -H 'Content-Type: application/json' \  -d '{  "state": "on",  "intensity": 0.4}'
Example Response
{  "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  }}