1 of 75

Cortex API V4

Getting Started

This documentation contains guidance for developing applications with EMOTIV Cortex - the core piece of technology at EMOTIV which brings the brain computer interface to consumer.

The intended audience is anyone with some programming skills who wants to develop a third party application that interacts with an EMOTIV headset.

The Cortex API is built on JSON and WebSockets, making it easy to access from a variety of programming languages and platforms.

System requirements and supported platforms

Learn more about .

Supported headsets

Currently, Cortex supports the following headsets:

USB dongle refers to the USB receiver that comes with EPOC+. If you need an additional receiver, you can purchase it from the EMOTIV.

Currently, it is not possible to use a Flex or a MN8 headset with Cortex on Raspberry Pi.

Virtual Brainwear

In addition to physical EMOTIV headsets, users can create virtual headsets (a “Virtual Brainwear®”) using the EMOTIV Launcher, which emulates device states and data streams for development purposes.

Important caveat: Records captured using a virtual headset are local to that machine and will not be synced to another device or transferred between machines.

For more details on creating and using virtual devices, see “”

Prerequisites

Create an EmotivID

As with other EMOTIV services, you are required to have an EmotivID account. You can create an ID on .

License

If you’re ready to start developing with EMOTIV’s Cortex SDK, one of your first steps is registering your Cortex App ID. Whether you’re working with consumer devices like the Insight or MN8, or exploring options with professional-grade hardware such as the EPOC X or EPOC Flex, this guide will walk you through how to get started with consumer devices.

Understanding Cortex API Access Levels

EMOTIV’s Cortex SDK supports multiple EEG and behavioral data streams. These are grouped into Basic (BCI API) and Premium categories:

Basic (BCI API) Includes:

Mental Commands API
Facial Expression API
Frequency Band API
Motion Data API

Premium API Includes:

Raw EEG API
High-resolution Performance Metrics (2 Hz)

Consumer devices (Insight, MN8) will allow access to all data streams through our Developer SDK and API. You can register here to get started: . Professional devices (EPOC X and EPOC Flex) include free access to the Basic BCI API. To access the Premium API, however, a premium Developer API license is required. If you don't have a valid Developer API license, please submit your SDK application and specify the level of data stream you wish to access with your professional device. Our support team will then guide you on the appropriate licensing option to get started.

Create a Cortex App

To learn how to register your Cortex App ID and begin development, please refer to .

Client ID and Client Secret

Once you register your Cortex App ID, you will receive a Client ID and Client Secret, which serve as unique identifiers for your software application. These will be used as input parameters for some authentication Cortex API calls.

The "Client ID" and "Client Secret" similar to a username and password, are automatically generated by EMOTIV for each version of your software application.

The Cortex Examples

To help you getting started with your application, EMOTIV provides basic examples in various programming languages. There are open source and hosted by Github at

If you have difficulty with the Cortex API, you can also on this Github repository.

Next Step

If you are upgrading your application from Cortex 1.x to Cortex 2.x, then please be aware that the Cortex API has significantly changed. Please read the for details.

If you are new to the Cortex API, then please start with .

Connecting to the Cortex API

On Windows and MacOS, the Cortex service is a background process that communicates with the EMOTIV headsets and the EMOTIV cloud. It is also a WebSocket server that uses the JSON-RPC protocol.

WebSocket

Communicate with the Cortex API using the WebSocket Secure protocol.

Create a WebSocket client and connect to localhost on the port 6868, using the wss protocol.

Any WebSocket client should work in any programming language. You can even use a web browser plugin or an .

Please note that Cortex only supports the WebSocket Secure (wss) protocol. It doesn't support the plain WebSocket (ws) protocol without encryption.

To try the Cortex API, open a secure WebSocket connection to wss://localhost:6868 and send the message {"id":1,"jsonrpc":"2.0","method":"getCortexInfo"}

Cortex security certificate

The Cortex web socket server uses a self-signed certificate. When you install Emotiv softwares, the installer has already installed the Emotiv Root CA file and ask the system to trust it, so most of the time, your application don't need to configure anything else. However, for some programming languagues or for remote connections to Pi, you must configure a custom Certificate Authorities (CA) to trust Cortex websocket connection.

For example, on Android, you must configure the application like or if you use python, you can configure the application like .

Here is .

Remote connections

Since 2.7.1 release, we support remote connections to Cortex running on Raspberry Pi device. It requires some steps:

Grant the permissions to a desktop machine before an app on that machine can connect to the Cortex web socket server on Raspberry Pi device, using tool.
Connect using the IP address:
- Only applied if the IP address of your Raspberry Pi device is in the below range:

Please note that websocket server on Raspberry Pi accepts only 1 remote connection at a time (not counting the remote connection from EMOTIVApp).

JSON-RPC

After you have successfully opened the WebSocket connection, communicate with Cortex using the protocol.

Call methods, with or without parameters, and Cortex sends back a result or an error.

Call an API method by sending a JSON object with these fields:

The response from Cortex is a JSON object with these fields:

Here is a simple fictional example:

Please read the for details.

Test API request and response

You can try with the most simple API of Cortex: .

Next step

The rest of this documentation will show you what methods are available, what parameters they take, and how to use these methods.

But first, you should start with the .

getCortexInfo

This method returns information about the Cortex service, like its version and build number.

Parameters

This method has no parameter.

Result

The result is an object with these fields:

Example

Overview of API flow

There are a few steps to prepare before you can get the data streaming out from Cortex web socket server:

First you have to login to the EMOTIV Launcher with your EmotivID.
Make sure that you are using the correct application ID, client ID and client secret that you generated from the Account dashboard on Emotiv website in your application (see here).
Call the API from your app to Cortex, and accept via the EMOTIV Launcher.
After access is granted, connect your EMOTIV brainwear headset via the USB dongle or Bluetooth.
Call the API with "refresh" command to start the headset scanning.
Call the API to list the available headsets.
Call the API with "connect" command to connect to the desire headset.
Call the API to get a Cortex token for subsequence requests.
Call the API to open up a new session and be ready for BCI data streaming.

Offline support

Once the app authenticates with the Cortex successfully, it can use the Cortex token to stay offline while working with Cortex for a period of time (see soft limit, hard limit below).

Here is the recommended flow to work offline with Cortex:

Step 1: Follow this API flow to get Cortex token the first time. This flow requires the Internet connection. A Cortex token will be available for 48 hours.

Step 2: When the Cortex token is expired, call generateNewToken API to generate another token. This API doesn't require the Internet connection.

Step 3: Check soft limit, hard limit of the current license via getLicenseInfo API and warn the users to be online.

In the license information, there are 2 fields "softLimitTime" and "hardLimitTime".

softLimitTime

This is the reasonable time to warn users that the app will not be able to use offline soon. The app can still work offline until hardLimitTime.

hardLimitTime

This is the time that the app will be no longer to use offline. The app must call API with the Internet connection to be able to continue working with Cortex.

The softLimitTime will be at least 1 month later from the time the app calls API. The hardLimitTime is 7 days after softLimitTime.

Authentication

After your application is successfully connected to the Cortex service, you must go through the authentication procedure.

First, you should call getUserLogin to check if the user has already logged in though EMOTIV Launcher. Then, you must call requestAccess to ask the user to approve your application.

Finally, call authorize to generate a Cortex token or you can reuse a token that you previously got from this method, if it is not expired.

getUserLogin

Get the current logged in user.

There is no login or logout API in Cortex. Instead, users are required to login through the EMOTIV Launcher.

Parameters

This method has no parameter.

Result

The result is an array of objects, each object describes a logged in user. If no user is logged in, then the result is an empty array.

Please note that currently, Cortex is a single user system. Only one user can login at a time, so the result contains at most one object.

The user object includes these fields:

If currentOSUId is equal to loggedInOSUId, then the user is already logged in and can work with Cortex. If currentOSUId is different from loggedInOSUId, then a user is logged into Cortex, but from a different OS account. So the user of the current OS account cannot work with Cortex, and must check EMOTIV Launcher.

Examples

No user is logged in

A user is logged in from the current OS account

A user is logged in from another OS account

The application is connected to Cortex that belongs to the OS account 501/jsnow. But someone has already logged in to Cortex from OS account 502/astark with the EmotivID aria.stark. So, the application cannot work with Cortex.

requestAccess

Request user approval for the current application through EMOTIV Launcher.

When your application calls this method for the first time, EMOTIV Launcher displays a message to approve your application. You can call this API many times, but EMOTIV Launcher will prompt the user only once. If the user has already approved your application, then this API does nothing.

Almost all the methods of the API require that your application was approved in EMOTIV Launcher. These methods will return an error if your application wasn't approved.

Any application that connects to Cortex must call this API to request approval from the user through .

Most of the methods of the API will fail if the user didn't approve your application.

Parameters

Result

The result is an object containing a boolean value "accessGranted" and a message.

If accessGranted is false, then your application should ask the user to check EMOTIV Launcher and approve your application. Then you should wait for a while and call this API again. If accessGranted is true, then no action is required.

Examples

Application was already approved

Application is not approved yet, or declined

hasAccessRight

Check if your application has been granted access rights or not in EMOTIV Launcher.

Any application that connects to Cortex must request approval from the user through EMOTIV Launcher. See requestAccess for details.

Parameters

Result

The result is an object containing a boolean value "accessGranted" and a message.

If accessGranted is false, then your application should call If accessGranted is true, then no action is required

Examples

authorize

This method is to generate a Cortex access token. Most of the methods of the Cortex API require this token as a parameter.

Application can specify the license key and the amount of sessions to be debited from the license and use them locally.

Cortex token

The token is linked to your application. It cannot be used with another application. The token is also linked to the EmotivID of the current user. It cannot be used with another EmotivID. So if the user logs out in EMOTIV Launcher, and then logs in with another EmotivID, your application must call this API again to get a new token.

Your application can save the Cortex token and reuse it later, within 2 days. Note that it is the responsibility of the application to secure the token.

The Cortex token must remain secret. Do NOT share it. It is your responsibility to keep it secure.

Once having Cortex token, the app can .

EULA not accepted warning

If the user has not accepted the EULA, then a warning message will be included in the response as well. The user must accept the EULA through EMOTIV Launcher.

Before you call this method, the user must approve your application in . See for details.

Parameters

Result

The result is an object containing a field cortexToken. It may also include a field warning, if the user didn't accept the EULA.

Examples

getUserInformation

This method returns basic information about the current user.

Parameters

Name

Type

Required

Description

Result

The result is an object containing basic information about the user.

Examples

getLicenseInfo

This method returns information about the license currently used by your application.

Parameters

Name

Type

Required

Description

Result

The result is an object containing a license object and the isOnline flag.

Example

Headsets

After you finish the authentication process, your application should start headset scanning to search for EMOTIV headsets, using the method controlDevice with "refresh" command, then use the method queryHeadsets to get the discovered headsets.

If the headset is not connected to Cortex yet, then you must call controlDevice with "connect" command.

controlDevice

This method is to connect or disconnect a headset. It can also refresh the list of available Bluetooth headsets returned by queryHeadsets.

Please note that connecting and disconnecting a headset can take a few seconds.

Before you call createSession on a headset, make sure that Cortex is connected to this headset. You can use queryHeadsets to check the connection status of the headset.

This method is not available on iOS. On iOS the user must connect and disconnect the headset in EMOTIV App.

Parameters

Headset Scanning Flow

The app must call controlDevice with "refresh" command to start headset scanning. The timeout of scanning is around 20s. When the scanning finishes, Cortex will send a to the app. When received this warning, if the app still want to scan for headsets, simply call controlDevice with "refresh" command again.

Please note that headset scanning can affect to data stream quality if headset scanning is running at the same time with data stream subscription, so we recommend app developers to design the app so that we only run headset scanning when necessary.

EPOC Flex mapping

The mappings parameter is only to connect an EPOC Flex headset. Use this parameter to tell Cortex how you setup the EEG sensors of your EPOC Flex headset.

The keys for this object must be chosen from this list: "CMS", "DRL", "LA", "LB", "LC", "LD", "LE", "LF", "LG", "LH", "LJ", "LK", "LL", "LM", "LN", "LO", "LP", "LQ", "RA", "RB", "RC", "RD", "RE", "RF", "RG", "RH", "RJ", "RK", "RL", "RM", "RN", "RO", "RP", "RQ".

The keys "CMS" and "DRL" are required.

The values are sensor locations from the international 10-20 system: "Cz", "FCz", "Fz", "Afz", "Fpz", "Fp1", "AF3", "AF7", "F9", "F7", "F5", "F3", "F1", "FC1", "C1", "C3", "FC3", "FC5", "FT7", "FT9", "T7", "C5", "TP9", "TP7", "CP5", "CP3", "CP1", "P1", "P3", "P5", "P7", "P9", "PO9", "PO7", "PO3", "O1", "O9", "CPz", "Pz", "POz", "Oz", "Iz", "O10", "O2", "PO4", "PO8", "PO10", "P10", "P8", "P6", "P4", "P2", "CP2", "CP4", "CP6", "TP8", "TP10", "C6", "T8", "FT10", "FT8", "FC6", "FC4", "C4", "C2", "FC2", "F2", "F4", "F6", "F8", "F10", "AF8", "AF4", "Fp2".

Special EEG sensor mapping for EPOC Flex

By default, the streams "met", "com" and "fac" are not available for EPOC Flex. It is because Cortex doesn't implement the detections (performance metrics, mental command, facial expression) for EPOC Flex.

However, you can configure your EPOC Flex to simulate an EPOC X headset. In that case, Cortex runs the detections that are designed for EPOC X.

All you have to do is to use a sensor mapping that includes all the 14 EEG sensors of an EPOC X headset: AF3, F7, F3, FC5, T7, P7, O1, O2, P8, T8, FC6, F4, F8, AF4. In addition, you should use P3 and P4 as references CMS and DRL. Please see the EPOC X for the complete EPOC X configuration.

Your mapping can also include sensors that are not present on an EPOC X. Cortex will not use these additional sensors to run the detections, but you can use them to collect more EEG data.

There are two methods for creating the mapping for EPOC Flex:

Using the EMOTIV Launcher, which can be accessed .
Using the configMapping API, available .

Example of special EEG sensor mapping:

This feature was added in Cortex 2.7.1

Connection Type

You can use this parameter together with the command "connect", to force Cortex to use the specified connection type. For example, an EPOC+ headset can be connected by dongle or by Bluetooth. If both connections are available on your computer then you may want to set connectionType to "dongle" so you don't accidentally connect the headset with Bluetooth.

Result

The result is an object containing these fields:

When the command is "connect", then the result of this method just tells you that the connection is in progress. You must wait for a warning object with to know that the connection is successful. If the connection fails then you will receive a warning with .

Another way to check if the headset is connected or not is to call and then check the status of the headset.

Examples

Refresh the list of headsets

Use the refresh command to start searching for new Bluetooth headsets.

Then you will receive a when scanning is finished.

Connect an Insight headset

Then you will receive a warning with code 104 if the connection is successful:

Connect an Epoc Flex headset

Disconnect a headset

configMapping

The configMapping API manages EEG channel mapping configurations for a EPOC Flex headset. This API allows you to create, get, read, update and delete mapping configurations.

To connect to an EPOC Flex headset, you must input a specific EEG channel mapping or the name of an existing mapping for the current Emotiv user.

Parameters

Status create

Create a new sensor mapping for EPOC Flex. The configuration will be added to list EEG sensor mapping configuration of current emotiv user, can be synced to other machine. Requires: cortexToken, status="create", name, and mappings.

Example

Status get

Retrieve all mapping configurations for the current Emotiv user. Requires: cortexToken, status="get".

Example

Status read

Read the details of a specific configuration. Requires: cortexToken, status="read", uuid.

Example

Status update

To update an existing mapping configuration. Requires: cortexToken, status, and uuid.

The name and mappings are optional parameters:

If name is included, the configuration name will be updated.
If mappings is included, the mappings will be updated.
If both are included, both fields will be updated.

Example

Status delete

Delete a mapping configuration. Requires: cortexToken, status="delete", uuid.

Example

updateHeadset

This method lets you change the settings of an EPOC+ or EPOC X headset.

You can configure the EEG sample rate, EEG resolution, motion data sample rate, and motion data resolution. You can check the current settings of a headset using the method queryHeadsets.

This method is for EPOC+ and EPOC X headsets only. There are no configuration settings for other EMOTIV headsets.

Please note that updating the configuration of a headset can take a few seconds.

The user must connect the headset to the computer by using a USB cable before calling this method. You can't configure the headset through a wireless connection. You can use to check how the headset is connected.

Parameters

The setting parameter must be an object with these fields:

A motion rate of zero means that the motion sensors are disabled.

Result

The result is an object containing these fields:

In Cortex 2.3.0 and earlier, you just need to check the result of the method. If the method doesn't return any error, then it means that the update is successful.

However, since Cortex 2.4.0, the result of the method just tells you that the update is in progress. You must wait for a warning object with to know if the update is successful or not.

If your configuration is not compatible with a Bluetooth connection then you will receive a warning with . Your configuration will work fine with a USB dongle. To use the headset with a Bluetooth connection, you must set the EEG rate to 128Hz and disable the motion sensors.

Examples

Set the EEG rate to 256 hertz (16 bits) and the motion rate to 64 hertz (16bits)

Set the EPOC+ headset in EPOC mode, EEG rate at 128 hertz (14 bits) and disable the motion sensors.

Error Codes

Here is a list of the error codes that the Cortex API can return. This list is not exhaustive (yet) and will be updated in the future.

-32700 Parse Error

The message you sent to Cortex is not a valid JSON object. This is a bug is your application.

-32600 Invalid Request

The message you sent to Cortex is a valid JSON object but it doesn't contain the expected fields. This a bug is your application. Please check

-32601 Method Not Found

You sent a request with an invalid method name. This a bug is your application. Please check this documentation to see which methods are available.

-32602 Invalid Parameters

You sent a request to call a valid method, but the parameters are wrong. It can be because:

You didn't provide a required parameter
You provided a parameters with an invalid name
The name of parameter is correct but the value is invalid

This is a bug in your application. Please check the documentation of the method.

-32603 Internal Error

An unexpected error happened in Cortex while processing your request. This is probably a bug in Cortex. If the problem persists, please contact the .

-32000 Server Internal Error

An unexpected error happened in the EMOTIV cloud while processing your request. It can be a temporary failure of the EMOTIV servers, like when the servers are in maintenance. Or it can be a bug in Cortex. If the problem persists, please contact the .

-32002 Invalid License ID

The EMOTIV cloud cannot find the license of the user. When you call the method , please make sure that you provide a valid license ID, or no license parameter at all. If the problem persists, then the owner of the license must contact the .

-32003 Internet Connection Error

Cortex must connect to the EMOTIV cloud to process your request, but the connection failed. Please make sure that you computer has a working internet connection. Please make sure your internet is not blocked by any firewall or security, see .

-32004 Headset Unavailable

You sent a request to perform an action on a specific headset, but Cortex cannot find this headset. Some possible reasons for this error:

You provided an invalid headset ID in your request
The headset was disconnected (maybe it is out of range of your computer)
The headset was switched off

-32005 A session already exists with this headset

You called the method for a specific headset, but your application already has a session for this headset. This is a bug in your application. You cannot create 2 sessions for the same headset at the same time. You must the existing session before creating a new one.

-32006 No license to activate a session

You called or with the parameter "status" set to "active", but your license doesn't authorize you to activate a session. You have a paid EMOTIV license to activate a session. If you already have such a license but the problem still persists, then contact the . You should also read the .

-32007 The session doesn't exist

You included a session ID in the parameters of your request, but Cortex cannot find this session. It can be because you session ID is invalid or because the session is already closed.

Many methods can return this error: , , , , , , etc...

-32012 The session must be activated

You called a method that requires an active session, but the current session is inactive. It can happen if you call on an inactive session.

-32014 Invalid Cortex token

You included a Cortex token in the parameters of your request, but this token is invalid. This is a bug in your application. When a method requires a Cortex token, please make sure that your token comes from the result of the method .

-32015 The Cortex token has expired

Your Cortex token has expired. You must call the method again to get a new token. The Cortex token is valid for 48 hours.

The requires Internet access. If you want your app to stay offline for longer time, you should call to generate a new token from the expired token.

-32016 Invalid stream

You called the methods or with an invalid stream. The stream can be invalid for one of these reasons:

The name of the stream is incorrect. Check for the list of the available streams.
The stream is not available for this headset. For example, the motion data of an EPOC X headset can be disable.
The stream is "eeg" but the license doesn't allow you to access this stream. You can check the license with

-32017 Record already started

You called for a specific session, but your application already started a record for the same session. You cannot create 2 records for the same session at the same time.

-32019 Session limit has been reached

You tried to activate a session (with or ) but the "localQuota" of the license is zero. You can check the "localQuota" by calling the method . Every time you activate a session, the local quota of the license is reduced by 1.

To solve this error, you must increase the local quota of the license. Call with the parameter "debit". For example, you can call with a "debit" of 10, and this will increase the local quota by 10. Then you will be able to create and activate 10 sessions on this computer.

-32020 The headset must be connected with a USB cable

You called but the headset is connected to the computer via Bluetooth or a USB dongle. Instead, the user should connect the headset with a USB cable.

-32021 Invalid client credentials

The error indicates that your request includes an invalid client ID or client secret. Ensure your request contains a valid client ID and client secret. You can obtain these credentials by registering your App ID with the Cortex SDK for development according to the .

-32022 Device limit has been reached

The license was used on too many devices (eg computer, tablet, phone...). The license has a device limit. You can check it by calling the method . If you want to increase the limit or transfer the license from 1 device to another, then please contact the .

-32024 The license has expired

The license of the user has expired. You can check the license with . After the license is renewed, your application must call to get a new token.

-32027 Cannot use this license

You called with a valid license ID but your application doesn't have the permission to use this license.

-32029 License hard limit has been reached

When the computer is offline, you can use the license for a limited period of time. The end of this period is the "hard limit" of the license. You can check it with . After the "hard limit" has been reached, Cortex must connect to the EMOTIV cloud to validate the license again. To solve this problem, the computer must have an internet connection and then you must call .

-32031 Invalid profile name

You sent a request to perform an action on a specific , but Cortex cannot find this profile.

-32032 Multi Emotiv ID user

You can got this error when call login while there is already a EmotivID user logged in. Before login in, you should check if there is logged in EmotivID user via getUserLogin API.

This error is only available on Cortex version which support login API (for example: Cortex embedded lib).

-32033 EmotivID user is not logged in

Cortex cannot process your request because no EmotivID user is logged in.

For the Cortex websocket server, you must ask the user to log in in .

For other Cortex version which supports login, you must call login first.

-32034 The Cortex token is for another user

Your request includes a Cortex token that was created for a specific user, but the current user is a different one. In that case, that must call again and get a new token. You can check the current user with .

-32035 EmotivID is not matching with logged in user

You will get this issue if the username is not the same with currently logged in EmotivID user.

Related API are logout. This API is only available for the Cortex embedded lib.

-32037 Cannot train this action

You called for an action that cannot be trained. Please see available actions .

-32044 Profile already loaded on another headset

You tried to a training profile for a specific headset, but this profile is already loaded for another headset. You cannot load the same profile on 2 different headset at the same time.

-32045 No profile loaded for this headset

You tried to unload a training profile from a headset, but no profile was loaded for this headset.

-32046 Profile loaded by another application

You tried to perform an operation (eg , ...) on a training profile, but this profile was loaded by another application. An application can only access a profile that loaded by itself. You can call to check if your application loaded the profile of a headset or not.

-32102 Not approved in EMOTIV Launcher

The user didn't approved your application yet. The user must open and approve your application.

-32104 Failed to connect or disconnect the headset

Cortex failed to communicate with the headset. Maybe the wireless connection between the headset and the computer was interrupted. Your application should try again. You can also call to check the status of the headset.

-32106 The user account is not active

The EMOTIV ID of the user is inactive. The app will get this error when the user has registered the EmotivID account but haven't activated via email yet.

-32107 Cannot accept license agreement

If you got this error when calling acceptLicense API, there is a bug in our Cortex or Emotiv Cloud. Please report this issue to .

This acceptLicense is only available on the Cortex embedded lib.

-32108 Cloud token error

The EMOTIV cloud refused the user credentials provided by Cortex. The user must logout and login again.

-32109 Cortex token error

There is something wrong with the Cortex token. Your application must call to get a new Cortex token.

-32111 The information cannot be found in database

For APIs that need information from the local database, if Cortex cannot find this information in the database, this error is returned. This error is general and can be returned for any API. If the problem persists, please contact .

-32112 The session is already active

You tried to a session that is already active. You can call to check the status of your sessions.

-32113 Invalid record ID

You are trying to access a record that doesn't exist, or the record exist but you don't have the permission to access it.

-32114 No record in progress

You are trying to a marker or to a record but no record is is progress.

-32115 The time of the marker is too far in the past

You are trying to inject a marker but its time is too far in the past. You should inject your markers in real time, at the moment the event you want to mark happens.

Sometimes you may get the issue because the difference between the time system in your app and the headset time system in Cortex is considerable. In this case, to have better synchronization with the headset time system, please use the API.

-32116 The time of the marker is too far in the future

You are trying to inject a marker but its time is too far in the future. You should inject your markers in real time, at the moment the event you want to mark happens.

-32117 Marker not found

You called with an invalid marker id.

-32118 The profile name already exists

You are trying to or rename a training profile, but another profile with the same name already exists.

-32119 The marker is already stopped

You are trying to a marker that was already updated before.

-32120 headset mapping config name already exists

The error can occur if you use an existing mapping name while creating a new mapping with the API.

-32121 The flex config was not found.

This error occurs when you use a non-existent EPOC Flex mapping UUID or name while calling the or API.

-32122 Cortex is starting

The app will get this error sometimes after the app connection is established to Cortex web socket server or after the app call CortexLib::start() API of the Cortex embedded lib, when it takes long for Cortex to be ready, especially when Cortex needs to do some database upgrading. In this case, the app only needs to wait for a while and remake API calls.

-32123 Corrupted database

The local Cortex database is corrupted. Please contact the .

-32124 Subject not found

You are trying to or a subject that doesn't exist. Or you are trying to a record with an invalid subject.

-32125 Subject already exists

You are trying to create a subject, but another subject with the same name already exists.

-32126 The record session is running

The app can get this error if you call on a running record. Please make sure the app calls before .

-32127 Profile already loaded for this headset

You are trying to a training profile for a headset, but a profile was already loaded for this headset before. You must unload the current profile before loading a new one.

-32129 Invalid record title

You are trying to create or update a record, but the record title is invalid. The title must be 200 characters long or less.

-32130 Cloud token is being refreshed

If the Cortex API needs to work with the Emotiv Cloud (e.g: API), the app can get this issue when the cloud token is being refreshed. The app should wait until the token is refreshed and try the API call again.

-32135 Cortex token with incorrect application id or version

The Cortex token is valid, however, the app has already authorized with different application credentials or same application but different version. The app needs to call again.

In this case, there is often a bug in your application.

-32137 Cannot open output file

You are trying to a record but Cortex cannot open the output CSV or EDF file to write. Users should check the path or the permissions.

-32138 Stream not supported for export

You are trying to a record but one of the data streams you requested is not available.

-32139 Record is too short to export

When export to EDF file, the record length must be at least one second of data.

-32140 Cannot unsubscribe a data stream

The app can get this error when calling unsubscribe a data stream. Please check if the stream has been subscribed.

-32142 Unpublished application

This app is currently unpublished, so only the person who created it (the owner) can use it. To access unpublished app, they must log in to Emotiv Launcher with the same EmotivID used to create the Cortex App ID and Cortex Client ID.

If the owner of the app wants to share the app with other people, the owner needs to contact to publish the app.

-32146 A record is being reported

We don't allow a record to be exported twice at the same time. You must wait for a record exporting to stop before calling on this record again.

-32147 Record data is corrupted

Record data is corruped and cannot be exported.

-32148 Timestamp of record is incorrect

There is something wrong with start and end time of the record and we cannot find the these timestamps in record data file. In this case, we cannot export the record.

-32151 Cannot run Cortex on this machine

If Cortex cannot read hardware information of the machine, you will get this error when calling API.

-32152 Headset is not ready yet

When a headset is requested to connect, it will take some time for Cortex to establish the connection and getting the first sample. If the app wants to do anything with headset e.g: createSession, subscribe, etc, before that, the app will get this error. In this case, the app needs to wait and retry later.

-32153 Low disk space

The app will get this error when trying to when the free disk space on this machine is critical low. Users will need to create more disk space to continue.

-32154 Invalid headset connection type

The app will get this error when trying to with an expected connection type but the headset is not available via that connection type.

-32155 Opt-out feature is unavailable

The opt-out feature is not available with the current license. You can get this error when calling API. Please contact if you want to have the ability of record uploading opt-out.

-32156 Cannot change Opt-out config

The opt-out feature is available with the current license. However, you cannot change the opt-out option. You can get this error when calling API. Please contact if you want to have the ability of changing opt-out option.

-32157 Cannot change headset mapping

You cannot change the headset mapping of a connected headset.

-32159 Cannot upgrading database

You will not likely get this error. However, if you get it, there must be something wrong with the database. Please contact .

-32160 Record data is corrupted after post-processing

You cannot export the record because when running post-processing, record data is corrupted for some reason. Please contact for this case.

-32161 Record is being post-processing

You cannot export the record because when record's post-processing is in progress. Please wait until it's done.

-32173 The API is not supported for this application/platform/headset

You can get this error if the API is not supported in some cases.

For example, when the app is trying to run facial expression detection on a headset which doesn't support facial expression detection.

-32175 Database is busy

You will get this error when the API call is trying to access to database but the database is busy with other operations. Please wait and try again.

-32176 Cannot change headset config

You can get this error when calling API. Please make sure the headset connection is stable.

-32178 Cannot update headband position

You can get this error when calling API but there is an active recording with this current headset.

-32179 Local time error

You cannot work with headset if your local time is modified and different from actual time. If you got this error, please check the Date Time settings on your machine.

-32182 Multi headset error

On some platforms like iOS, Android, Raspberry Pi, we support only 1 headset at a time. So if the app to the another headset while there is already connected headset, this error will be returned.

-32183 The account has been suspended

If users attempt to login at least 5 times with incorrect user credentials, the account will be suspended for 15 minutes and the app will get this error.

-32186 Record data already exists

When the app calls but record data already exists, no need to download, the app will get this error.

-32188 Invalid authentication code

Only available for the Cortex embedded lib, related API: .

-32189 Expired authentication code

Only available for the Cortex embedded lib, related API: .

-32191 Cannot open database

This error can happen when there is some disk I/O error, e.g: users unplug the disk where Cortex's database is located.

-32192 Cannot encrypt database

Cortex cannot generate encryption key to encrypt database. Please contact for this case.

-32193 Unhandled database error

There are unhandled errors in database. Please contact for this case.

-32198 Re-generating database key

Cortex is trying to re-generating database key. This can happen when we rotate database key. Please wait and try again.

-32200 Cannot access records of other applications

Normally the app can only access the records that have been created by this app, unless it has the license key that record is created with. If the app doesn't have permission to access the record, it will get this error when calling these APIs: , , .

-32206 Headset not supported

The headset is not supported for some feature. e.g: API.

-32225 Forced logout

Cortex log the user out because some critical account availability for example: user has changed their password or user has deleted their account.

-32226 Training profile incompatible with the headset

If the defined EEG channels in the training profile is not the same with the EEG channels of this headset, you will get this error. See API.

-32227 Training profile incompatible with the EMOTIV Flex headset

If the training profile is loaded with EMOTIV Flex headset which doesn't have Epoc-based mapping, you will get this error. See API.

-32228 Readonly training profile

The profile is ready and cannot be trained. Read more at .

-32230 Unsupported headset in license

Emotiv licenses also limits the type of headset for specific data streams, especially 'eeg' or 'met' (see API). If you got this issue, please contact .

-32232 License requires EEG

You will get this error if your app has enabled "Enable EEG for Professional devices" option when creating the app, however, you don't have any valid paid license.

This option should be enabled when you have Professional devices (EPOC, Flex) and want to access Premium data stream (EEG, high-resolution Performance Metrics). Please contact in this case.

Otherwise, please create another Cortex app with new client id and client secret, disable this option then run again.

Cortex API V4

Getting Started

hashtagSystem requirements and supported platforms

hashtagSupported headsets

hashtagVirtual Brainwear

hashtagPrerequisites

hashtagCreate an EmotivID

hashtagLicense

hashtagUnderstanding Cortex API Access Levels

hashtagCreate a Cortex App

hashtagClient ID and Client Secret

hashtagThe Cortex Examples

hashtagNext Step

Connecting to the Cortex API

hashtagWebSocket

hashtagCortex security certificate

hashtagRemote connections

hashtagJSON-RPC

hashtagTest API request and response

hashtagNext step

getCortexInfo

hashtagParameters

hashtagResult

hashtagExample

Overview of API flow

Offline support

hashtagsoftLimitTime

hashtaghardLimitTime

Authentication

getUserLogin

hashtagParameters

hashtagResult

hashtagExamples

hashtagNo user is logged in

hashtagA user is logged in from the current OS account

hashtagA user is logged in from another OS account

requestAccess

hashtagParameters

hashtagResult

hashtagExamples

hashtagApplication was already approved

hashtagApplication is not approved yet, or declined

hasAccessRight

hashtagParameters

hashtagResult

hashtagExamples

authorize

hashtagCortex token

hashtagEULA not accepted warning

hashtagParameters

hashtagResult

hashtagExamples

getUserInformation

hashtagParameters

hashtagResult

hashtagExamples

getLicenseInfo

hashtagParameters

hashtagResult

hashtagExample

Headsets

controlDevice

hashtagParameters

hashtagHeadset Scanning Flow

hashtagEPOC Flex mapping

hashtagSpecial EEG sensor mapping for EPOC Flex

hashtagConnection Type

hashtagResult

hashtagExamples

hashtagRefresh the list of headsets

hashtagConnect an Insight headset

hashtagConnect an Epoc Flex headset

hashtagDisconnect a headset

configMapping

hashtagParameters

hashtagStatus create

hashtagStatus get

hashtagStatus read

hashtagStatus update

hashtagStatus delete

System requirements and supported platforms

Supported headsets

Virtual Brainwear

Prerequisites

Create an EmotivID

License

Understanding Cortex API Access Levels

Create a Cortex App

Client ID and Client Secret

The Cortex Examples

Next Step

WebSocket

Cortex security certificate

Remote connections

JSON-RPC

Test API request and response

Next step

Parameters

Result

Example

softLimitTime

hardLimitTime

Parameters

Result

Examples

No user is logged in

A user is logged in from the current OS account

A user is logged in from another OS account

Parameters

Result

Examples

Application was already approved

Application is not approved yet, or declined

Parameters

Result

Examples

Cortex token

EULA not accepted warning

Parameters

Result

Examples

Parameters

Result

Examples

Parameters

Result

Example

Parameters

Headset Scanning Flow

EPOC Flex mapping

Special EEG sensor mapping for EPOC Flex

Connection Type

Result

Examples

Refresh the list of headsets

Connect an Insight headset

Connect an Epoc Flex headset

Disconnect a headset

Parameters

Status create

Status get

Status read

Status update

Status delete

Parameters

Result

Examples

softLimitTime

hardLimitTime

System requirements and supported platforms

Supported headsets

Virtual Brainwear

Prerequisites

Create an EmotivID

License

Understanding Cortex API Access Levels

Create a Cortex App

Client ID and Client Secret

The Cortex Examples

Next Step