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