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

# Upload Script Points Chunk

> Upload script points to the device in chunks for direct playback.

This endpoint is used internally by the server to stream pre-processed script points
to devices. Points are sent in chunks with metadata for tracking and assembly.

The points use a time/position format where:
- `time` is in milliseconds
- `pos` is in range [0..100) representing the position percentage

Maximum 100 points per device command (server handles chunking automatically).




## OpenAPI

````yaml /api-reference/openapi_sdk.yaml post /device/hsc/chunk
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/hsc/chunk:
    post:
      tags:
        - Haptic Script Control
      summary: Upload Script Points Chunk
      description: >
        Upload script points to the device in chunks for direct playback.


        This endpoint is used internally by the server to stream pre-processed
        script points

        to devices. Points are sent in chunks with metadata for tracking and
        assembly.


        The points use a time/position format where:

        - `time` is in milliseconds

        - `pos` is in range [0..100) representing the position percentage


        Maximum 100 points per device command (server handles chunking
        automatically).
      operationId: post-device-hsc-chunk
      parameters:
        - $ref: '#/components/parameters/XDeviceKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadScriptPointsRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: invalid request body
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      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:
    UploadScriptPointsRequest:
      type: object
      description: |
        Request body for uploading script points to the device.
      required:
        - script_id
        - upload_id
        - chunk_id
        - points
        - total_chunks
        - total_points
      properties:
        script_id:
          type: integer
          format: int64
          description: |
            Unique identifier for the script on the current device.
          example: 12345
        upload_id:
          type: integer
          format: uint32
          description: |
            Unique identifier for this upload session.
          example: 1
        chunk_id:
          type: integer
          format: uint32
          description: |
            Sequence number of this chunk (starting from 0 or 1).
          example: 0
        points:
          type: array
          description: |
            Array of script points to upload.
          items:
            $ref: '#/components/schemas/HapticsScriptPoint'
        total_chunks:
          type: integer
          format: uint32
          description: |
            Total number of chunks in this upload session.
          example: 1
        total_points:
          type: integer
          format: uint32
          description: |
            Total number of points in the script.
          example: 100
    BaseResponse:
      type: object
      description: |
        Standard success response.
      properties:
        message:
          type: string
          description: Response message.
          example: ok
    HapticsScriptPoint:
      type: object
      description: |
        A single point in a haptic script.
      required:
        - time
        - pos
      properties:
        time:
          type: integer
          format: uint32
          description: |
            Time offset in **milliseconds** from script start.
          example: 1000
        pos:
          type: integer
          format: uint32
          description: |
            Position value in range [0..100).
          example: 50
  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.

````