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
1
http://ingestion.edgeimpulse.com
Copied!
HTTPS
1
https://ingestion.edgeimpulse.com
Copied!

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 inferred 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
Node.js
Python
1
curl -X POST
2
-H "x-api-key: ei_238fae..."
3
-H "x-file-name: idle.01"
4
-H "x-label: idle"
5
-H "content-type: application/cbor"
6
-d somefile.cbor
7
https://ingestion.edgeimpulse.com/api/training/data
Copied!
1
// Install request via: `npm install request`
2
3
const request = require('request');
4
const fs = require('fs');
5
6
request.post('https://ingestion.edgeimpulse.com/api/training/data', {
7
headers: {
8
'x-api-key': 'ei_238fae...',
9
'x-file-name': 'idle.01',
10
'x-label': 'idle',
11
'Content-Type': 'application/cbor'
12
},
13
body: fs.readFileSync('./somefile.cbor'),
14
encoding: 'binary'
15
}, function (err, response, body) {
16
if (err) return console.error('Request failed', err);
17
18
console.log('Uploaded file to Edge Impulse', response.status, body);
19
});av
Copied!
1
# Install requests via: `pip3 install requests`
2
3
with open('somefile.cbor', 'r') as file:
4
res = requests.post(url='https://ingestion.edgeimpulse.com/api/training/data',
5
data=file,
6
headers={
7
'Content-Type': 'application/cbor',
8
'x-file-name': 'idle.01',
9
'x-label': 'idle',
10
'x-api-key': API_KEY
11
})
12
13
if (res.status_code == 200):
14
print('Uploaded file to Edge Impulse', res.status_code, res.content)
15
else:
16
print('Failed to upload file to Edge Impulse', res.status_code, res.content)
Copied!

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:
1
curl -X POST \
2
-H "x-api-key: ei_..." \
3
-H "x-file-name: mark.jpg" \
4
-H "x-label: mark" \
5
https://ingestion.edgeimpulse.com/api/training/data \
6
-F attachments[]="@metadata.json;type=application/json" \
7
-F attachments[]="@mark.jpg;type=image/jpeg"
Copied!
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:
1
-----BEGIN CERTIFICATE-----
2
MIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/
3
MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT
4
DkRTVCBSb290IENBIFgzMB4XDTE2MDMxNzE2NDA0NloXDTIxMDMxNzE2NDA0Nlow
5
SjELMAkGA1UEBhMCVVMxFjAUBgNVBAoTDUxldCdzIEVuY3J5cHQxIzAhBgNVBAMT
6
GkxldCdzIEVuY3J5cHQgQXV0aG9yaXR5IFgzMIIBIjANBgkqhkiG9w0BAQEFAAOC
7
AQ8AMIIBCgKCAQEAnNMM8FrlLke3cl03g7NoYzDq1zUmGSXhvb418XCSL7e4S0EF
8
q6meNQhY7LEqxGiHC6PjdeTm86dicbp5gWAf15Gan/PQeGdxyGkOlZHP/uaZ6WA8
9
SMx+yk13EiSdRxta67nsHjcAHJyse6cF6s5K671B5TaYucv9bTyWaN8jKkKQDIZ0
10
Z8h/pZq4UmEUEz9l6YKHy9v6Dlb2honzhT+Xhq+w3Brvaw2VFn3EK6BlspkENnWA
11
a6xK8xuQSXgvopZPKiAlKQTGdMDQMc2PMTiVFrqoM7hD8bEfwzB/onkxEz0tNvjj
12
/PIzark5McWvxI0NHWQWM6r6hCm21AvA2H3DkwIDAQABo4IBfTCCAXkwEgYDVR0T
13
AQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwfwYIKwYBBQUHAQEEczBxMDIG
14
CCsGAQUFBzABhiZodHRwOi8vaXNyZy50cnVzdGlkLm9jc3AuaWRlbnRydXN0LmNv
15
bTA7BggrBgEFBQcwAoYvaHR0cDovL2FwcHMuaWRlbnRydXN0LmNvbS9yb290cy9k
16
c3Ryb290Y2F4My5wN2MwHwYDVR0jBBgwFoAUxKexpHsscfrb4UuQdf/EFWCFiRAw
17
VAYDVR0gBE0wSzAIBgZngQwBAgEwPwYLKwYBBAGC3xMBAQEwMDAuBggrBgEFBQcC
18
ARYiaHR0cDovL2Nwcy5yb290LXgxLmxldHNlbmNyeXB0Lm9yZzA8BgNVHR8ENTAz
19
MDGgL6AthitodHRwOi8vY3JsLmlkZW50cnVzdC5jb20vRFNUUk9PVENBWDNDUkwu
20
Y3JsMB0GA1UdDgQWBBSoSmpjBH3duubRObemRWXv86jsoTANBgkqhkiG9w0BAQsF
21
AAOCAQEA3TPXEfNjWDjdGBX7CVW+dla5cEilaUcne8IkCJLxWh9KEik3JHRRHGJo
22
uM2VcGfl96S8TihRzZvoroed6ti6WqEBmtzw3Wodatg+VyOeph4EYpr/1wXKtx8/
23
wApIvJSwtmVi4MFU5aMqrSDE6ea73Mj2tcMyo5jMd6jmeWUHK8so/joWUoHOUgwu
24
X4Po1QYz+3dszkDqMp4fklxBwXRsW10KXzPMTZ+sOPAveyxindmjkW8lGy+QsRlG
25
PfZ+G6Z6h7mjem0Y+iWlkYcV4PIWL1iwBi8saCbGS5jN2p8M+X+Q7UNKEkROb3N6
26
KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg==
27
-----END CERTIFICATE-----
Copied!