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

# API Overview

> A high-level guide to the Haptics SDK API, including authentication, device control modes, and core haptics endpoints.

# Introduction

Welcome to the **Haptics Docs API**! You can use our API to access **Haptics SDK** endpoints for controlling compatible haptic devices.

All API requests must include the header:

```http theme={null}
Content-Type: application/json
```

unless explicitly specified otherwise.

***

## Base URL

All requests are sent to a single production endpoint:

| Environment    | Base URL                   | Description          |
| -------------- | -------------------------- | -------------------- |
| **Production** | `https://api.getmelody.io` | Live Haptics SDK API |

***

## Authentication & Security

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.

Device endpoints are called with a short-lived **session token**, never the Developer Key directly:

1. **Link a device** to your organization with `POST /device/otp/confirm/v2` (send your Developer Key in the `X-Org-Key` header). This returns the device's **Device Key**.
2. **Create a session token** by exchanging your Developer Key at `POST /api/sessions/v2`.
3. **Call device endpoints** with the session token plus the target Device Key:

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

Requests with a missing or invalid token return `401 Unauthorized`.

***

## Making Requests

The API supports standard REST semantics:

| Method        | Purpose                                                                        |
| ------------- | ------------------------------------------------------------------------------ |
| **GET**       | Query device or session state                                                  |
| **POST**      | Send real‑time motion commands, start/stop modes, upload scripts, generate OTP |
| **PUT/PATCH** | Update device or session configuration                                         |
| **DELETE**    | Stop playback, clear sessions, or disconnect                                   |

### Example request

```bash theme={null}
curl -X GET "https://api.getmelody.io/device/info" \
  -H "Authorization: Bearer <SESSION_TOKEN>" \
  -H "X-Device-Key: <DEVICE_KEY>" \
  -H "Content-Type: application/json"
```

All responses return JSON that follows the schemas declared in OpenAPI document such as `DeviceInfo`, `HapticPoint`, etc.

***

## Core API Domains

### Device Information

* Inspect device details
* Query active session state
* Update device configuration
* Set communication mode (BLE or WiFi)

***

### Haptic Direct Control

* Send **time‑based motion commands**
* Move device to a **target position within a defined time**
* Suitable for custom timeline-driven engines

***

### Haptic Points Stream (HPS)

* Stream **timestamped motion points**
* Automatic velocity smoothing
* Ideal for **real‑time high‑frequency control**

***

### Haptic Script Control (Melody Playback)

* Built for **video‑to‑sensation scripting**
* Upload/assign motion scripts
* Controls: **start, stop, pause, seek**
* Server orchestrates timeline playback

***

### Haptic Loop Control

* Define motion **min/max range**
* Movement loops automatically
* Lightweight continuous patterns

***

### One‑Time Password (OTP)

* Secure **short‑lived pairing secrets**
* Generate and confirm OTP during device binding

***

### Maintenance & Debug

* Remote maintenance commands
* Diagnostics and device status inspection
* Debug or log retrieval if implemented and permitted by device

***

For full endpoint, schema, and parameter details, jump into the Melody API Reference — each tab includes deeper context, practical examples, and detailed request/response insights.