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

# Play Loop

> Play Haptic Loop



## OpenAPI

````yaml /api-reference/openapi_sdk.yaml post /device/hlc/play
openapi: 3.1.0
info:
  title: Haptics SDK API
  contact:
    name: Haptics API Support
    email: support@getmelody.io
    url: https://docs.getmelody.io/spec
  description: >
    # Introduction


    Welcome to the Haptics Docs API! You can use our API to access Haptics SDK
    endpoints.


    All API requests must contain header `Content-Type: application/json` by
    default. If not explicitly specified otherwise.


    Haptics Prod: [api.getmelody.io](https://api.getmelody.io)


    Haptics Stage:
    [api.haptics.devlikereal.com](https://api.haptics.devlikereal.com)


    # Authentication


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


    To call device endpoints:


    1. Link a device to your organization with `POST /device/otp/confirm/v2`
    (send your Developer Key in the `X-Org-Key` header) to obtain its **Device
    Key**.

    2. Exchange your Developer Key for a short-lived **session token** with
    `POST /api/sessions/v2`.

    3. Call any `/device/*` endpoint with `Authorization: Bearer
    <session_token>` and the `X-Device-Key: <device-key>` header.
  version: v4
servers:
  - url: https://api.getmelody.io
    description: Production
  - url: https://api.haptics.devlikereal.com
    description: Staging
security: []
tags:
  - name: Authentication
    description: >
      Obtain and use organization-scoped access tokens. Your Organization ID and
      Developer Key (Melody Key) are issued to you by Melody — contact
      support@getmelody.io to request them.
  - name: Device Information
    description: |
      The Device Information API encompasses two primary functionalities:

      This section includes endpoints that enable you to:

      - Retrieve detailed information about the device.
      - Access information related to the current session.
      - Update device settings efficiently.
      - Set required device mode.
  - name: Haptic Direct Control
    description: >
      Section convers Direct Control mode. User is able to set position & time
      to get the receiver there.
  - name: Haptic Points Stream
    description: >
      Section covers Points Stream mode. Mode for streaming arrays of signal
      with device position & signal time in the original sender’s timescale. The
      stroker movement velocity is calculated on device and is based on time
      difference between signals. At least two signals needed to calculate
      stroker velocity & move the stroker.
  - name: Haptic Script Control
    description: >
      Section covers Script Playback. The script is sent to device by passing
      the link. After script downloaded by device, server controls device with
      start, stop, pause commands.
  - name: Haptic Loop Control
    description: >
      Section covers Loop Playback. Mode for simple up/down stroking without the
      need for data points. It only needs stroker velocity percentage and
      min/max positions for stroking range to create a loop and move according
      provided range.
  - name: One-Time Password
    description: >
      Section covers One-Time Password. The one-time password is valid for 10-15
      minutes, required for device bootstrapping with 3rd party services.
  - name: Maintenance
    description: >
      This section provides APIs dedicated to the upkeep and troubleshooting of
      the device. Key functionalities include:


      - Firmware Updates: APIs to check for, download, and apply firmware
      updates, ensuring the device is running the latest software version with
      improved features and fixes.

      - Debug Information: Access detailed diagnostic data and logs to
      facilitate troubleshooting and performance analysis.

      - Debug Logging: Enable or disable real-time debug log emission from the
      device. When enabled, the device sends unsolicited `DEBUG_LOG` frames
      (frame type `21`) over the WebSocket. Each frame carries a
      `DebugLogMessage` protobuf payload with a single `message` string field.
      Logs are stored server-side per device (up to 1000 entries) and can be
      viewed in the CMS device detail page.
paths:
  /device/hlc/play:
    post:
      tags:
        - Haptic Loop Control
      summary: Play Loop
      description: Play Haptic Loop
      operationId: post-device-hlc-play
      parameters:
        - $ref: '#/components/parameters/XDeviceKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceHLCPlay'
      responses:
        '200':
          description: OK
      security:
        - SessionToken: []
components:
  parameters:
    XDeviceKey:
      name: X-Device-Key
      in: header
      required: true
      description: |
        Device Key (4 BIP39 words) identifying the target device.
        Obtain it from `POST /device/otp/confirm/v2`.
      schema:
        type: string
        pattern: ^[a-z]+-[a-z]+-[a-z]+-[a-z]+$
        example: alpha-bravo-charlie-delta
  schemas:
    DeviceHLCPlay:
      type: object
      description: |
        The haptic loop control settings of the device.
      properties:
        velocity:
          type: number
          format: float
          minimum: 0
          maximum: 100
          description: |
            The velocity of the loop as a percentage (0-100%).
          example: 50
        low_limit:
          type: number
          format: float
          minimum: 0
          maximum: 10000
          description: |
            The low limit of the loop stroke range [0..10000].
          example: 0
        high_limit:
          type: number
          format: float
          minimum: 0
          maximum: 10000
          description: |
            The high limit of the loop stroke range [0..10000].
          example: 10000
  securitySchemes:
    SessionToken:
      type: http
      scheme: bearer
      description: >
        Short-lived session token obtained from POST /api/sessions/v2.

        Send it as `Authorization: Bearer <session_token>` together with the
        `X-Device-Key: <device-key>` header identifying the target device.

````