Skip to main content

api reference

This section provides comprehensive documentation for the Instinct API, including detailed endpoint specifications, authentication methods, error handling, data models, and versioning information.

important

The Instinct API server runs exclusively on the Instinct headset itself. This is the only way to interact with the headset. There is no separate server or cloud-based API available.

base url​

All API requests must be made to the headset's local API server at:

http://localhost:42069

available endpoints​

The Instinct API provides endpoints for all headset operations, organized by functionality:

data processing & streaming​

  • Create Pipeline - POST /stream/streams
    • Create a new data processing pipeline
  • List Pipelines - GET /stream/streams
    • List all available pipelines
  • Get Pipeline - GET /stream/streams/{streamId}
    • Get details of a specific pipeline
  • Delete Pipeline - DELETE /stream/streams/{streamId}
    • Remove a pipeline
  • Pipeline Control - POST /stream/streams/{streamId}/signal
    • Send control signals to a pipeline
  • Node Management - POST /stream/streams/{streamId}/nodes
    • Add nodes to a pipeline
  • Pipe Configuration - POST /stream/streams/{streamId}/pipes
    • Configure data pipes between nodes
  • YAML Import - POST /stream/streams/yaml
    • Import pipeline configuration from YAML

headset management​

  • Get Hostname - GET /system/hostname
    • Retrieve the device hostname
  • Update Hostname - PATCH /system/hostname
    • Change the device hostname
  • Get Configuration - GET /system/config
    • Get current device configuration
  • Update Configuration - PATCH /system/config
    • Update device settings
  • Get Status - GET /system/status
    • Get current device status
  • Health Check - GET /system/healthz
    • Check device health
  • Debug Commands - POST /system/debug/command
    • Execute debug commands

eeg & hardware control​

  • Electrode Management
    • PUT /system/sensors/eeg - Configure EEG sensors
    • POST /system/sensors/eeg/stream - Start EEG streaming
    • DELETE /system/sensors/eeg/stream - Stop EEG streaming
    • GET /system/sensors/impedance - Check impedance
    • GET /system/sensors/impedance/all - Check all impedances
  • Motor Control
    • GET /system/motors/position - Get motor positions
    • GET /system/motors/state - Get motor states
    • POST /system/motors/position - Move motors
    • POST /system/motors/position/reset - Reset all motors
  • LED Control
    • GET /system/led/state - Get LED states
    • PUT /system/led/state - Set LED state

api documentation structure​

The API Reference section is organized as follows:

endpoint categories​

response format​

All API endpoints return responses in JSON format. Successful responses typically include:

{
  "success": true,
  "data": {
    // Response data specific to the endpoint
  }
}

Error responses follow a consistent format:

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human readable error message",
    "details": {
      // Additional error details if available
    }
  }
}
tip

Remember that all API interactions must go through the headset's local API server. There is no separate server or cloud-based API available.

developer documentation​

For conceptual information, refer to the Concepts section, and for practical guidance, check out our Guides & Tutorials.