Ingestion service

The ingestion service is used to send new device data to Edge Impulse. It's available on both HTTP and HTTPS endpoints, and requires an API key to authenticate. Data needs to be sent in the Edge Impulse Data Acquisition format, and is optionally signed with an HMAC key. Data with invalid signatures will still show up in the studio, but will be marked as such, and can be excluded from training.

There are three endpoints available:

  • POST /api/training/data - for gathering training data.
  • POST /api/testing/data - for gathering testing data. If you have the 'Live classification' page open in your browser the file will automatically be classified against the current impulse.
  • POST /api/anomaly/data - for anomaly data from deployed devices.

The API is located at:

HTTP

http://ingestion.edgeimpulse.com

HTTPS

https://ingestion.edgeimpulse.com

Header parameters

  • x-api-key - API Key (required).
  • x-file-name - Filename (required, but does not have to be unique).
  • x-label - Label (optional). If this header is not provided a label is automatically infered from the filename through the following regex: ^[a-zA-Z0-9\s-_]+. For example: idle.01 will yield the label idle.
  • x-disallow-duplicates - When set, checks the hash of the message against your current dataset (optional). We'd recommend to set this header, but haven't enabled it by default for backwards compatibility.

Response

All responses are sent with content type text/plain. The following response codes may be returned:

  • 200 - Stored the file, file name is in the body.
  • 400 - Invalid message, e.g. fields are missing, or are invalid. See body for more information.
  • 401 - Missing x-api-key header, or invalid api key.
  • 421 - Missing header, see body for more information.
  • 500 - Internal server error, see body for more information.

Example usage

curl -X POST
    -H "x-api-key: ei_238fae..."
    -H "x-file-name: idle.01"
    -H "x-label: idle"
    -H "content-type: application/cbor"
    -d somefile.cbor
    https://ingestion.edgeimpulse.com/api/training/data
// Install request via: `npm install request`

const request = require('request');
const fs = require('fs');

request.post('https://ingestion.edgeimpulse.com/api/training/data', {
    headers: {
        'x-api-key': 'ei_238fae...',
        'x-file-name': 'idle.01',
        'x-label': 'idle',
        'Content-Type': 'application/cbor'
    },
    body: fs.readFileSync('./somefile.cbor'),
    encoding: 'binary'
}, function (err, response, body) {
    if (err) return console.error('Request failed', err);

    console.log('Uploaded file to Edge Impulse', response.status, body);
});
# Install requests via: `pip3 install requests`

with open('somefile.cbor', 'r') as file:
    res = requests.post(url='https://ingestion.edgeimpulse.com/api/training/data',
                        data=file,
                        headers={
                            'Content-Type': 'application/cbor',
                            'x-file-name': 'idle.01',
                            'x-label': 'idle',
                            'x-api-key': API_KEY
                        })

    if (res.status_code == 200):
        print('Uploaded file to Edge Impulse', res.status_code, res.content)
    else:
        print('Failed to upload file to Edge Impulse', res.status_code, res.content)

Multipart requests

You can also send binary files to the ingestion service through a multipart request. This is currently only supported for image data in JPG format. In this request you'll need to add two fields that describe the header, and the actual file.

  • Field name: attachments[], content type: application/json or application/cbor, file name: metadata.json or metadata.cbor, file content: a file following the Data acquisition format in either JSON or CBOR.
  • Field name: attachments[], content type: image/jpg, file name: free form, but it needs to end with .jpg, file content: a JPG file.

Here's an example of how to construct this request using cURL:

curl -X POST \
    -H "x-api-key: ei_..." \
    -H "x-file-name: mark.jpg" \
    -H "x-label: mark" \
    https://ingestion.edgeimpulse.com/api/training/data \
    -F attachments[]="@metadata.json;type=application/json" \
    -F attachments[]="@mark.jpg;type=image/jpeg"

An end-to-end example is here: example-ingestion-jpg.

Certificate authority

On embedded devices use the following certificate authority (CA) to communicate with the HTTPS API:

-----BEGIN CERTIFICATE-----
MIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/
MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT
DkRTVCBSb290IENBIFgzMB4XDTE2MDMxNzE2NDA0NloXDTIxMDMxNzE2NDA0Nlow
SjELMAkGA1UEBhMCVVMxFjAUBgNVBAoTDUxldCdzIEVuY3J5cHQxIzAhBgNVBAMT
GkxldCdzIEVuY3J5cHQgQXV0aG9yaXR5IFgzMIIBIjANBgkqhkiG9w0BAQEFAAOC
AQ8AMIIBCgKCAQEAnNMM8FrlLke3cl03g7NoYzDq1zUmGSXhvb418XCSL7e4S0EF
q6meNQhY7LEqxGiHC6PjdeTm86dicbp5gWAf15Gan/PQeGdxyGkOlZHP/uaZ6WA8
SMx+yk13EiSdRxta67nsHjcAHJyse6cF6s5K671B5TaYucv9bTyWaN8jKkKQDIZ0
Z8h/pZq4UmEUEz9l6YKHy9v6Dlb2honzhT+Xhq+w3Brvaw2VFn3EK6BlspkENnWA
a6xK8xuQSXgvopZPKiAlKQTGdMDQMc2PMTiVFrqoM7hD8bEfwzB/onkxEz0tNvjj
/PIzark5McWvxI0NHWQWM6r6hCm21AvA2H3DkwIDAQABo4IBfTCCAXkwEgYDVR0T
AQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwfwYIKwYBBQUHAQEEczBxMDIG
CCsGAQUFBzABhiZodHRwOi8vaXNyZy50cnVzdGlkLm9jc3AuaWRlbnRydXN0LmNv
bTA7BggrBgEFBQcwAoYvaHR0cDovL2FwcHMuaWRlbnRydXN0LmNvbS9yb290cy9k
c3Ryb290Y2F4My5wN2MwHwYDVR0jBBgwFoAUxKexpHsscfrb4UuQdf/EFWCFiRAw
VAYDVR0gBE0wSzAIBgZngQwBAgEwPwYLKwYBBAGC3xMBAQEwMDAuBggrBgEFBQcC
ARYiaHR0cDovL2Nwcy5yb290LXgxLmxldHNlbmNyeXB0Lm9yZzA8BgNVHR8ENTAz
MDGgL6AthitodHRwOi8vY3JsLmlkZW50cnVzdC5jb20vRFNUUk9PVENBWDNDUkwu
Y3JsMB0GA1UdDgQWBBSoSmpjBH3duubRObemRWXv86jsoTANBgkqhkiG9w0BAQsF
AAOCAQEA3TPXEfNjWDjdGBX7CVW+dla5cEilaUcne8IkCJLxWh9KEik3JHRRHGJo
uM2VcGfl96S8TihRzZvoroed6ti6WqEBmtzw3Wodatg+VyOeph4EYpr/1wXKtx8/
wApIvJSwtmVi4MFU5aMqrSDE6ea73Mj2tcMyo5jMd6jmeWUHK8so/joWUoHOUgwu
X4Po1QYz+3dszkDqMp4fklxBwXRsW10KXzPMTZ+sOPAveyxindmjkW8lGy+QsRlG
PfZ+G6Z6h7mjem0Y+iWlkYcV4PIWL1iwBi8saCbGS5jN2p8M+X+Q7UNKEkROb3N6
KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg==
-----END CERTIFICATE-----