DevelopersDocumentation

FUG API Documentation

Device Command & Control Integration Guide

OpenAPI 3.1.0 · v2026.03.16.0 · DCK Auth · JSON

FUG is the real-time device control API for FeelMe haptic hardware. It provides REST endpoints to send motion commands, configure device parameters, and manage device provisioning. This document covers every endpoint, all request/response schemas, error handling patterns, code examples, and a step-by-step integration walkthrough.

Getting Started
Authentication
Environments
Endpoints
Error Handling
Retry & Backoff Strategy
Integration Walkthrough — Happy Path
Code Examples
Schema Reference
Troubleshooting
Support

1. Getting Started

Before making your first API call you will need:

A valid device connection keyfor the target device(s) (see Authentication)
An HTTPS client capable of sending JSON request bodies

2. Authentication

All mutating endpoints (POST) require a device connection key as a DCK token in the Authorization header. Health and version endpoints are public and require no authentication.

Required Headers

Authorization: DCK <device connection key>
Content-Type:  application/json

3. Environments

Base URL	Notes
`https://fug.feelme.com`	Production environment.

4. Endpoints

Method	Path	Auth	Purpose
`POST`	`/api/send_command_to_devices`	Yes	Send motion or raw command to device
`POST`	`/api/send_setup_to_device`	Yes	Configure device parameters
`POST`	`/api/send_reprovision_command_to_device`	Yes	Manage device provisioning lifecycle
`POST`	`/api/get_status_of_devices`	Yes	Request status of devices in a group

4.1 `POST /api/send_command_to_devices`

🔒 DCK required

The primary endpoint for controlling device movement. Sends a typed command — movement to a target position, oscillation between two positions, a raw byte payload, or a pause — to a specific device identified by the device connection key in the auth header.

Request Body

Field	Type	Required	Description
`command_type`	`string (enum)`	Yes	Type of command to execute. See DeviceCommandType.
`arguments`	`object`	Yes	Command parameters. Keys from DeviceCommandArgumentsType.
`command_duration_ms`	`integer`\ `null`	No	Duration in milliseconds. Defaults to device-internal timing if omitted.

DeviceCommandType

Value	Use Case
`MOVEMENT`	Move actuator to a specific position
`MOVEMENT_BETWEEN`	Oscillate between two position boundaries
`PAUSE`	Stop / pause current device motion
`RAW`	Send raw byte string directly to device firmware

DeviceCommandArgumentsType

Available keys: speed · position · min_position · max_position · raw_data

Request Examples

Move to position

{
  "command_type":        "MOVEMENT",
  "arguments":           { "position": 80, "speed": 50 },
  "command_duration_ms": 3000
}

Oscillate between positions

{
  "command_type":        "MOVEMENT_BETWEEN",
  "arguments":           { "min_position": 10, "max_position": 90, "speed": 75 },
  "command_duration_ms": 10000
}

Pause device

{
  "command_type": "PAUSE",
  "arguments":    {}
}

Send raw data

{
  "command_type": "RAW",
  "arguments":    { "raw_data": "0x01 0x02 0xFF" }
}

Response — 200 OK

{
  "status":  "success",
  "message": "Command sent to device(s)"
}

cURL Example

curl -X POST https://fug.feelme.com/api/send_command_to_devices \
  -H "Authorization: DCK $DEVICE_CONNECTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command_type":        "MOVEMENT",
    "arguments":           { "position": 80, "speed": 50 },
    "command_duration_ms": 3000
  }'

4.2 `POST /api/send_setup_to_device`

🔒 DCK required

Configures operating parameters on a device — such as speed intensity scaling, range intensity scaling, or status reporting interval. Send setup commands before issuing motion commands to ensure correct device behavior.

Request Body

Field	Type	Required	Description
`setup_type`	`string (enum)`	Yes	Configuration operation to apply. See DeviceSetupType.
`arguments`	`object`	Yes	Configuration parameters. Keys from DeviceSetupArgumentsType.

DeviceSetupType

Value	Use Case	Argument Keys
`speed_intensity_adjustment`	Scale speed/intensity of all subsequent movement commands	`intensity`
`range_intensity_adjustment`	Scale the range of motion (amplitude intensity)	`intensity`
`status_update_interval`	Configure how frequently the device emits status updates	`interval`

DeviceSetupArgumentsType

Available keys: intensity · interval

Request Example

{
  "setup_type": "speed_intensity_adjustment",
  "arguments":  { "intensity": 70 }
}

Response — 200 OK

Returns HTTP 200 with a JSON body.

{
  "status":  "success",
  "message": "Settings sent to the device(s)"
}

cURL Example

curl -X POST https://fug.feelme.com/api/send_setup_to_device \
  -H "Authorization: DCK $DEVICE_CONNECTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "setup_type": "speed_intensity_adjustment",
    "arguments":  { "intensity": 70 }
  }'

4.3 `POST /api/send_reprovision_command_to_device`

🔒 DCK required

Sends a reprovisioning command to a device to change its connectivity mode or reset stored credentials. Use for device lifecycle management — e.g., switching a device into Bluetooth pairing mode, or wiping credentials before reassigning to a new user.

Request Body

Field	Type	Required	Description
`reprovision_type`	`string (enum)`	Yes	The reprovisioning action to perform.
`arguments`	`object`	Yes	Additional parameters. Can be empty `{}`.

DeviceReprovisionType

Value	Effect
`bt_mode`	Puts the device into Bluetooth pairing/advertising mode
`reset_credentials`	Wipes device credentials; returns to factory provisioning state

Request Examples

Switch to Bluetooth mode

{
  "reprovision_type": "bt_mode",
  "arguments":        {}
}

Reset device credentials

{
  "reprovision_type": "reset_credentials",
  "arguments":        {}
}

Response — 200 OK

{
  "status":  "success",
  "message": "Re-provision command sent to the device(s)"
}

cURL Example

curl -X POST https://fug.feelme.com/api/send_reprovision_command_to_device \
  -H "Authorization: DCK $DEVICE_CONNECTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reprovision_type": "bt_mode",
    "arguments":        {}
  }'

4.4 `POST /api/get_status_of_devices`

🔒 DCK required

Requests status of devices in a group.

Request Body

Field	Type	Required	Description
`payload`	`object`	No	Additional parameters. Can be empty `{}`.

Response — 200 OK

[
  {
    "status": "operational",
    "cpu_usage": 32,
    "serial_number": "1234567890"
  }
]

cURL Example

curl -X POST https://fug.feelme.com/api/get_status_of_devices \
  -H "Authorization: DCK $DEVICE_CONNECTION_KEY" \
  -H "Content-Type: application/json" 

5. Error Handling

HTTP Status Codes

Status	Meaning	When it occurs
`200 OK`	Success	Request accepted and command dispatched
`204 No Content`	No Content	`GET /api/health` — service is healthy
`401 Unauthorized`	Unauthorized	Missing or invalid DCK token
`422 Unprocessable Entity`	Validation Error	Request body fails schema validation
`500 Internal Server Error`	Server Error	Unexpected server-side failure

Validation Error Body (422)

When a request fails validation, the response contains a structured error array indicating exactly which fields are invalid:

{
  "detail": [
    {
      "loc":   ["body", "command_type"],
      "msg":   "Input should be 'RAW', 'MOVEMENT', 'MOVEMENT_BETWEEN' or 'PAUSE'",
      "type":  "enum",
      "input": "SPIN",
      "ctx":   { "expected": "'RAW', 'MOVEMENT', 'MOVEMENT_BETWEEN', 'PAUSE'" }
    }
  ]
}

Field	Description
`loc`	Array path to the invalid field, e.g. `["body", "command_type"]`
`msg`	Human-readable description of the failure
`type`	Machine-readable error classifier, e.g. `enum`, `missing`, `string_type`
`input`	The value that was provided (may be absent)
`ctx`	Additional context such as allowed values (optional)

6. Retry & Backoff Strategy

FUG commands affect physical hardware in real time. Blind retries can cause unintended repeated device movement. Follow these guidelines:

Status	Retry?	Strategy
`200 OK`	No	Success — no retry needed
`401`	No	Fix credentials before retrying
`422`	No	Fix the request payload — retrying will not help
`500`	⚠️ Cautiously	Exponential backoff: 1s → 2s → 4s. Max 3 retries. Send `PAUSE` first if movement was in progress.
Network timeout	⚠️ Cautiously	Treat as ambiguous delivery — the command may have reached the device. Issue `PAUSE` before retrying any movement command.

7. Integration Walkthrough — Happy Path

The minimal integration flow to control a device from scratch:

Step 1 — Obtain device connection key Provision the device through the normal onboarding flow to get its unique device connection key (used as DCK token). This key identifies the target device for all subsequent API calls.

Step 2 — Configure device Send POST /api/send_setup_to_device with speed_intensity_adjustment to set base intensity before any motion commands.

Step 3 — Send a movement command Call POST /api/send_command_to_devices with command_type: "MOVEMENT" and the desired position.

Step 4 — Pause when done Send a PAUSE command when the experience ends to stop device motion cleanly.

8. Code Examples

Postman / OpenAPI Import

The live OpenAPI 3.1 spec is served directly by the API:

GET https://fug.feelme.com/api/docs        # Swagger UI
GET https://fug.feelme.com/api/docs-json   # Raw OpenAPI JSON spec

To import into Postman:

Open Postman → click Import in the top-left.
Select Link and enter https://fug.feelme.com/api/docs-json.
Set a collection variable token to your DCK token. All authenticated requests reference `` in the Authorization header.

9. Schema Reference

DeviceCommandSchema

Field	Type	Required	Notes
`command_type`	`DeviceCommandType`	Yes	`RAW \ MOVEMENT \ MOVEMENT_BETWEEN \ PAUSE`
`arguments`	`object`	Yes	Keys: `speed`, `position`, `min_position`, `max_position`, `raw_data`
`command_duration_ms`	`integer \ null`	No	Duration in milliseconds…

DeviceSetupSchema

Field	Type	Required	Notes
`setup_type`	`DeviceSetupType`	Yes	`speed_intensity_adjustment`	`range_intensity_adjustment` \| `status_update_interval`
`arguments`	`object`	Yes	Keys: `intensity`, `interval`

DeviceReprovisionCommandSchema

Field	Type	Required	Notes
`reprovision_type`	`DeviceReprovisionType`	Yes	`bt_mode`
`arguments`	`object`	Yes	Can be empty `{}`

DeviceCommandResponse / DeviceReprovisionCommandResponse

Field	Type	Description
`status`	`string`	Short status indicator, e.g. `"success"`
`message`	`string`	Human-readable result description

ValidationError (422 `detail` items)

Field	Type	Description
`loc`	`array`	Path to the invalid field, e.g. `["body", "command_type"]`
`msg`	`string`	Human-readable description of the failure
`type`	`string`	Machine-readable classifier: `enum`, `missing`, `string_type`, etc.
`input`	`any`	The value that was provided (may be absent)
`ctx`	`object`	Additional context such as allowed enum values (optional)

10. Troubleshooting

Symptom	Likely Cause	Fix
`401 Unauthorized`	Token missing, malformed, or expired	Check the `Authorization` header. Format must be exactly `DCK <device_connection_key>` — capital letters, space, no quotes.
`422` — “Field required”	`command_type` or `arguments` missing from body	Both fields are required even if `arguments` is `{}`. Check your JSON serialization.
`422` — “Input should be…”	Enum value misspelled or wrong case	Enum values are case-sensitive. E.g., `"MOVEMENT"` not `"movement"`; `"bt_mode"` not `"BT_MODE"`.
Command accepted but device doesn’t move	`device_connection_key` refers to a disconnected device	Verify the device is online. Refresh the active DCK from your socket/event system.
Device moves unexpectedly after a retry	Command delivered twice	Send `PAUSE` before any retry of a movement command. Treat network timeouts as ambiguous delivery.

11. Support

For integration questions, access requests, and credential provisioning contact the FeelMe integrations team:

🌐 Swagger UI: https://fug-prd.feelme.com/api/docs

DevelopersDocumentation

FUG API Documentation

Table of Contents

1. Getting Started

2. Authentication

Required Headers

3. Environments

4. Endpoints

4.1 POST /api/send_command_to_devices

Request Body

DeviceCommandType

DeviceCommandArgumentsType

Request Examples

Response — 200 OK

cURL Example

4.2 POST /api/send_setup_to_device

Request Body

DeviceSetupType

DeviceSetupArgumentsType

Request Example

Response — 200 OK

cURL Example

4.3 POST /api/send_reprovision_command_to_device

Request Body

DeviceReprovisionType

Request Examples

Response — 200 OK

cURL Example

4.4 POST /api/get_status_of_devices

Request Body

Response — 200 OK

cURL Example

5. Error Handling

HTTP Status Codes

Validation Error Body (422)

6. Retry & Backoff Strategy

7. Integration Walkthrough — Happy Path

8. Code Examples

Postman / OpenAPI Import

9. Schema Reference

DeviceCommandSchema

DeviceSetupSchema

DeviceReprovisionCommandSchema

DeviceCommandResponse / DeviceReprovisionCommandResponse

ValidationError (422 detail items)

10. Troubleshooting

11. Support

4.1 `POST /api/send_command_to_devices`

4.2 `POST /api/send_setup_to_device`

4.3 `POST /api/send_reprovision_command_to_device`

4.4 `POST /api/get_status_of_devices`

ValidationError (422 `detail` items)