Emotiv Cortex API

https://emotiv.gitbook.io/cortex-api
Admin
Emotiv Cortex API is a brain-computer interface platform that enables developers to build...
Tokens:109,307
Snippets:563
Trust Score:10
Update:9 months ago
Show doc for...
Tokens:
Raw
### Session Data Example

Source: https://emotiv.gitbook.io/cortex-api/session/session-object

This example shows the structure of a session object, including headset status, subscribed streams, and recording information.

```APIDOC
## Session Data Example

### Description
This example shows the structure of a session object, including headset status, subscribed streams, and recording information.

### Method
N/A (Example Data)

### Endpoint
N/A (Example Data)

### Parameters
N/A (Example Data)

### Request Example
N/A (Example Data)

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the session.
- **status** (string) - Current status of the session (e.g., "opened").
- **owner** (string) - The owner of the session.
- **license** (string) - License information associated with the session.
- **appId** (string) - The application ID that created the session.
- **started** (string) - Timestamp when the session started.
- **stopped** (string) - Timestamp when the session stopped (if applicable).
- **headset** (object) - Information about the connected headset.
- **recordIds** (array) - List of record IDs associated with the session.
- **recording** (boolean) - Indicates if the session is currently recording.
- **streams** (array) - List of subscribed data streams (e.g., "met", "mot").

#### Response Example
```json
{
    "id": "8bfc26de-754b-4c1f-9771-acfd1a7da02c",
    "status": "opened",
    "owner": "jon.snow",
    "license": "",
    "appId": "com.jon.snow.winterfell-app",
    "started": "2019-05-29T14:18:45.108+07:00",
    "stopped": "",
    "headset": {
        "status": "connected",
        "connectedBy": "dongle",
        "customName": "",
        "dongle": "6ff",
        "firmware": "625",
        "id": "EPOCPLUS-3B9AXXXX",
        "motionSensors": [
            "GYROX",
            "GYROY",
            "GYROZ",
            "ACCX",
            "ACCY",
            "ACCZ",
            "MAGX",
            "MAGY",
            "MAGZ"
        ],
        "sensors": [
            "AF3",
            "F7",
            "F3",
            "FC5",
            "T7",
            "P7",
            "O1",
            "O2",
            "P8",
            "T8",
            "FC6",
            "F4",
            "F8",
            "AF4"
        ],
        "settings": {
            "eegRate": 256,
            "eegRes": 16,
            "memsRate": 64,
            "memsRes": 16,
            "mode": "EPOCPLUS"
        }
    },
    "recordIds": [],
    "recording": false,
    "streams": ["met","mot"]
}
```
```

--------------------------------

### loadGuestProfile

Source: https://emotiv.gitbook.io/cortex-api/bci/loadguestprofile

Loads an empty profile for a headset. This is a convenient way to get a profile ready without explicit setup.

```APIDOC
## loadGuestProfile

### Description
This method loads an empty profile for a headset. You can use this method to quickly load a profile, without having to create a profile with [setupProfile](https://emotiv.gitbook.io/cortex-api/bci/setupprofile).

### Method
POST

### Endpoint
/loadGuestProfile

### Parameters
#### Request Body
- **cortexToken** (string) - Required - A token returned by [authorize](https://emotiv.gitbook.io/cortex-api/authentication/authorize).
- **headset** (string) - Required - A headset id returned by [queryHeadsets](https://emotiv.gitbook.io/cortex-api/headset/queryheadsets).

### Request Example
```json
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "loadGuestProfile",
    "params": {
        "cortexToken": "xxx",
        "headset": "INSIGHT-12341234"
    }
}
```

### Response
#### Success Response (200)
- **action** (string) - Is always "load".
- **name** (string) - Is always "Guest Profile".
- **message** (string) - A success message.

#### Response Example
```json
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "action": "load",
        "name": "Guest Profile",
        "message": "..."
    }
}
```
```

--------------------------------

### Mental Command Training Event Example (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/data-subscription/data-sample-object

Illustrates a typical system event received when a mental command training session starts. It includes session ID, system event details (mental command started), and timestamp.

```javascript
{
    "sid":"c7e7b527-2b2e-4ec6-8c74-cf16aae8540b",
    "sys":["mentalCommand","MC_Started"],
    "time":1559903035.2961
}
```

--------------------------------

### Get Opt-Out Configuration (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/records/configoptout

This JavaScript code snippet demonstrates how to make a request to the Cortex API to retrieve the current opt-out configuration. It specifies the method 'configOptOut' with the status 'get' and requires a Cortex token.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "configOptOut",
    "params": {
        "cortexToken": "xxx",
        "status": "get"
    }
}
```

--------------------------------

### Instance Marker Object Example (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/markers/marker-object

This example demonstrates the structure of an instance marker object. Instance markers represent a single point in time and are useful for capturing discrete events. The 'endDatetime' field is typically the same as 'startDatetime' for instance markers.

```javascript
{
    "extras": {},
    "label": "test2",
    "port": "Cortex Example",
    "startDatetime": "2019-06-06T15:57:41.529661+07:00",
    "endDatetime":   "2019-06-06T15:57:41.529661+07:00",
    "type": "instance",
    "uuid": "26fccfd8-e487-4623-910a-1ba8591fcdcf",
    "value": 42
}
```

--------------------------------

### Query Subjects Request Example (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/subjects/querysubjects

An example JSON request object for the `querySubjects` method in the Cortex API. It demonstrates how to specify query parameters such as date of birth, sex, and keywords, along with ordering, offset, and limit for pagination.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "querySubjects",
    "params": {
        "cortexToken": "xxx",
        "query": {
            "dateOfBirth": {
                "from": "1979-01-01",
                "to": "1980-12-31"
            },
            "sex": "F",
            "keyword": {
                "yyy":["subjectName", "email"]
            }
        },
        "orderBy": [
            {"subjectName": "ASC"}
        ],
        "offset": 0,
        "limit": 10
    }
}
```

--------------------------------

### Start Mental Command Training (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/bci/training

Initiates a training session for a mental command detection. Requires a Cortex token, session ID, detection type ('mentalCommand'), and the specific action to train (e.g., 'push'). The status must be set to 'start'.

```javascript
{
    "id": 14,
    "jsonrpc": "2.0",
    "method": "training",
    "params": {
        "action": "push",
        "cortexToken": "xxx",
        "detection": "mentalCommand",
        "session": "f3a35fd0-9163-4cc4-ab30-4ed224369f91",
        "status": "start"
    }
}
```

--------------------------------

### Query Subjects Response Example (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/subjects/querysubjects

An example JSON response object for a `querySubjects` request using the Cortex API. It includes the total count, limit, offset, and an array of subject objects that match the query criteria.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "count": 1,
        "limit": 10,
        "offset": 0,
        "subjects": [
            {
                "attributes": [
                    {
                        "name": "Handedness",
                        "value": "Left"
                    },
                    {
                        "name": "Education",
                        "value": "Master's degree"
                    }
                ],
                "city": "London",
                "countryCode": "GB",
                "countryName": "",
                "dateOfBirth": "1980-12-25",
                "experimentsCount": 0,
                "modifiedDatetime": "2019-07-01T11:23:11.644+07:00",
                "sex": "F",
                "state": "",
                "subjectName": "Alice Smith"
            }
        ]
    }
}
```

--------------------------------

### Database Upgrade Completion

Source: https://emotiv.gitbook.io/cortex-api/warning-objects

Indicates the status of the database upgrade process when Cortex starts.

```APIDOC
## Warning Code 23: Database Upgrade Status

### Description
This warning signals the completion status of the database upgrade process that occurs when Cortex starts. It can indicate success or failure.

### Method
N/A (This is a warning notification, not a direct API call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (Implicit)
- **jsonrpc** (string) - Specifies the JSON-RPC version.
- **warning** (object) - Contains warning details.
  - **code** (integer) - The warning code (23).
  - **message** (object) - Warning message details.
    - **success** (boolean) - True if the upgrade was successful, false otherwise.
    - **behavior** (string) - Describes the outcome: "Cortex service is ready." or "Failed to setup Cortex service.".

#### Response Example (Success)
```json
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 23,
        "message": {
            "success": true,
            "behavior": "Cortex service is ready."
        }
    }
}
```

#### Response Example (Failure)
```json
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 23,
        "message": {
            "success": false,
            "behavior": "Failed to setup Cortex service."
        }
    }
}
```
```

--------------------------------

### Database Upgrade Status (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/warning-objects

Reports the status of the database upgrade process when Cortex starts. A 'success' field indicates whether the upgrade was successful, with different messages for success and failure.

```javascript
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 23,
        "message": {
            "success": true,
            "behavior": "Cortex service is ready."
        }
    }
}
```

```javascript
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 23,
        "message": {
            "success": false,
            "behavior": "Failed to setup Cortex service."
        }
    }
}
```

--------------------------------

### Cortex API Warnings Reference

Source: https://emotiv.gitbook.io/cortex-api/warning-objects

Reference for Cortex API warning codes, including their descriptions and example JSON payloads.

```APIDOC
## Cortex API Warnings

This section details various warning codes that can be returned by the Cortex API, along with their corresponding messages and potential causes.

### Warning Code 102

**Description**: Cortex reached a timeout while trying to connect to a headset. This can happen if the wireless connection is of poor quality.

### Warning Code 103

**Description**: Cortex disconnected a headset because it didn't receive any data from this headset for more than 30 seconds. This can happen if the headset goes out of range of the computer, or if the wireless connection is of poor quality.

### Warning Code 104

**Description**: Cortex successfully connected to a headset.

### Warning Code 110

**Description**: Cortex successfully updated the configuration of a headset. This warning was added in Cortex 2.4. See [updateHeadset](https://emotiv.gitbook.io/cortex-api/headset/updateheadset).

### Warning Code 111

**Description**: Cortex failed to update the configuration of a headset. This warning was added in Cortex 2.4. See [updateHeadset](https://emotiv.gitbook.io/cortex-api/headset/updateheadset).

### Warning Code 112

**Description**: Cortex successfully updated a headset, but the new configuration can only work with a USB dongle connection. The configuration is not compatible with a Bluetooth connection. This warning was added in Cortex 2.5. See [updateHeadset](https://emotiv.gitbook.io/cortex-api/headset/updateheadset).

### Warning Code 113

**Description**: Cortex failed to connect to an EPOC+ or EPOC X headset with Bluetooth. The configuration of the headset is not compatible with a Bluetooth connection. This warning was added in Cortex 2.5. See [controlDevice](https://emotiv.gitbook.io/cortex-api/headset/controldevice).

### Warning Code 142

**Description**: Cortex finishes headset scanning, which is started by [controlDevice](https://emotiv.gitbook.io/cortex-api/headset/controldevice) with the "refresh" command.

### Example Warning Payloads

#### Warning Code 0: Data stream unsubscribed

```json
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 0,
        "message": {
            "behavior": "Cortex has stopped all the subscriptions of session 866b8437-2380-4392-9a35-3d5957eaf95d.",
            "sessionId": "866b8437-2380-4392-9a35-3d5957eaf95d"
        }
    }
}
```

#### Warning Code 1: Session closed

```json
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 1,
        "message": {
            "behavior": "Cortex has closed the session 866b8437-2380-4392-9a35-3d5957eaf95d.",
            "sessionId": "866b8437-2380-4392-9a35-3d5957eaf95d"
        }
    }
}
```

#### Warning Code 2: User login

```json
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 2,
        "message": "User jon.snow has already logged in to Cortex."
    }
}
```

#### Warning Code 3: User logout

```json
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 3,
        "message": "User jon.snow has already logged out from Cortex."
    }
}
```

#### Warning Code 9: App access granted

```json
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 9,
        "message": "The access right to the cortex-examples has been granted"
    }
}
```

#### Warning Code 10: App access declined

```json
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 10,
        "message": "The access right to the cortex-examples has been rejected"
    }
}
```
```

--------------------------------

### Setup Profile API

Source: https://emotiv.gitbook.io/cortex-api/bci/setupprofile

The setupProfile method allows for comprehensive management of user training profiles. This includes creating new profiles, renaming existing ones, deleting profiles, loading profiles onto a headset, and unloading currently loaded profiles.

```APIDOC
## POST /setupProfile

### Description
Manages the training profiles of the user. This method supports operations like creating, renaming, deleting, loading, and unloading profiles for a headset.

### Method
POST

### Endpoint
/setupProfile

### Parameters
#### Query Parameters
- **cortexToken** (string) - Required - A token returned by the authorize method.
- **status** (string) - Required - Must be one of the following: "create", "load", "unload", "save", "rename", or "delete".
- **profile** (string) - Required - The name of the profile to act upon. For "unload" status, this should be an empty string.
- **headset** (string) - Required/Optional - Depends on the 'status'. A headset ID returned by queryHeadsets. Required for 'create', 'load', 'unload', and 'save'. Optional for 'rename' and 'delete' if the profile is not associated with a specific headset.
- **newProfileName** (string) - Optional - If the **status** is "rename", this parameter is required and specifies the new name for the profile.

### Request Example
```json
{
  "cortexToken": "your_cortex_token",
  "status": "create",
  "profile": "MyNewProfile",
  "headset": "your_headset_id"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation (e.g., "ok").
- **error** (string) - An error message if the operation failed.

#### Response Example
```json
{
  "status": "ok"
}
```

### Status Specific Details:

#### Status "create"
- **profile** (string) - Required - The name of the new profile. Must be unique.
- **headset** (string) - Required - If provided, creates a copy of the profile currently loaded for this headset.

#### Status "load"
- **profile** (string) - Required - The name of the profile to load.
- **headset** (string) - Required - The ID of the headset to load the profile onto.

#### Status "unload"
- **headset** (string) - Required - The ID of the headset from which to unload the profile.
- **profile** (string) - Required - Should be an empty string. Cortex ignores this parameter during unload.

#### Status "rename"
- **profile** (string) - Required - The current name of the profile to rename.
- **newProfileName** (string) - Required - The new name for the profile.

#### Status "delete"
- **profile** (string) - Required - The name of the profile to delete.
```

--------------------------------

### Create Profile Request

Source: https://emotiv.gitbook.io/cortex-api/bci/setupprofile

This snippet demonstrates how to create a new, empty profile using the setupProfile method. It requires a cortexToken, a profile name, and the status set to 'create'. The response confirms the action and the profile name.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "setupProfile",
    "params": {
        "cortexToken": "xxx",
        "profile": "cortex-v2-example",
        "status": "create"
    }
}
```

--------------------------------

### Get User Information Request (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/authentication/getuserinformation

Example of a JSON request to the getUserInformation method in the Cortex API. This request includes the necessary 'cortexToken' parameter to authenticate and identify the user.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getUserInformation",
    "params": {
        "cortexToken": "xxx"
    }
}
```

--------------------------------

### Get User Information Response (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/authentication/getuserinformation

Example JSON response from the getUserInformation method of the Cortex API. This response contains the 'result' object detailing the user's 'username', 'firstName', 'lastName', and 'licenseAgreement' information.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "username": "jon.snow",
        "firstName": "Jon",
        "lastName": "Snow",
        "licenseAgreement": {
            "accepted": true,
            "licenseUrl": "https://..."
        }
    }
}
```

--------------------------------

### Subscribe to Motion and Performance Metrics (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/data-subscription/subscribe

This example shows a successful subscription request to both motion ('mot') and performance ('met') data streams. The response indicates which streams were successfully subscribed to and the columns available for each. It requires a Cortex token and a session ID.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "subscribe",
    "params": {
        "cortexToken": "xxx",
        "session": "f8cb7289-9a92-438b-8281-e5fdffe8166e",
        "streams": ["met","mot"]
    }
}
```

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "failure": [],
        "success": [
            {
                "cols": ["eng","exc","lex","str","rel","int","foc"],
                "sid": "f8cb7289-9a92-438b-8281-e5fdffe8166e",
                "streamName": "met"
            },
            {
                "cols": [
                    "COUNTER_MEMS",
                    "INTERPOLATED_MEMS",
                    "GYROX",
                    "GYROY",
                    "GYROZ",
                    "ACCX",
                    "ACCY",
                    "ACCZ",
                    "MAGX",
                    "MAGY",
                    "MAGZ"
                ],
                "sid": "f8cb7289-9a92-438b-8281-e5fdffe8166e",
                "streamName": "mot"
            }
        ]
    }
}
```

--------------------------------

### Get Training Time Request and Response (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/advanced-bci/gettrainingtime

This snippet shows an example of a request payload to the getTrainingTime method and its corresponding response. The request includes authentication token, detection type, and session ID. The response contains the training duration in seconds and the detection type.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getTrainingTime",
    "params": {
        "cortexToken": "xxx",
        "detection": "mentalCommand",
        "session": "xxx"
    }
}
```

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "time": 8,
        "detection": "mentalCommand"
    }
}
```

--------------------------------

### Subscribe to Performance Metrics, Fail Raw EEG (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/data-subscription/subscribe

This example demonstrates a subscription request for performance metrics ('met') and raw EEG ('eeg'). The response shows a successful subscription to 'met' but a failure for 'eeg', with an error message indicating the stream is unavailable. It requires a Cortex token and a session ID.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "subscribe",
    "params": {
        "cortexToken": "xxx",
        "session": "49eb6cb0-9df6-414a-b3e8-cfa17198daa0",
        "streams": ["met","eeg"]
    }
}
```

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "failure": [
            {
                "code": -32016,
                "message": "The stream is unavailable or unsupported.",
                "streamName": "eeg"
            }
        ],
        "success": [
            {
                "cols": ["eng","exc","lex","str","rel","int","foc"],
                "sid": "49eb6cb0-9df6-414a-b3e8-cfa17198daa0",
                "streamName": "met"
            }
        ]
    }
}
```

--------------------------------

### Subscribe to Performance Metrics and Fail on EEG

Source: https://emotiv.gitbook.io/cortex-api/data-subscription/subscribe

This example demonstrates a subscription request where one stream ('met') is successfully subscribed to, while another ('eeg') fails due to being unavailable or unsupported. The response clearly indicates which streams succeeded and which failed, along with error details for the failed ones.

```APIDOC
## POST /subscribe

### Description
Attempts to subscribe to specified data streams, handling potential failures for unavailable streams like 'eeg'.

### Method
POST

### Endpoint
/subscribe

### Parameters
#### Request Body
- **id** (integer) - Required - A unique identifier for the request.
- **jsonrpc** (string) - Required - Specifies the JSON-RPC version, usually "2.0".
- **method** (string) - Required - The method to call, "subscribe" in this case.
- **params** (object) - Required - An object containing subscription parameters.
  - **cortexToken** (string) - Required - The authentication token for the Cortex API.
  - **session** (string) - Required - The unique identifier for the current session.
  - **streams** (array) - Required - An array of strings, specifying streams to subscribe to (e.g., "met", "eeg").

### Request Example
```json
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "subscribe",
    "params": {
        "cortexToken": "xxx",
        "session": "49eb6cb0-9df6-414a-b3e8-cfa17198daa0",
        "streams": ["met","eeg"]
    }
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the request.
- **jsonrpc** (string) - The JSON-RPC version.
- **result** (object) - An object containing the results of the subscription request.
  - **failure** (array) - An array of objects detailing failed subscriptions.
    - **code** (integer) - The error code for the failure.
    - **message** (string) - A message describing the reason for the failure.
    - **streamName** (string) - The name of the stream that failed to subscribe.
  - **success** (array) - An array of objects detailing successfully subscribed streams.
    - **cols** (array) - An array of strings representing the columns available for the stream.
    - **sid** (string) - The session ID associated with the stream.
    - **streamName** (string) - The name of the subscribed stream.

#### Response Example
```json
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "failure": [
            {
                "code": -32016,
                "message": "The stream is unavailable or unsupported.",
                "streamName": "eeg"
            }
        ],
        "success": [
            {
                "cols": ["eng","exc","lex","str","rel","int","foc"],
                "sid": "49eb6cb0-9df6-414a-b3e8-cfa17198daa0",
                "streamName": "met"
            }
        ]
    }
}
```
```

--------------------------------

### Update Headset Configuration (EPOC Mode)

Source: https://emotiv.gitbook.io/cortex-api/headset/updateheadset

This example demonstrates setting an EPOC+ headset to EPOC mode, configuring the EEG rate to 128 Hz and disabling motion sensors (memsRate set to 0). A Cortex token and headset ID are necessary. The response confirms the update or details any issues encountered.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "updateHeadset",
    "params": {
        "cortexToken": "xxx",
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "setting": {
            "mode": "EPOC",
            "eegRate": 128,
            "memsRate": 0
        }
    }
}
```

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "headsetId": "EPOCPLUS-3B9AXXXX",
        "message": "..."
    }
}
```

--------------------------------

### getTrainedSignatureActions Response Example (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/advanced-bci/gettrainedsignatureactions

Example of a successful response from the getTrainedSignatureActions method. It details the total training times and a list of trained actions, each with its name and the number of times it was trained.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "totalTimesTraining": 12,
        "trainedActions": [
            {
                "action": "neutral",
                "times": 1
            },
            {
                "action": "push",
                "times": 1
            },
            {
                "action": "pull",
                "times": 1
            }
        ]
    }
}
```

--------------------------------

### Handle App Access Decline (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/warning-objects

This JavaScript code example shows the JSON structure for a warning when an application's access request to Cortex is declined. The message indicates the rejection. This is important for debugging authorization issues.

```javascript
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 10,
        "message": "The access right to the cortex-examples has been rejected"
    }
}
```

--------------------------------

### Get Mental Command Action Sensitivity

Source: https://emotiv.gitbook.io/cortex-api/advanced-bci/mentalcommandactionsensitivity

Retrieves the current sensitivities for the 4 active mental command actions. Requires a cortexToken and specifies the status as 'get'. A profile name can be optionally provided.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "mentalCommandActionSensitivity",
    "params": {
        "cortexToken": "xxx",
        "profile": "cortex-v2-example",
        "status": "get"
    }
}
```

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [5,5,5,5]
}
```

--------------------------------

### Profile Management API

Source: https://emotiv.gitbook.io/cortex-api/bci/setupprofile

This section details the endpoints for managing user profiles, including saving, renaming, and deleting them. These operations are typically performed via the 'setupProfile' method with different 'status' parameters.

```APIDOC
## POST /api/v1/setupProfile

### Description
Manages user profiles by performing actions such as creating, loading, saving, renaming, or deleting them.

### Method
POST

### Endpoint
/api/v1/setupProfile

### Parameters
#### Request Body
- **cortexToken** (string) - Required - The authentication token for the Cortex API.
- **profile** (string) - Required - The name of the profile to be managed.
- **status** (string) - Required - The action to perform on the profile. Possible values: "create", "load", "save", "rename", "delete".
- **headset** (string) - Optional - The headset identifier, required for "load" and "save" statuses.
- **newProfileName** (string) - Optional - The new name for the profile, required for the "rename" status.

### Request Example
```json
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "setupProfile",
    "params": {
        "cortexToken": "xxx",
        "headset": "EPOCPLUS-12341234",
        "profile": "cortex-v2-example",
        "status": "save"
    }
}
```

### Response
#### Success Response (200)
- **action** (string) - The status used in the request.
- **name** (string) - The profile name used in the request.
- **message** (string) - A success message.

#### Response Example
```json
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "action": "save",
        "message": "The profile is saved successfully",
        "name": "cortex-v2-example"
    }
}
```

#### Error Handling
- **400 Bad Request**: If required parameters are missing or invalid.
- **401 Unauthorized**: If the cortexToken is invalid.
- **404 Not Found**: If the profile or headset does not exist.
- **409 Conflict**: If attempting to rename or delete a profile that is in use by another application.
```

--------------------------------

### Create Record Request and Response (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/records/createrecord

Demonstrates the JSON structure for creating a record via the Cortex API. The request includes necessary parameters like `cortexToken` and `session`, while the response details the created record's properties and the session ID. This is useful for managing experiments and data within the Cortex platform.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "createRecord",
    "params": {
        "cortexToken": "xxx",
        "session": "1067dc90-eb17-489b-9514-69cb79ac696c",
        "title": "Cortex Examples C++"
    }
}
```

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "record": {
            "uuid": "222eb845-bc44-4a01-bf28-07445a7c7e8a",
            "applicationId": "com.jon.snow.winterfell-app",
            "applicationVersion": "1.0",
            "description": "",
            "endDatetime": "",
            "experimentId": 0,
            "licenseId": "xxx",
            "licenseScope": ["pm","eeg"],
            "ownerId": "76c3468a-d9c0-428d-81b4-bdac5d63860e",
            "startDatetime": "2019-05-31T11:06:24.398560+07:00",
            "tags": [],
            "title": "Cortex Examples C++"
        },
        "sessionId": "1067dc90-eb17-489b-9514-69cb79ac696c"
    }
}
```

--------------------------------

### Implement Pagination with Limit and Offset (Cortex API)

Source: https://emotiv.gitbook.io/cortex-api/records/queryrecords

Use the limit and offset parameters to implement pagination for displaying records in a UI. This involves making sequential requests with increasing offsets based on the 'count' returned in the response.

```JSON
{
  "limit": 10,
  "offset": 0
}
```

```JSON
{
  "limit": 10,
  "offset": 10
}
```

```JSON
{
  "limit": 10,
  "offset": 20
}
```

--------------------------------

### Get User Login Request (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/authentication/getuserlogin

This snippet demonstrates the JSON-RPC request to the getUserLogin method. It's a simple POST request with the method name and an ID. The request itself has no parameters.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getUserLogin"
}
```

--------------------------------

### Profile Loaded Warning

Source: https://emotiv.gitbook.io/cortex-api/warning-objects

Indicates that a profile has been successfully loaded for a headset.

```APIDOC
## Warning Code 13: Profile Loaded

### Description
This warning indicates that a profile has been successfully loaded for a specific headset.

### Method
N/A (This is a warning notification, not a direct API call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (Implicit)
- **jsonrpc** (string) - Specifies the JSON-RPC version.
- **warning** (object) - Contains warning details.
  - **code** (integer) - The warning code (13).
  - **message** (object) - Warning message details.
    - **behavior** (string) - Describes the event: "Profile is loaded".
    - **headset** (string) - The ID of the headset.
    - **profile** (string) - The name of the loaded profile.

#### Response Example
```json
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 13,
        "message": {
            "behavior": "Profile is loaded",
            "headset": "INSIGHT-12341234",
            "profile": "foo"
        }
    }
}
```
```

--------------------------------

### getTrainedSignatureActions Request Example (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/advanced-bci/gettrainedsignatureactions

Example of a request object for the getTrainedSignatureActions method. It includes the necessary parameters like cortexToken, detection type, and profile name. Ensure 'profile' or 'session' is provided as per API requirements.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "getTrainedSignatureActions",
    "params": {
        "cortexToken": "xxx",
        "detection": "mentalCommand",
        "profile": "cortex-v2-example"
    }
}
```

--------------------------------

### Load Profile Request

Source: https://emotiv.gitbook.io/cortex-api/bci/setupprofile

This snippet shows how to load an existing profile for a specific headset. It requires a cortexToken, the headset ID, the profile name, and the status set to 'load'. The response indicates a successful load.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "setupProfile",
    "params": {
        "cortexToken": "xxx",
        "headset": "EPOCPLUS-12341234",
        "profile": "cortex-v2-example",
        "status": "load"
    }
}
```

--------------------------------

### Get User Login Response - No User Logged In (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/authentication/getuserlogin

This JavaScript snippet shows the expected response when no user is logged into Cortex. The result field is an empty array, indicating no active user session.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "result": []
}
```

--------------------------------

### Offline Support Workflow

Source: https://emotiv.gitbook.io/cortex-api/overview-of-api-flow/offline-support

This section outlines the recommended steps for using the Cortex API offline. It involves obtaining an initial token, generating new tokens when expired, and checking license limits to warn users about impending offline access expiry.

```APIDOC
## Offline Support Workflow

### Description
This workflow details the recommended steps for enabling and managing offline access with the Cortex API. It emphasizes the importance of initial authentication, token renewal, and user notifications regarding license limitations.

### Recommended Flow

**Step 1: Initial Authentication**
Follow the [authorize API flow](https://emotiv.gitbook.io/cortex-api/authentication/authorize) to authenticate with Cortex for the first time. This step requires an active internet connection. Upon successful authentication, a Cortex token will be issued, valid for 48 hours.

**Step 2: Token Renewal**
When the Cortex token expires, call the [generateNewToken](https://emotiv.gitbook.io/cortex-api/authentication/generatenewtoken) API. This API can be called without an active internet connection to generate a new token.

**Step 3: License Limit Check**
Periodically check the license limits using the [getLicenseInfo](https://emotiv.gitbook.io/cortex-api/authentication/getlicenseinfo) API. This allows you to provide timely warnings to users about the remaining offline usage time before the hard limit is reached.

### License Limits

- **softLimitTime**: This is a grace period during which users are warned that offline access will soon be unavailable. The application can still function offline until the `hardLimitTime`.
- **hardLimitTime**: This is the absolute deadline for offline usage. After this time, the application must reconnect to the internet and call the [authorize](https://emotiv.gitbook.io/cortex-api/authentication/authorize) API to continue working with Cortex.

**Note:** The `softLimitTime` is at least one month after the initial `authorize` call, and the `hardLimitTime` is 7 days after the `softLimitTime`.
```

--------------------------------

### JSON-RPC Request Example (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/connecting-to-the-cortex-api

Demonstrates a typical JSON-RPC request to an API method, including the method name, parameters, and a unique request ID. This format is used to call functions within the Cortex API.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "area",
    "params": {
        "width": 6,
        "length": 7
    }
}
```

--------------------------------

### Get Facial Expression Signature (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/advanced-bci/facialexpressionsignaturetype

This JavaScript snippet demonstrates how to request the current facial expression signature using the 'get' status. It requires a cortexToken and session ID. The response indicates the current and available signatures.

```javascript
{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "facialExpressionSignatureType",
    "params": {
        "cortexToken": "xxx",
        "status": "get",
        "session": "xxx"
    }
}
```

--------------------------------

### Get Active Mental Command Actions (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/advanced-bci/mentalcommandactiveaction

Retrieves the list of currently active mental command actions for a given profile. This function requires a cortexToken and specifies the 'get' status. The response will be an array of strings representing the active actions.

```javascript
{
    "id": 544314,
    "jsonrpc": "2.0",
    "method": "mentalCommandActiveAction",
    "params": {
        "cortexToken": "xxx",
        "profile": "cortex-v2-example",
        "status": "get"
    }
}
```

--------------------------------

### Handle User Logout Conflict (JavaScript)

Source: https://emotiv.gitbook.io/cortex-api/warning-objects

This JavaScript code example shows the JSON format for a warning when a user attempts to log out from Cortex but is not currently logged in. It includes a descriptive message. This helps in ensuring correct user session states.

```javascript
{
    "jsonrpc": "2.0",
    "warning": {
        "code": 3,
        "message": "User jon.snow has already logged out from Cortex."
    }
}
```

--------------------------------

### Profile and Session Parameters

Source: https://emotiv.gitbook.io/cortex-api/advanced-bci

Explains the usage of 'profile' and 'session' parameters for BCI operations. These parameters determine whether profile attributes are read from disk or from an active session, and whether they are read-only or read-write.

```APIDOC
## Profile and Session Parameters

### Description
Most methods in this section accept two optional parameters: `profile` (string) and `session` (string). You must provide one, but not both.

- If `profile` is provided, attributes are read from a profile on disk (read-only).
- If `session` is provided, attributes are read from the profile currently loaded in-memory (read-write). Changes can be saved using the `setUpProfile` endpoint.

### Parameters
#### Query Parameters
- **profile** (`string`) - Optional - The name of a profile. If omitted or set to an empty string when using a session, it adheres to specific bug workarounds in older Cortex versions.
- **session** (`string`) - Optional - A session ID obtained from `createSession`. Must be provided if `profile` is omitted or empty.
```
Tokens:
Raw