> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmelody.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get authenticated, connect to your device via BLE or WiFi, and run your first scripted haptics session using the Melody API.

# Quickstart Guide

Bring your project to life with real sensation using the **Melody API**.\
This guide gets you authenticated, connected, and sending your first haptics command — fast.

***

## 1. Get authenticated

All API traffic is routed through a single live endpoint:

```
https://api.getmelody.io
```

Access is scoped to your **organization**. Your **Organization ID** and **Developer Key** (Melody Key) are issued to you by Melody — [contact support](mailto:support@getmelody.io) to request them.

You control devices with a short-lived **session token**:

1. Link a device to your organization via `POST /device/otp/confirm/v2` (Developer Key in the `X-Org-Key` header) to get its **Device Key**.
2. Exchange your Developer Key for a session token at `POST /api/sessions/v2`.
3. Send every device request with both headers:

```http theme={null}
Content-Type: application/json
Authorization: Bearer <SESSION_TOKEN>
X-Device-Key: <DEVICE_KEY>
```

If the token is missing or invalid, the API will return `401 Unauthorized`.

***

## 2. Connect your device

Compatible devices can communicate using **Bluetooth Low Energy (BLE)** or **WiFi hubs/bridges**.\
Both flows use the same universal command schema — so you implement once, and it works everywhere.

| Transport                      | Description                                                   |
| ------------------------------ | ------------------------------------------------------------- |
| **BLE (Bluetooth Low Energy)** | Nearby pairing and ultra‑fast motion command delivery         |
| **WiFi Hub / WiFi Bridge**     | Network‑paired device control via WiFi hubs or bridge routing |

***

## 3. Send your first haptics command

Use `POST /device/hdc/command` (or equivalent command path in your API reference) to send low‑latency motion primitives.

### Example request

```bash theme={null}
curl --request POST \
  --url https://api.getmelody.io/device/hdc/command \
  --header 'Authorization: Bearer <SESSION_TOKEN>' \
  --header 'X-Device-Key: <DEVICE_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "pos": 50,
  "time": 1
}'
```

***

## 4. Start your first scripted sensation session (Melody)

**Melody** is both:

* a **physical interactive haptic device hub we built ourselves**, and
* our **timeline-first scripting engine** for syncing sensation to video and VR playback

With Melody, you can upload or assign a script, then start/pause/seek/stop timeline playback via API.

### Authoring option modes supported

* **Direct target position + time**
* **Sequential haptic point streams (HPS) for smoothing**
* **Server‑orchestrated timeline script playback**
* **Loop range mode** for automatic repeating motion

***

## 6. Next steps

You're now ready to start building with Melody:

<Columns cols={2}>
  <Card title="Melody Overview & Setup" icon="music" href="/melody/overview">
    Learn how to pair the Melody Device Hub, upload scripts, and synchronize video timelines to motion.
  </Card>

  <Card title="BLE API Integration" icon="bluetooth" href="/melody/ble/setup">
    Implement low-latency nearby control for Bluetooth-enabled interactive devices.
  </Card>

  <Card title="WiFi Device Integration" icon="wifi" href="/melody/wifi/device_setup">
    Send motion commands and timeline sessions to devices connected through WiFi hubs or bridges.
  </Card>

  <Card title="SDK & API Reference" icon="book-open" href="/api-reference">
    Deep‑dive into all endpoints, schemas, and parameter descriptions across reference tabs.
  </Card>
</Columns>

***

> 💡 **Tip:** All transports and devices use the same JSON command contract — “write once, feel anywhere.”

You’re now connected and ready to integrate real sensation into your video or VR immersion stack.\
Next, explore the **API Reference** for endpoint and field details.