Data Models

This document describes the core data structures used throughout the Instinct API. Understanding these models will help you interact with the API more effectively.

Stream Models

Stream

A Stream represents a data processing pipeline that processes signal data through a series of nodes connected by pipes.

{
  "id": "string",
  "name": "string",
  "description": "string",
  "nodes": [Node],
  "pipes": [Pipe],
  "created_at": "ISO8601 timestamp",
  "updated_at": "ISO8601 timestamp",
  "status": "string"
}

Field	Type	Description
id	string	Unique identifier for the stream
name	string	Human-readable name for the stream
description	string	Optional description of the stream's purpose
nodes	array	Array of Node objects that make up the stream
pipes	array	Array of Pipe objects that connect the nodes
created_at	string	ISO8601 timestamp of when the stream was created
updated_at	string	ISO8601 timestamp of when the stream was last updated
status	string	Current status of the stream (e.g., "stopped", "running")

Node

A Node represents a processing unit within a stream that performs operations on data.

{
  "id": "string",
  "type": "string",
  "name": "string",
  "config": {
    // Node-specific configuration
  },
  "position": {
    "x": number,
    "y": number
  }
}

Field	Type	Description
id	string	Unique identifier for the node within the stream
type	string	Type of the node (e.g., "source", "filter", "transformer")
name	string	Human-readable name for the node
config	object	Node-specific configuration parameters
position	object	X and Y coordinates for visual representation

Pipe

A Pipe connects two nodes in a stream, defining how data flows from one node to another.

{
  "id": "string",
  "source_node": "string",
  "source_port": "string",
  "target_node": "string",
  "target_port": "string"
}

Field	Type	Description
id	string	Unique identifier for the pipe within the stream
source_node	string	ID of the node where data originates
source_port	string	Output port name on the source node
target_node	string	ID of the node where data is sent
target_port	string	Input port name on the target node

EEG Models

EEG Configuration

Defines the configuration for EEG acquisition.

{
  "sampling_rate": number,
  "gain": number,
  "enabled_electrodes": [string],
  "input_type": "string",
  "bias": boolean
}

Field	Type	Description
sampling_rate	number	Sampling rate in Hz (e.g., 250, 500, 1000)
gain	number	Amplification level for the signals
enabled_electrodes	array	List of electrode identifiers to enable
input_type	string	Input type (e.g., "normal", "shorted", "bias")
bias	boolean	Whether to enable bias

Electrode

Represents an individual electrode on the headset.

{
  "id": "string",
  "name": "string",
  "location": "string",
  "status": "string"
}

Field	Type	Description
id	string	Unique identifier for the electrode
name	string	Human-readable name (e.g., "Fp1", "O2")
location	string	Anatomical location on the scalp
status	string	Current status (e.g., "connected", "disconnected")

Impedance Data

Represents impedance measurements for electrodes.

{
  "timestamp": "ISO8601 timestamp",
  "electrodes": {
    "electrode_id": number,
    // Additional electrode IDs and their impedance values
  }
}

Field	Type	Description
timestamp	string	ISO8601 timestamp of when the measurement was taken
electrodes	object	Map of electrode IDs to impedance values in kOhms

System Models

System Health

Represents the health status of the headset.

{
  "status": "string",
  "uptime": number,
  "cpu": {
    "usage": number,
    "temperature": number
  },
  "memory": {
    "total": number,
    "used": number,
    "free": number
  },
  "battery": {
    "level": number,
    "charging": boolean,
    "time_remaining": number
  },
  "storage": {
    "total": number,
    "used": number,
    "free": number
  }
}

Field	Type	Description
status	string	Overall system status (e.g., "healthy", "warning", "critical")
uptime	number	System uptime in seconds
cpu.usage	number	CPU usage percentage (0-100)
cpu.temperature	number	CPU temperature in degrees Celsius
memory.total	number	Total memory in bytes
memory.used	number	Used memory in bytes
memory.free	number	Free memory in bytes
battery.level	number	Battery level percentage (0-100)
battery.charging	boolean	Whether the battery is currently charging
battery.time_remaining	number	Estimated time remaining in minutes
storage.total	number	Total storage in bytes
storage.used	number	Used storage in bytes
storage.free	number	Free storage in bytes

LED Status

Represents the status of LEDs on the headset.

{
  "power": "string",
  "status": "string",
  "bluetooth": "string",
  "custom": [
    {
      "id": "string",
      "status": "string",
      "color": "string"
    }
  ]
}

Field	Type	Description
power	string	Power LED status (e.g., "on", "off", "blinking")
status	string	Status LED state (e.g., "green", "red", "yellow")
bluetooth	string	Bluetooth LED status
custom	array	Array of custom LED statuses

Motor Position

Represents the position of motors on the headset.

{
  "motor_id": {
    "current": number,
    "target": number,
    "moving": boolean
  },
  // Additional motor IDs and their positions
}

Field	Type	Description
motor_id	object	Map of motor IDs to their position information
current	number	Current position of the motor
target	number	Target position of the motor
moving	boolean	Whether the motor is currently moving

Common Structures

Success Response

Standard response format for successful API calls.

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

Field	Type	Description
success	boolean	Always true for successful responses
data	object	Response data specific to the API endpoint

Error Response

Standard response format for failed API calls.

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "details": {
      // Additional context about the error
    }
  }
}

Field	Type	Description
success	boolean	Always false for error responses
error.code	string	Machine-readable error code
error.message	string	Human-readable error description
error.details	object	Optional object with additional error context

Next Steps

• API Reference Overview
• Data Processing APIs
• Hardware Control APIs