frAPI API Documentation
API Endpoint
http://localhost/frapiThis documentation provides a simple and easy way to learn about our API and to integrate it with your application using both our web and REST interfaces. We believe that the web interface is the best way to start, since it will show how our system works in a more natural and friendly way. And when the integration time comes, rest assured that all the funcionalities from the web interface are available through our REST interface.
Of course, we’re assuming that you have a valid license activated in your system; if that’s not the case and you want a free trial, contact us at sales@meerkat.com.br.
Geting Started
There are two straightforward ways to test our API. The first is by using Postman. Just download our collection, import it on Postman and start playing around. You will find examples for our most common features such as adding and playing different types of video streams, detecting and recognizing faces and more.
Authentication
Basically, the API’s authentication is performed through your app key. You must
include it on every request headers. You app key is a 64-character string and should
be included in a header field called app_key
. There are some consideration on
this, depending on the system’s deploy. In either case, your key will be shown
on the top right of the web interface.
- On-premise: If you are running the system on premise, once you activate your license a key is automatically generated for you. Also, if you did not create additional keys, i.e. you have a single app key, you do not need to provided in your requests. The system will take this single key as default for all operations.
- Cloud service: Obtain your trial key in our website following
the registration procedure. Then, login in to the web interface and find your
APP_KEY
displayed on the top right of the webpage. Alternatively, you can request yourAPP_KEY
through the/user/<username>
endpoint.
Testing API calls
There are two straightforward ways to test our API. The first is by using [Postman] (https://www.getpostman.com/). Just import our collection on it and start playing around. The second one is by using the code snippets bellow in your favorite programming language.
Support
If you need help, send us an e-mail at support@meerkat.com.br or use the support webapp page.
Version ¶
Check API version ¶
Returns the current API version. It can also be used to check the API status.
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Body
{
"version": "1.0",
"source_commit": "c71266d",
"model_type": "default"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"version": {
"type": "string",
"description": "API version"
},
"source_commit": {
"type": "string",
"description": "Hash of the build version"
},
"model_type": {
"type": "string",
"description": "The recognition model in use"
}
},
"required": [
"version",
"source_commit",
"model_type"
]
}
Get system current versionGET/version
Activation ¶
Once you get your on-premise version of frAPI, you need to activate it online to start using it. If you access the webapp and the API is not activated you’ll be redirected to an activation page. You can also activate or check your license status using the REST API, as described below.
Note: all routes with the exception of /version
and /activate
will return 404 until the API is
activated with your license key. Also, you need internet access to activate the API.
Activate or check your activation ¶
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Body
{
"is_activated": true,
"license": {
"expiration_date": "21/10/2015",
"key": "12abc345..."
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"is_activated": {
"type": "boolean",
"description": "Value indicating if your system is activated or not"
},
"license": {
"type": "object",
"properties": {
"expiration_date": {
"type": "string"
},
"key": {
"type": "string"
}
},
"required": [
"expiration_date",
"key"
],
"additionalProperties": false
}
},
"required": [
"is_activated",
"license"
]
}
Check license statusGET/activation
Checks if your system is activated.
Headers
Content-Type: application/json
Body
{
"key": "61683eb9642326ebc458efe5d7414e21"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Your license key"
}
}
}
Your key provided as argument is invalid or something went wrong during activation
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Activate your licensePOST/activation
Activates the API with your license key. After a minute or two, all the other routes will be available to be used. Please note that the license key is different from the app_key.
App key ¶
This key must be included in the header of every API call. If you are running the system on premise and have a single app key, it can be omitted (a default app key will be used).
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Body
{
"app_key": "abcdeabcde"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"app_key": {
"type": "string",
"description": "Your app key"
}
},
"required": [
"app_key"
]
}
Retrieve your default app keyGET/app_keys/default
Retrieve the default app_key if the system is running on premise and a single app_key exists.
Enroll ¶
Enroll with images ¶
In order for frAPI to be able to recognize people you first must enroll them. This is done with our enroll routes.
Besides providing an image URL or its base64 content, you must provide a label that uniquely identifies the person. We recommend choosing an alphanumeric sequence. If you choose to include non-alphanumeric characters, you must encode the label when making requests that include the person’s label on the URL.
Headers
Content-Type: application/json
Body
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg",
"label": "name"
}
Headers
Content-Type: application/json
Body
{
"person_faces": {
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"thumb_image_url": "'/frapi/images/image",
"original_image_url": "'/frapi/images/image",
"person_label": "'Nelson'",
"creation_date": "'2018",
"detected_face": {
"bottom_right": {
"x": 1387,
"y": 1766
},
"top_left": {
"x": 983,
"y": 241
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"person_faces": {
"type": "object",
"properties": {
"face_id": {
"type": "string",
"description": "id of the face."
},
"thumb_image_url": {
"type": "string",
"description": "071e69a2-5d90-4a50.jpg' (string) - url of the thumbnail image."
},
"original_image_url": {
"type": "string",
"description": "acb4c5b6-2cfb.png' (string) - url of the original image."
},
"person_label": {
"type": "string",
"description": "label that uniquely identifies a person."
},
"creation_date": {
"type": "string",
"description": "12-04T18:12:18.360970' (string) - date of face creation."
},
"detected_face": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the bottom right face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the bottom right face bounding box."
}
}
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the top left face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the top left face bounding box."
}
}
}
}
}
}
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
No face found on the image or image could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Enroll person using image URLPOST/faces
Adds a person to the database using an image URL.
IMPORTANT: Enrolling new people will consume the people quota. Once the people limit has been reached you must delete all faces from a subject before adding a new person. There is no limit to the number of faces for each person in the DB.
Headers
Content-Type: application/json
Body
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA...",
"label": "name"
}
Headers
Content-Type: application/json
Body
{
"person_faces": {
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"thumb_image_url": "'/frapi/images/image",
"original_image_url": "'/frapi/images/image",
"person_label": "'Nelson'",
"creation_date": "'2018",
"detected_face": {
"bottom_right": {
"x": 1387,
"y": 1766
},
"top_left": {
"x": 983,
"y": 241
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"person_faces": {
"type": "object",
"properties": {
"face_id": {
"type": "string",
"description": "id of the face."
},
"thumb_image_url": {
"type": "string",
"description": "071e69a2-5d90-4a50.jpg' (string) - url of the thumbnail image."
},
"original_image_url": {
"type": "string",
"description": "acb4c5b6-2cfb.png' (string) - url of the original image."
},
"person_label": {
"type": "string",
"description": "label that uniquely identifies a person."
},
"creation_date": {
"type": "string",
"description": "12-04T18:12:18.360970' (string) - date of face creation."
},
"detected_face": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the bottom right face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the bottom right face bounding box."
}
}
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the top left face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the top left face bounding box."
}
}
}
}
}
},
"description": "<!--- person ( PersonWithFaceIds )-->"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
No face found on the image or image could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Enroll person using string base64 JPEGPOST/faces
IMPORTANT: Enrolling new people will consume the people quota. Once the people limit has been reached you must delete all faces from a subject before adding a new person. There is no limit to the number of faces for each person in the DB.
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEY
Body
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
data
--BOUNDARY--
Headers
Content-Type: application/json
Body
{
"person_faces": {
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"thumb_image_url": "'/frapi/images/image",
"original_image_url": "'/frapi/images/image",
"person_label": "'Nelson'",
"creation_date": "'2018",
"detected_face": {
"bottom_right": {
"x": 1387,
"y": 1766
},
"top_left": {
"x": 983,
"y": 241
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"person_faces": {
"type": "object",
"properties": {
"face_id": {
"type": "string",
"description": "id of the face."
},
"thumb_image_url": {
"type": "string",
"description": "071e69a2-5d90-4a50.jpg' (string) - url of the thumbnail image."
},
"original_image_url": {
"type": "string",
"description": "acb4c5b6-2cfb.png' (string) - url of the original image."
},
"person_label": {
"type": "string",
"description": "label that uniquely identifies a person."
},
"creation_date": {
"type": "string",
"description": "12-04T18:12:18.360970' (string) - date of face creation."
},
"detected_face": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the bottom right face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the bottom right face bounding box."
}
}
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the top left face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the top left face bounding box."
}
}
}
}
}
},
"description": "<!--- person ( PersonWithFaceIds )-->"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
No face found on the image or image could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Enroll person using multipart form-dataPOST/faces
IMPORTANT: Enrolling new people will consume the people quota. Once the people limit has been reached you must delete all faces from a subject before adding a new person. There is no limit to the number of faces for each person in the DB.
Enroll through events ¶
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"label": "Nelson",
"events": [
0,
6
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "Person name"
},
"events": {
"type": "array",
"description": "list of recognition event IDs that will be added to this person"
}
},
"required": [
"label"
]
}
Headers
Content-Type: application/json
Body
{
"person_faces": [
{
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"thumb_image_url": "'/frapi/images/image",
"original_image_url": "'/frapi/images/image",
"person_label": "'Nelson'",
"creation_date": "'2018",
"detected_face": {
"bottom_right": {
"x": 1387,
"y": 1766
},
"top_left": {
"x": 983,
"y": 241
}
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"person_faces": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
No face found on the image or image could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Enroll person using recognition eventsPOST/faces/from_events
Adds faces to the database using recognition events from the stream. You need to pass a list of event IDs in the field events
and the person label in
which to enroll in label
.
IMPORTANT: Enrolling new people will consume the people quota. Once the people limit has been reached you must delete all faces from a subject before adding a new person. There is no limit to the number of faces for each person in the DB.
People ¶
People ¶
After people are enrolled on the system, you can manage them using the following routes. Each person is enrolled using one or more face images, that can also be listed and deleted individually.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"people": [
{
"additional_info": "Employee",
"avatar_url": "/frapi/images/image-c8e73fd32eb9449dbe69b3c7b16c264a.jpg",
"creation_date": "Wed, 21 Nov 2018 16:03:29 GMT",
"person_label": "Mario"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"people": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
List peopleGET/people
Returns the list of all people. Filtering options are as follows:
-
page
: page number if results are to be paginated. -
per_page
: number of items per page to return, if paginated. -
like_person_label
: search for a portion of the label name. -
order_by
: field to order by it. Default it’s the event date. -
order_asc
: select if you want ascending (asc
) or descending order (desc
- default).
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"faces": [
{
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"thumb_image_url": "'/frapi/images/image",
"original_image_url": "'/frapi/images/image",
"person_label": "'Nelson'",
"creation_date": "'2018",
"detected_face": {
"bottom_right": {
"x": 1387,
"y": 1766
},
"top_left": {
"x": 983,
"y": 241
}
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"faces": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
List facesGET/faces
Returns the list of all faces. Configuration can be performed using the following query parameters:
-
page
: page number if results are to be paginated. -
per_page
: number of items per page to return, if paginated. -
like_person_label
: search for a portion of the label name. -
order_by
: field to order by it. Default it’s the event date. -
order_asc
: select if you want ascending (asc
) or descending order (desc
- default).
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"person": {
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"thumb_image_url": "'/frapi/images/image",
"original_image_url": "'/frapi/images/image",
"person_label": "'Nelson'",
"creation_date": "'2018",
"detected_face": {
"bottom_right": {
"x": 1387,
"y": 1766
},
"top_left": {
"x": 983,
"y": 241
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"person": {
"type": "object",
"properties": {
"face_id": {
"type": "string",
"description": "id of the face."
},
"thumb_image_url": {
"type": "string",
"description": "071e69a2-5d90-4a50.jpg' (string) - url of the thumbnail image."
},
"original_image_url": {
"type": "string",
"description": "acb4c5b6-2cfb.png' (string) - url of the original image."
},
"person_label": {
"type": "string",
"description": "label that uniquely identifies a person."
},
"creation_date": {
"type": "string",
"description": "12-04T18:12:18.360970' (string) - date of face creation."
},
"detected_face": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the bottom right face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the bottom right face bounding box."
}
}
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the top left face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the top left face bounding box."
}
}
}
}
}
}
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Person with the given label not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Get person informationGET/people/{person_label}
Returns the information of a given person. Also returns all its face_ids.
- person_label
string
(required) Example: mandela
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"person_face": {
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"thumb_image_url": "'/frapi/images/image",
"original_image_url": "'/frapi/images/image",
"person_label": "'Nelson'",
"creation_date": "'2018",
"detected_face": {
"bottom_right": {
"x": 1387,
"y": 1766
},
"top_left": {
"x": 983,
"y": 241
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"person_face": {
"type": "object",
"properties": {
"face_id": {
"type": "string",
"description": "id of the face."
},
"thumb_image_url": {
"type": "string",
"description": "071e69a2-5d90-4a50.jpg' (string) - url of the thumbnail image."
},
"original_image_url": {
"type": "string",
"description": "acb4c5b6-2cfb.png' (string) - url of the original image."
},
"person_label": {
"type": "string",
"description": "label that uniquely identifies a person."
},
"creation_date": {
"type": "string",
"description": "12-04T18:12:18.360970' (string) - date of face creation."
},
"detected_face": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the bottom right face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the bottom right face bounding box."
}
}
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number",
"description": "X coordinate of the top left face bounding box."
},
"y": {
"type": "number",
"description": "Y coordinate of the top left face bounding box."
}
}
}
}
}
}
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Face with the given id not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Get face informationGET/faces/{face_id}
Returns the information of a given face.
- face_id
string
(required) Example: abc
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Person with the given label not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Removes an enrolled personDELETE/people/{person_label}
Fully removes a person from the API.
IMPORTANT: Removing a person from the DB will free the people quota, allowing a new person ot be enrolled.
- person_label
string
(required) Example: mandela
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Face with the given id not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Removes a face from an enrolled personDELETE/faces/{face_id}
Removes one of the enrolled face images of a person. If it is the last face, the person will also be deleted.
IMPORTANT: Removing all faces of person from the DB will free the people quota, allowing a new person ot be enrolled.
- face_id
string
(required) Example: abc
Detection ¶
Face detection bounding boxes ¶
Detects faces in an image, returning their bounding boxes.
Headers
Content-Type: application/json
Body
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg"
}
Headers
Content-Type: application/json
Body
{
"detections": [
{
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detections": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Face detection using image URLPOST/detection/faces
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: application/json
Body
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA..."
}
Headers
Content-Type: application/json
Body
{
"detections": [
{
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detections": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Face detection using string base64 JPEGPOST/detection/faces
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEY
Body
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
data
--BOUNDARY--
Headers
Content-Type: application/json
Body
{
"detections": [
{
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"detections": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Face detection using multipart form-dataPOST/detection/faces
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Face detection landmarks ¶
Detects faces in an image, returning their landmarks.
Headers
Content-Type: application/json
Body
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg"
}
Headers
Content-Type: application/json
Body
{
"landmarks": [
{
"x": 0,
"y": 0
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"landmarks": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Face landmarks using image URLPOST/detection/landmarks
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: application/json
Body
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA..."
}
Headers
Content-Type: application/json
Body
{
"landmarks": [
{
"x": 0,
"y": 0
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"landmarks": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Face landmarks using string base64 JPEGPOST/detection/landmarks
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEY
Body
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
data
--BOUNDARY--
Headers
Content-Type: application/json
Body
{
"landmarks": [
{
"x": 0,
"y": 0
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"landmarks": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Face landmarks using multipart form-dataPOST/detection/landmarks
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Recognition ¶
Face recognition ¶
After you have enrolled people you can send images so that frAPI can recognize them. You will have a confidence associated with each recognition, so notice that values that are too low (around 30%) are most likely an unknown person.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg",
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageUrl": {
"type": "string"
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageUrl"
]
}
Headers
Content-Type: application/json
Body
{
"people": [
{
"detection": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"recognition": {
"confidence": 0,
"predicted_label": "name"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"people": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image Recognition using image URLPOST/recognition
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA...",
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageB64": {
"type": "string"
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageB64"
]
}
Headers
Content-Type: application/json
Body
{
"people": [
{
"detection": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"recognition": {
"confidence": 0,
"predicted_label": "name"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"people": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image Recognition using string base64 JPEGPOST/recognition
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: multipart/form-data; boundary=--{boundary value}
app_key: YOUR_APP_KEY
Body
--{boundary value}
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
{file content}
--{boundary value}--
Headers
Content-Type: application/json
Body
{
"people": [
{
"detection": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"recognition": {
"confidence": 0,
"predicted_label": "name"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"people": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image Recognition using multipart form-dataPOST/recognition
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Face recognition Top N ¶
Just as with /recognition route, you can perform face recognition using images. The difference with this route is that it returns a list of possible recognition candidates ordered by the recognition confidence.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg",
"n": 5,
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageUrl": {
"type": "string",
"description": "Image Url to run recognition."
},
"n": {
"type": "number",
"description": "Number of top-n candidates returned.",
"default": 5
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageUrl"
]
}
Headers
Content-Type: application/json
Body
{
"people": [
{
"detection": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"top_n_recognitions": [
{
"confidence": 0,
"predicted_label": "name"
}
],
"recognition": {
"confidence": 0,
"predicted_label": "name"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"people": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image Top N Recognition using image URLPOST/recognition/top_n
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA...",
"n": 5,
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageB64": {
"type": "string",
"description": "The image to run a recognition encoded as Base64 string."
},
"n": {
"type": "number",
"description": "Number of top-n candidates returned.",
"default": 5
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageB64"
]
}
Headers
Content-Type: application/json
Body
{
"people": [
{
"detection": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"top_n_recognitions": [
{
"confidence": 0,
"predicted_label": "name"
}
],
"recognition": {
"confidence": 0,
"predicted_label": "name"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"people": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image Top N Recognition using string base64 JPEGPOST/recognition/top_n
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: multipart/form-data; boundary=--{boundary value}
app_key: YOUR_APP_KEY
Body
--{boundary value}
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
{file content}
--{boundary value}
Content-Disposition: form-data; name="n"
3
--{boundary value}--
Headers
Content-Type: application/json
Body
{
"people": [
{
"detection": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"recognition": {
"confidence": 0,
"predicted_label": "name"
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"people": {
"type": "array"
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image Top N Recognition using multipart form-dataPOST/recognition/top_n
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Verification ¶
With the verification routes you can check if either two pictures are from the same person or if a picture is from a given user that is already enrolled.
Note that, in the case of multiple faces on the image, the largest will be used.
Verification with two images ¶
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
This verification route receives two images and says if they are indeed the same person.
Headers
Content-Type: application/json
Body
{
"imageUrl1": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg",
"imageUrl2": "https://upload.wikimedia.org/wikipedia/commons/3/3c/Mandela_1991.jpg",
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageUrl1": {
"type": "string"
},
"imageUrl2": {
"type": "string"
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageUrl1",
"imageUrl2"
]
}
Headers
Content-Type: application/json
Body
{
"verification": {
"same_person": true,
"confidence": 50,
"detection_1": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"detection_2": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification": {
"type": "object",
"properties": {
"same_person": {
"type": "boolean"
},
"confidence": {
"type": "number"
},
"detection_1": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
},
"detection_2": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
}
},
"required": [
"same_person",
"confidence",
"detection_1",
"detection_2"
],
"additionalProperties": false
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Verification people using images URLPOST/verification
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: application/json
Body
{
"imageB641": "/9j/4RiDRXhpZgAATU0AKgA...",
"imageB642": "/9j/4RiDRXhpZgAATU0AKgA...",
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageB641": {
"type": "string"
},
"imageB642": {
"type": "string"
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageB641",
"imageB642"
]
}
Headers
Content-Type: application/json
Body
{
"verification": {
"same_person": true,
"confidence": 50,
"detection_1": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"detection_2": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification": {
"type": "object",
"properties": {
"same_person": {
"type": "boolean"
},
"confidence": {
"type": "number"
},
"detection_1": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
},
"detection_2": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
}
},
"required": [
"same_person",
"confidence",
"detection_1",
"detection_2"
],
"additionalProperties": false
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Verification people using string base64 JPEGPOST/verification
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEY
Body
--BOUNDARY
Content-Disposition: form-data; name="image1"; filename="filename1.jpg"
Content-Type: image/jpeg
data1
--BOUNDARY--
Content-Disposition: form-data; name="image2"; filename="filename2.jpg"
Content-Type: image/jpeg
data2
--BOUNDARY--
Headers
Content-Type: application/json
Body
{
"verification": {
"same_person": true,
"confidence": 50,
"detection_1": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"detection_2": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification": {
"type": "object",
"properties": {
"same_person": {
"type": "boolean"
},
"confidence": {
"type": "number"
},
"detection_1": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
},
"detection_2": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
}
},
"required": [
"same_person",
"confidence",
"detection_1",
"detection_2"
],
"additionalProperties": false
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Verification people using multipart form-dataPOST/verification
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Verification of an image with an enrolled person ¶
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
This verification route receives an image and a label of an enrolled person, and says if this picture is indeed of this person.
Headers
Content-Type: application/json
Body
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/3/3c/Mandela_1991.jpg",
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageUrl": {
"type": "string"
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageUrl"
]
}
Headers
Content-Type: application/json
Body
{
"verification": {
"same_person": true,
"confidence": 50,
"detection": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification": {
"type": "object",
"properties": {
"same_person": {
"type": "boolean"
},
"confidence": {
"type": "number"
},
"detection": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
}
},
"required": [
"same_person",
"confidence",
"detection"
],
"additionalProperties": false
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Person with the given label not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Verification using image URLPOST/verification/{person_label}
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
- person_label
string
(required) Example: mandela
Headers
Content-Type: application/json
Body
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA...",
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageB64": {
"type": "string"
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageB64"
]
}
Headers
Content-Type: application/json
Body
{
"verification": {
"same_person": true,
"confidence": 50,
"detection": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification": {
"type": "object",
"properties": {
"same_person": {
"type": "boolean"
},
"confidence": {
"type": "number"
},
"detection": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
}
},
"required": [
"same_person",
"confidence",
"detection"
],
"additionalProperties": false
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Person with the given label not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Verification using string base64 JPEGPOST/verification/{person_label}
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
- person_label
string
(required) Example: mandela
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEY
Body
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
data
--BOUNDARY--
Headers
Content-Type: application/json
Body
{
"verification": {
"same_person": true,
"confidence": 50,
"detection": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification": {
"type": "object",
"properties": {
"same_person": {
"type": "boolean"
},
"confidence": {
"type": "number"
},
"detection": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
}
},
"required": [
"same_person",
"confidence",
"detection"
],
"additionalProperties": false
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Person with the given label not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Verification using multipart form-dataPOST/verification/{person_label}
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
- person_label
string
(required) Example: mandela
Verification of an image with a person holding it's ID ¶
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
This verification route receives an image of a person holding it’s ID with picture. The route will detect both the document picture and the person and verify that they are indeed the same.
Headers
Content-Type: application/json
Body
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/3/3c/Mandela_1991.jpg",
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageUrl": {
"type": "string"
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageUrl"
]
}
Headers
Content-Type: application/json
Body
{
"verification": {
"same_person": true,
"confidence": 50,
"detection_1": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"detection_2": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification": {
"type": "object",
"properties": {
"same_person": {
"type": "boolean"
},
"confidence": {
"type": "number"
},
"detection_1": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
},
"detection_2": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
}
},
"required": [
"same_person",
"confidence",
"detection_1",
"detection_2"
],
"additionalProperties": false
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Person with the given label not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Doc Verification using image URLPOST/doc_verification
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: application/json
Body
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA...",
"support_rotation": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"imageB64": {
"type": "string"
},
"support_rotation": {
"type": "boolean",
"description": "Rotates the image within 90 degrees intervals to detect rotated faces.",
"default": false
}
},
"required": [
"imageB64"
]
}
Headers
Content-Type: application/json
Body
{
"verification": {
"same_person": true,
"confidence": 50,
"detection_1": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"detection_2": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification": {
"type": "object",
"properties": {
"same_person": {
"type": "boolean"
},
"confidence": {
"type": "number"
},
"detection_1": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
},
"detection_2": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
}
},
"required": [
"same_person",
"confidence",
"detection_1",
"detection_2"
],
"additionalProperties": false
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Person with the given label not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Doc Verification using string base64 JPEGPOST/doc_verification
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEY
Body
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
data
--BOUNDARY--
Headers
Content-Type: application/json
Body
{
"verification": {
"same_person": true,
"confidence": 50,
"detection_1": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"detection_2": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"verification": {
"type": "object",
"properties": {
"same_person": {
"type": "boolean"
},
"confidence": {
"type": "number"
},
"detection_1": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
},
"detection_2": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false
}
},
"required": [
"same_person",
"confidence",
"detection_1",
"detection_2"
],
"additionalProperties": false
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Person with the given label not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Image provided could not be read
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Doc Verification using multipart form-dataPOST/doc_verification
IMPORTANT: Calling this route will consume API calls from your account current quota cycle.
Stream ¶
The core vision algorithms can run at real-time in streams, which usually correspond to videos or IP cameras.
Stream configuration ¶
To configure a stream you basically have to provide the following info:
-
algo_type
: The type of algorithm that you want to process on that stream. Options are detection, recognition or enroll. -
stream_label
: a name for the stream. We recommend ASCII characters to avoid url encoding problems. -
stream_type
: if its a video or a an IP camera. Options are video and ip_camera. -
multi_threading
: enables multi threading stream processing. Only enable this option if you plan to have only 1 stream running, otherwise the overall performance of the system will drop. -
stream_mode
: sets the stream mode. It can be FAST_STREAM for regular streams, SLOW_STREAM for streams running below 5fps or SCENE_STREAM for streams that contain cuts. -
path
: the location url of the stream. If IP camera, you need to arrange the URL given the local IP address and a suffix which varies from each camera model – a good guide to find you URL can be found here. For the video, you can use the upload on the web interface, or put your video in/var/lib/meerkat/user_data/video/<your_app_key>/
and pass the/user_data/video/<your_app_key>/YOUR_VIDEO.avi
in this field. -
you can pass a set of options that you can latter change for your stream:
resize
: this tell the algorithm which is the expected size of a plate or face in pixels. Larger values will not detect small plates or faces, but it will improve performance.rotation
: an angle to rotate the frames coming from the stream. Positive values rotate counter clockwise and negative values rotate clockwise.roi
: this option defines a region of interest (ROI) on the camera. You need to pass the top-left and bottom-right coordinates for it.video_skip_frame
: how many video frames will be skipped between each recognition (only work for video type).0
is the default value which process all frames. You can increase this value to speed-up the stream processing.max_FPS
: when higher than 0, sets an upper bound for the stream processing rate. You can set this value to control the amount of computational recourses used by each stream.follow_stream_rate
: works for video streams only. If set, discards frames whenever the stream processing rate is slower than the video FPS. You can set this option to simulate the behavior of an IP camera stream.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"algo_type": "detection",
"path": "stream.mp4",
"stream_label": "test",
"stream_type": "video",
"detector_size": 130,
"rotation": -2,
"start_on_restart": false,
"always_on": true,
"multi_threading": false,
"stream_mode: `FAST_STREAM`": "Hello, world!",
"roi": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"video_skip_frame": 30,
"max_FPS": 0,
"follow_stream_rate": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"algo_type": {
"type": "string",
"enum": [
"detection",
"recognition"
],
"description": "Type of the algorithm to run on the stream"
},
"path": {
"type": "string",
"description": "URL of the stream"
},
"stream_label": {
"type": "string",
"description": "Name of stream"
},
"stream_type": {
"type": "string",
"enum": [
"video",
"ip_camera"
],
"description": "The type ot the stream"
},
"detector_size": {
"type": "number",
"description": "minimum expected size of object"
},
"rotation": {
"type": "number",
"description": "camera angle rotation in degrees"
},
"start_on_restart": {
"type": "boolean",
"description": "indicates if the stream should start no the API startup."
},
"always_on": {
"type": "boolean",
"description": "keeps trying to reconnect if the stream suddenly stops."
},
"multi_threading": {
"type": "boolean",
"description": "enables mutlti threading processing. Only enable this if there will be only one stream running."
},
"stream_mode: `FAST_STREAM`": {
"type": "string"
},
"roi": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false,
"description": "bounding box of the region of interest"
},
"video_skip_frame": {
"type": "number",
"description": "step between frames, only works for videos."
},
"max_FPS": {
"type": "number",
"description": "maximum stream processing rate"
},
"follow_stream_rate": {
"type": "boolean",
"description": "whether to discard frames when processing is too slow"
}
},
"required": [
"algo_type",
"path",
"stream_label",
"stream_type",
"detector_size",
"rotation",
"start_on_restart",
"always_on",
"multi_threading",
"stream_mode: `FAST_STREAM`",
"roi",
"video_skip_frame",
"max_FPS",
"follow_stream_rate"
],
"additionalProperties": false
}
Body
{
"stream": {
"algo_type": "detection",
"path": "/user_data/video/<YOUR_APP_KEY>/video.mp4",
"stream_label": "test",
"id": 7,
"stream_type": "video",
"detector_size": 130,
"rotation": -2,
"start_on_restart": false,
"always_on": true,
"multi_threading": false,
"stream_mode: `FAST_STREAM`": "Hello, world!",
"roi": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"video_skip_frame": 30,
"max_FPS": 0,
"follow_stream_rate": false,
"status": {
"fps": 23.2,
"status": "STOPPED",
"description": ""
}
}
}
Schema
{
"type": "object",
"properties": {
"stream": {
"type": "object",
"properties": {
"algo_type": {
"enum": [
"detection",
"recognition"
],
"description": "Type of the algorithm to run on the stream"
},
"path": {
"type": "string"
},
"stream_label": {
"type": "string"
},
"id": {
"type": "number"
},
"stream_type": {
"enum": [
"video",
"ip_camera"
],
"description": "The type ot the stream"
},
"detector_size": {
"type": "number",
"description": "minimum expected size of object"
},
"rotation": {
"type": "number",
"description": "camera angle rotation in degrees"
},
"start_on_restart": {
"type": "boolean",
"description": "indicates if the stream should start no the API startup."
},
"always_on": {
"type": "boolean",
"description": "keeps trying to reconnect if the stream suddenly stops."
},
"multi_threading": {
"type": "boolean",
"description": "enables mutlti threading processing. Only enable this if there will be only one stream running."
},
"stream_mode: `FAST_STREAM`": {
"type": "string"
},
"roi": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
}
}
},
"description": "bounding box of the region of interest"
},
"video_skip_frame": {
"type": "number",
"description": "step between frames, only works for videos."
},
"max_FPS": {
"type": "number",
"description": "maximum stream processing rate"
},
"follow_stream_rate": {
"type": "boolean",
"description": "whether to discard frames when processing is too slow"
},
"status": {
"type": "object",
"properties": {
"fps": {
"type": "number",
"description": "Framerate of the stream if its running"
},
"status": {
"enum": [
"STOPPED",
"STARTING",
"ERROR"
],
"description": "The stream status"
},
"description": {
"type": "string",
"description": "error description when status is ERROR, can be ignored otherwise."
}
},
"description": "the current status of the stream"
}
},
"description": "Object that describes a configured stream"
}
},
"required": [
"stream"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Invalid parameters to create a stream. Check the message on payload to see what happened.
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Adding a streamPOST/streams
Add a stream to the system to process recognition.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"stream": {
"algo_type": "detection",
"path": "/user_data/video/<YOUR_APP_KEY>/video.mp4",
"stream_label": "test",
"id": 7,
"stream_type": "video",
"detector_size": 130,
"rotation": -2,
"start_on_restart": false,
"always_on": true,
"multi_threading": false,
"stream_mode: `FAST_STREAM`": "Hello, world!",
"roi": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"video_skip_frame": 30,
"max_FPS": 0,
"follow_stream_rate": false,
"status": {
"fps": 23.2,
"status": "STOPPED",
"description": ""
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"stream": {
"type": "object",
"properties": {
"algo_type": {
"type": "string",
"enum": [
"detection",
"recognition"
],
"description": "Type of the algorithm to run on the stream"
},
"path": {
"type": "string"
},
"stream_label": {
"type": "string"
},
"id": {
"type": "number"
},
"stream_type": {
"type": "string",
"enum": [
"video",
"ip_camera"
],
"description": "The type ot the stream"
},
"detector_size": {
"type": "number",
"description": "minimum expected size of object"
},
"rotation": {
"type": "number",
"description": "camera angle rotation in degrees"
},
"start_on_restart": {
"type": "boolean",
"description": "indicates if the stream should start no the API startup."
},
"always_on": {
"type": "boolean",
"description": "keeps trying to reconnect if the stream suddenly stops."
},
"multi_threading": {
"type": "boolean",
"description": "enables mutlti threading processing. Only enable this if there will be only one stream running."
},
"stream_mode: `FAST_STREAM`": {
"type": "string"
},
"roi": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false,
"description": "bounding box of the region of interest"
},
"video_skip_frame": {
"type": "number",
"description": "step between frames, only works for videos."
},
"max_FPS": {
"type": "number",
"description": "maximum stream processing rate"
},
"follow_stream_rate": {
"type": "boolean",
"description": "whether to discard frames when processing is too slow"
},
"status": {
"type": "object",
"properties": {
"fps": {
"type": "number",
"description": "Framerate of the stream if its running"
},
"status": {
"type": "string",
"enum": [
"STOPPED",
"STARTING",
"ERROR"
],
"description": "The stream status"
},
"description": {
"type": "string",
"description": "error description when status is ERROR, can be ignored otherwise."
}
},
"required": [
"status",
"description"
],
"additionalProperties": false,
"description": "the current status of the stream"
}
},
"required": [
"algo_type",
"path",
"stream_label",
"id",
"stream_type",
"detector_size",
"rotation",
"start_on_restart",
"always_on",
"multi_threading",
"stream_mode: `FAST_STREAM`",
"roi",
"video_skip_frame",
"max_FPS",
"follow_stream_rate",
"status"
],
"additionalProperties": false
}
},
"required": [
"stream"
]
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
stream with the provided id not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Get a specific streamGET/streams/{stream_id}
Returns a json with the specified stream parameters.
- stream_id
number
(required) Example: 1Stream identifier
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"algo_type": "detection",
"path": "stream.mp4",
"stream_label": "test",
"stream_type": "video",
"detector_size": 130,
"rotation": -2,
"start_on_restart": false,
"always_on": true,
"multi_threading": false,
"stream_mode: `FAST_STREAM`": "Hello, world!",
"roi": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"video_skip_frame": 30,
"max_FPS": 0,
"follow_stream_rate": false
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"algo_type": {
"type": "string",
"enum": [
"detection",
"recognition"
],
"description": "Type of the algorithm to run on the stream"
},
"path": {
"type": "string",
"description": "URL of the stream"
},
"stream_label": {
"type": "string",
"description": "Name of stream"
},
"stream_type": {
"type": "string",
"enum": [
"video",
"ip_camera"
],
"description": "The type ot the stream"
},
"detector_size": {
"type": "number",
"description": "minimum expected size of object"
},
"rotation": {
"type": "number",
"description": "camera angle rotation in degrees"
},
"start_on_restart": {
"type": "boolean",
"description": "indicates if the stream should start no the API startup."
},
"always_on": {
"type": "boolean",
"description": "keeps trying to reconnect if the stream suddenly stops."
},
"multi_threading": {
"type": "boolean",
"description": "enables mutlti threading processing. Only enable this if there will be only one stream running."
},
"stream_mode: `FAST_STREAM`": {
"type": "string"
},
"roi": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false,
"description": "bounding box of the region of interest"
},
"video_skip_frame": {
"type": "number",
"description": "step between frames, only works for videos."
},
"max_FPS": {
"type": "number",
"description": "maximum stream processing rate"
},
"follow_stream_rate": {
"type": "boolean",
"description": "whether to discard frames when processing is too slow"
}
},
"required": [
"algo_type",
"path",
"stream_label",
"stream_type",
"detector_size",
"rotation",
"start_on_restart",
"always_on",
"multi_threading",
"stream_mode: `FAST_STREAM`",
"roi",
"video_skip_frame",
"max_FPS",
"follow_stream_rate"
],
"additionalProperties": false
}
Headers
Content-Type: application/json
Body
{
"stream": {
"algo_type": "detection",
"path": "/user_data/video/<YOUR_APP_KEY>/video.mp4",
"stream_label": "test",
"id": 7,
"stream_type": "video",
"detector_size": 130,
"rotation": -2,
"start_on_restart": false,
"always_on": true,
"multi_threading": false,
"stream_mode: `FAST_STREAM`": "Hello, world!",
"roi": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"video_skip_frame": 30,
"max_FPS": 0,
"follow_stream_rate": false,
"status": {
"fps": 23.2,
"status": "STOPPED",
"description": ""
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"stream": {
"type": "object",
"properties": {
"algo_type": {
"type": "string",
"enum": [
"detection",
"recognition"
],
"description": "Type of the algorithm to run on the stream"
},
"path": {
"type": "string"
},
"stream_label": {
"type": "string"
},
"id": {
"type": "number"
},
"stream_type": {
"type": "string",
"enum": [
"video",
"ip_camera"
],
"description": "The type ot the stream"
},
"detector_size": {
"type": "number",
"description": "minimum expected size of object"
},
"rotation": {
"type": "number",
"description": "camera angle rotation in degrees"
},
"start_on_restart": {
"type": "boolean",
"description": "indicates if the stream should start no the API startup."
},
"always_on": {
"type": "boolean",
"description": "keeps trying to reconnect if the stream suddenly stops."
},
"multi_threading": {
"type": "boolean",
"description": "enables mutlti threading processing. Only enable this if there will be only one stream running."
},
"stream_mode: `FAST_STREAM`": {
"type": "string"
},
"roi": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false,
"description": "bounding box of the region of interest"
},
"video_skip_frame": {
"type": "number",
"description": "step between frames, only works for videos."
},
"max_FPS": {
"type": "number",
"description": "maximum stream processing rate"
},
"follow_stream_rate": {
"type": "boolean",
"description": "whether to discard frames when processing is too slow"
},
"status": {
"type": "object",
"properties": {
"fps": {
"type": "number",
"description": "Framerate of the stream if its running"
},
"status": {
"type": "string",
"enum": [
"STOPPED",
"STARTING",
"ERROR"
],
"description": "The stream status"
},
"description": {
"type": "string",
"description": "error description when status is ERROR, can be ignored otherwise."
}
},
"required": [
"status",
"description"
],
"additionalProperties": false,
"description": "the current status of the stream"
}
},
"required": [
"algo_type",
"path",
"stream_label",
"id",
"stream_type",
"detector_size",
"rotation",
"start_on_restart",
"always_on",
"multi_threading",
"stream_mode: `FAST_STREAM`",
"roi",
"video_skip_frame",
"max_FPS",
"follow_stream_rate",
"status"
],
"additionalProperties": false
}
},
"required": [
"stream"
]
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
stream with the provided id not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Edit a streamPATCH/streams/{stream_id}
Edit the parameters of the stream. You can include a subset of parameters that you want to modify. For the options, you can change a single value and the system will merge it with the old values, if not overwritten.
- stream_id
number
(required) Example: 1Stream identifier
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"streams": [
{
"algo_type": "detection",
"path": "/user_data/video/<YOUR_APP_KEY>/video.mp4",
"stream_label": "test",
"id": 7,
"stream_type": "video",
"detector_size": 130,
"rotation": -2,
"start_on_restart": false,
"always_on": true,
"multi_threading": false,
"stream_mode: `FAST_STREAM`": "Hello, world!",
"roi": {
"bottom_right": {
"x": 0,
"y": 0
},
"top_left": {
"x": 0,
"y": 0
}
},
"video_skip_frame": 30,
"max_FPS": 0,
"follow_stream_rate": false,
"status": {
"fps": 23.2,
"status": "STOPPED",
"description": ""
}
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"streams": {
"type": "array",
"items": {
"type": "object",
"properties": {
"algo_type": {
"type": "string",
"enum": [
"detection",
"recognition"
],
"description": "Type of the algorithm to run on the stream"
},
"path": {
"type": "string"
},
"stream_label": {
"type": "string"
},
"id": {
"type": "number"
},
"stream_type": {
"type": "string",
"enum": [
"video",
"ip_camera"
],
"description": "The type ot the stream"
},
"detector_size": {
"type": "number",
"description": "minimum expected size of object"
},
"rotation": {
"type": "number",
"description": "camera angle rotation in degrees"
},
"start_on_restart": {
"type": "boolean",
"description": "indicates if the stream should start no the API startup."
},
"always_on": {
"type": "boolean",
"description": "keeps trying to reconnect if the stream suddenly stops."
},
"multi_threading": {
"type": "boolean",
"description": "enables mutlti threading processing. Only enable this if there will be only one stream running."
},
"stream_mode: `FAST_STREAM`": {
"type": "string"
},
"roi": {
"type": "object",
"properties": {
"bottom_right": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
},
"top_left": {
"type": "object",
"properties": {
"x": {
"type": "number"
},
"y": {
"type": "number"
}
},
"required": [
"x",
"y"
],
"additionalProperties": false
}
},
"required": [
"bottom_right",
"top_left"
],
"additionalProperties": false,
"description": "bounding box of the region of interest"
},
"video_skip_frame": {
"type": "number",
"description": "step between frames, only works for videos."
},
"max_FPS": {
"type": "number",
"description": "maximum stream processing rate"
},
"follow_stream_rate": {
"type": "boolean",
"description": "whether to discard frames when processing is too slow"
},
"status": {
"type": "object",
"properties": {
"fps": {
"type": "number",
"description": "Framerate of the stream if its running"
},
"status": {
"type": "string",
"enum": [
"STOPPED",
"STARTING",
"ERROR"
],
"description": "The stream status"
},
"description": {
"type": "string",
"description": "error description when status is ERROR, can be ignored otherwise."
}
},
"required": [
"status",
"description"
],
"additionalProperties": false,
"description": "the current status of the stream"
}
},
"required": [
"algo_type",
"path",
"stream_label",
"id",
"stream_type",
"detector_size",
"rotation",
"start_on_restart",
"always_on",
"multi_threading",
"stream_mode: `FAST_STREAM`",
"roi",
"video_skip_frame",
"max_FPS",
"follow_stream_rate",
"status"
],
"additionalProperties": false
}
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
List all streamsGET/streams
Returns the list of all streams.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Stream with the provided id not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Start running a streamGET/streams/{stream_id}/run
Start running the stream. Notice that a 200 status code here will only mean that the system will attempt to run the stream. If an error happens on opening the stream (such as an invalid camera path), the system will change the stream status to ERROR.
IMPORTANT: Running streams uses your account quota of stream processing, counted in minutes (rounded up). If multiple streams are running at the same time, both will will add to the processing time used in the current quota cycle. Note that the stream minutes quota considers the processing time not the actual recording time of the stream.
- stream_id
number
(required) Example: 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Stream with the provided id not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Stop a running streamGET/streams/{stream_id}/stop
Tells the system to stop the stream. Since it’s running on an specific process it may take a couple of seconds for the stream status to change to STOPPED.
- stream_id
number
(required) Example: 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"status": {
"fps": 23.2,
"status": "STOPPED",
"description": ""
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "object",
"properties": {
"fps": {
"type": "number",
"description": "Framerate of the stream if its running"
},
"status": {
"type": "string",
"enum": [
"STOPPED",
"STARTING",
"ERROR"
],
"description": "The stream status"
},
"description": {
"type": "string",
"description": "error description when status is ERROR, can be ignored otherwise."
}
},
"required": [
"status",
"description"
],
"additionalProperties": false
}
},
"required": [
"status"
]
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Stream with the provided id not found
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Get the status of a streamGET/streams/{stream_id}/status
Get the status of a stream - it should be one of four values: STOPPED, STARTING, RUNNING or ERROR. If the stream is running it will also provide you the frames per second (FPS).
- stream_id
number
(required) Example: 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Removing a streamDELETE/streams/{stream_id}
Remove the stream using the stream_id.
- stream_id
number
(required) Example: 1Stream identifier
Admin ¶
The routes under this resource are the user setting preferences. It gives you options to control how you can receive the output of a running stream, set your detector to be more or less sensitive, etc.
Stream output options ¶
These options concern how you can capture the output of a running stream, that’s it, receive the system recognitions. You have two main options for that, saving results in a JSON file or receiving HTTP posts with the recognitions.
The following parameters are available:
-
save_json
: set totrue
if you want to save JSON files with the stream results. -
make_http_requests
: set totrue
if you want to receive HTTP requests with stream results. -
uras_min_face_quality
: Advanced Option controls the minimum face quality to track and do recognition. -
uras_min_good_faces
: Advanced Option minimum number of good faces to do a person recognition. -
uras_tracklet_merge_threshold
: Advanced Option minimum face similarity to join two distinct face tracklets. -
make_video_output
: set totrue
if you want to write the video output to a file -
video_options
max_video_mins
: the maximum video duration in minutesinclude_date_in_video
: set totrue
to include date on the video
-
min_confidence
: the minimum confidence value such as an output is created. Use this value to exclude from processing recognitions in which the system is not sure about. -
Should you choose to use JSON files, you can provide
json_options
as follows:batch_window
: how many recognitions to group before creating a new JSON filesfoldername
: name of the folder to save JSON files. One for all streams
-
Alternatively, if want to use HTTP posts, you must provide these
http_options
:output_server_url
: the URL to perform a post. Never put localhost urls since the whole system runs inside a Docker container, use the network IP instead.include_image_in_request
: the option to include an image on the request as well. The image will be encoded in jpeg base64 string.
-
When storing stream results locally, you must provide
video_options
:max_video_mins
: maximum size (in minutes) of each stored video file. If a stream runs long enough, the results will be stored in multiple videos.include_date_in_video
: set totrue
if you want the stream date to be printed on the video as well.make_raw_video_output
: set totrue
if you want to store the raw stream (without any results drawings) as well.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"stream_output_config": {
"save_json": false,
"make_http_requests": true,
"make_video_output": true,
"uras_min_face_quality": 0.75,
"uras_min_good_faces": 5,
"uras_tracklet_merge_threshold": 0.7,
"video_options": {
"max_video_mins": 10,
"include_date_in_video": true,
"make_raw_video_output": false
},
"min_confidence": 30,
"json_options": {
"batch_window": 10,
"foldername": "out_json"
},
"http_options": {
"output_server_url": "http://somereachableurl:323/post_route",
"include_image_in_request": true
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"stream_output_config": {
"type": "object",
"properties": {
"save_json": {
"type": "boolean",
"description": "Save or not JSON"
},
"make_http_requests": {
"type": "boolean",
"description": "Receive HTTP posts"
},
"make_video_output": {
"type": "boolean",
"description": "Write video to file"
},
"uras_min_face_quality": {
"type": "number",
"description": "Minimum face quality for recognition"
},
"uras_min_good_faces": {
"type": "number",
"description": "Minimum number of good faces to perform a recognition"
},
"uras_tracklet_merge_threshold": {
"type": "number",
"description": "Minimum face similarity between face tracklets to merge them"
},
"video_options": {
"type": "object",
"properties": {
"max_video_mins": {
"type": "number",
"description": "maximum video duration in minutes"
},
"include_date_in_video": {
"type": "boolean",
"description": "include date on the video output"
},
"make_raw_video_output": {
"type": "boolean",
"description": "to store the raw stream as a separate video"
}
}
},
"min_confidence": {
"type": "number",
"description": "minimum confidence value to accept"
},
"json_options": {
"type": "object",
"properties": {
"batch_window": {
"type": "number",
"description": "number of frames to group"
},
"foldername": {
"type": "string",
"description": "folder where to keep JSON files"
}
}
},
"http_options": {
"type": "object",
"properties": {
"output_server_url": {
"type": "string",
"description": "URL for webhook"
},
"include_image_in_request": {
"type": "boolean",
"description": "to include or not the image on the POST payload"
}
}
}
},
"required": [
"save_json",
"make_http_requests",
"make_video_output",
"uras_min_face_quality",
"uras_min_good_faces",
"uras_tracklet_merge_threshold",
"video_options",
"min_confidence",
"json_options",
"http_options"
],
"additionalProperties": false
}
},
"required": [
"stream_output_config"
]
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Wrong or missing input arguments
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Getting optionsGET/admin/stream/output
Get the current stream output options.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"save_json": false,
"make_http_requests": true,
"make_video_output": true,
"uras_min_face_quality": 0.75,
"uras_min_good_faces": 5,
"uras_tracklet_merge_threshold": 0.7,
"video_options": {
"max_video_mins": 10,
"include_date_in_video": true,
"make_raw_video_output": false
},
"min_confidence": 30,
"json_options": {
"batch_window": 10,
"foldername": "out_json"
},
"http_options": {
"output_server_url": "http://somereachableurl:323/post_route",
"include_image_in_request": true
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"save_json": {
"type": "boolean",
"description": "Save or not JSON"
},
"make_http_requests": {
"type": "boolean",
"description": "Receive HTTP posts"
},
"make_video_output": {
"type": "boolean",
"description": "Write video to file"
},
"uras_min_face_quality": {
"type": "number",
"description": "Minimum face quality for recognition"
},
"uras_min_good_faces": {
"type": "number",
"description": "Minimum number of good faces to perform a recognition"
},
"uras_tracklet_merge_threshold": {
"type": "number",
"description": "Minimum face similarity between face tracklets to merge them"
},
"video_options": {
"type": "object",
"properties": {
"max_video_mins": {
"type": "number",
"description": "maximum video duration in minutes"
},
"include_date_in_video": {
"type": "boolean",
"description": "include date on the video output"
},
"make_raw_video_output": {
"type": "boolean",
"description": "to store the raw stream as a separate video"
}
}
},
"min_confidence": {
"type": "number",
"description": "minimum confidence value to accept"
},
"json_options": {
"type": "object",
"properties": {
"batch_window": {
"type": "number",
"description": "number of frames to group"
},
"foldername": {
"type": "string",
"description": "folder where to keep JSON files"
}
}
},
"http_options": {
"type": "object",
"properties": {
"output_server_url": {
"type": "string",
"description": "URL for webhook"
},
"include_image_in_request": {
"type": "boolean",
"description": "to include or not the image on the POST payload"
}
}
}
},
"required": [
"save_json",
"make_http_requests",
"make_video_output",
"uras_min_face_quality",
"uras_min_good_faces",
"uras_tracklet_merge_threshold",
"video_options",
"min_confidence",
"json_options",
"http_options"
],
"additionalProperties": false
}
Headers
Content-Type: application/json
Body
{
"stream_output_config": {
"save_json": false,
"make_http_requests": true,
"make_video_output": true,
"uras_min_face_quality": 0.75,
"uras_min_good_faces": 5,
"uras_tracklet_merge_threshold": 0.7,
"video_options": {
"max_video_mins": 10,
"include_date_in_video": true,
"make_raw_video_output": false
},
"min_confidence": 30,
"json_options": {
"batch_window": 10,
"foldername": "out_json"
},
"http_options": {
"output_server_url": "http://somereachableurl:323/post_route",
"include_image_in_request": true
}
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"stream_output_config": {
"type": "object",
"properties": {
"save_json": {
"type": "boolean",
"description": "Save or not JSON"
},
"make_http_requests": {
"type": "boolean",
"description": "Receive HTTP posts"
},
"make_video_output": {
"type": "boolean",
"description": "Write video to file"
},
"uras_min_face_quality": {
"type": "number",
"description": "Minimum face quality for recognition"
},
"uras_min_good_faces": {
"type": "number",
"description": "Minimum number of good faces to perform a recognition"
},
"uras_tracklet_merge_threshold": {
"type": "number",
"description": "Minimum face similarity between face tracklets to merge them"
},
"video_options": {
"type": "object",
"properties": {
"max_video_mins": {
"type": "number",
"description": "maximum video duration in minutes"
},
"include_date_in_video": {
"type": "boolean",
"description": "include date on the video output"
},
"make_raw_video_output": {
"type": "boolean",
"description": "to store the raw stream as a separate video"
}
}
},
"min_confidence": {
"type": "number",
"description": "minimum confidence value to accept"
},
"json_options": {
"type": "object",
"properties": {
"batch_window": {
"type": "number",
"description": "number of frames to group"
},
"foldername": {
"type": "string",
"description": "folder where to keep JSON files"
}
}
},
"http_options": {
"type": "object",
"properties": {
"output_server_url": {
"type": "string",
"description": "URL for webhook"
},
"include_image_in_request": {
"type": "boolean",
"description": "to include or not the image on the POST payload"
}
}
}
},
"required": [
"save_json",
"make_http_requests",
"make_video_output",
"uras_min_face_quality",
"uras_min_good_faces",
"uras_tracklet_merge_threshold",
"video_options",
"min_confidence",
"json_options",
"http_options"
],
"additionalProperties": false
}
},
"required": [
"stream_output_config"
]
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Invalid parameters. Check the message on payload to see what happened.
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Setting optionsPOST/admin/stream/output
Sets the options that you want for output. You won’t need to restart streams for changes to take place.
Event generation options ¶
The event generation from streams has a few options that can be changed according to your integration needs. The following are available:
-
unique_win_seconds
: number of seconds in which the same recognition for the same stream will not be repeated. Default is 5*60. -
webhook_active
: if you want that a new event generates a POST to an webhook. If you want to use webhooks, you need to provide two more values:webhook_url
: the URL for the webhook.webhook_auth_type
: Authentication type (empty or “bearer”).webhook_auth_info
: Authentication info (value used for authentication with the webhook).post_image
: if you want to post the event image as well.
-
auto_clear
: whether the system will attempt a daily automatic events clear. -
max_age
: if automatically cleaning events, this number states how many days an event is allowed to stay persisted.
Note: Contrasting with the HTTP output for streams /admin/stream/output
the event webhook is intended to be called once each recognition and the stream output is a more raw output of the results with multiple requests per seconds.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"event_settings": {
"unique_win_seconds": 360,
"webhook_active": true,
"webhook_url": "http://somereachableurl:323/event_getter",
"post_image": true,
"include_unknowns": true,
"auto_clear": true,
"max_age": 90
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"event_settings": {
"type": "object",
"properties": {
"unique_win_seconds": {
"type": "number",
"description": "Number of seconds in which the event will not be repeated. Default is 5*60."
},
"webhook_active": {
"type": "boolean",
"description": "If a new event will generate a POST to an webhook."
},
"webhook_url": {
"type": "string",
"description": "URL for the webhook."
},
"post_image": {
"type": "boolean",
"description": "If you want to post the event image as well."
},
"include_unknowns": {
"type": "boolean",
"description": "If you want to post the event image as well."
},
"auto_clear": {
"type": "boolean",
"description": "If you want old events to be cleared automatically."
},
"max_age": {
"type": "number",
"description": "Threshold for automatic events clear."
}
},
"required": [
"unique_win_seconds",
"webhook_active",
"webhook_url",
"post_image",
"include_unknowns",
"auto_clear",
"max_age"
],
"additionalProperties": false
}
},
"required": [
"event_settings"
]
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Getting event optionsGET/admin/event/settings
Get the current options.
Headers
Content-Type: application/json
Body
{
"unique_win_seconds": 360,
"webhook_active": true,
"webhook_url": "http://somereachableurl:323/event_getter",
"post_image": true,
"include_unknowns": true,
"auto_clear": true,
"max_age": 90
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"unique_win_seconds": {
"type": "number",
"description": "Number of seconds in which the event will not be repeated. Default is 5*60."
},
"webhook_active": {
"type": "boolean",
"description": "If a new event will generate a POST to an webhook."
},
"webhook_url": {
"type": "string",
"description": "URL for the webhook."
},
"post_image": {
"type": "boolean",
"description": "If you want to post the event image as well."
},
"include_unknowns": {
"type": "boolean",
"description": "If you want to post the event image as well."
},
"auto_clear": {
"type": "boolean",
"description": "If you want old events to be cleared automatically."
},
"max_age": {
"type": "number",
"description": "Threshold for automatic events clear."
}
},
"required": [
"unique_win_seconds",
"webhook_active",
"webhook_url",
"post_image",
"include_unknowns",
"auto_clear",
"max_age"
],
"additionalProperties": false
}
Body
{
"event_settings": {
"unique_win_seconds": 360,
"webhook_active": true,
"webhook_url": "http://somereachableurl:323/event_getter",
"post_image": true,
"include_unknowns": true,
"auto_clear": true,
"max_age": 90
}
}
Schema
{
"type": "object",
"properties": {
"event_settings": {
"type": "object",
"properties": {
"unique_win_seconds": {
"type": "number",
"description": "Number of seconds in which the event will not be repeated. Default is 5*60."
},
"webhook_active": {
"type": "boolean",
"description": "If a new event will generate a POST to an webhook."
},
"webhook_url": {
"type": "string",
"description": "URL for the webhook."
},
"post_image": {
"type": "boolean",
"description": "If you want to post the event image as well."
},
"include_unknowns": {
"type": "boolean",
"description": "If you want to post the event image as well."
},
"auto_clear": {
"type": "boolean",
"description": "If you want old events to be cleared automatically."
},
"max_age": {
"type": "number",
"description": "Threshold for automatic events clear."
}
}
}
},
"required": [
"event_settings"
],
"$schema": "http://json-schema.org/draft-04/schema#"
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Invalid parameters. Check the message on payload to see what happened.
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Setting event optionsPOST/admin/event/settings
Sets the options that you want for events.
Events ¶
Events are generate automatically when processing streams - they are basically the logs of what our algorithm has recognize it. They provide some information that can be used for querying. As we saw above, you can also implement a webhook to receive the events when they are begin generated.
Each event have the following values:
-
stream_label
: label of the stream that generated the event. -
stream_id
: identifier of the stream that generated the event. -
event_label
: the label of recognition. It can be a plate OCR, or a person’s name, for instance. -
date
: the date when the event was created. -
confidence
: the confidence percentage related to the recognition. -
thumbnail_url
: the sufix of the URL to get the event thumbnail image. -
image_url
: the suffix of the frame’s URL when the event first appeared. -
details
: the recognition details, such as detected bounding boxes, of the image.
Querying events ¶
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"event": {
"id": 23,
"stream_id": 3,
"stream_label": "camera1",
"event_label": "Ernesto",
"type": "TypeA",
"date": "2018-10-02T00:53:24.955850Z",
"confidence": 90.32,
"thumbnail_url": "/images/image-cd323658-7077-4117-9dc3-055ab377f795.jpg",
"image_url": "/images/image-b11f2b59-bce1-4fbf-8a95-9e07fc3b2f29",
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"details": "{...}"
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"event": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "the event ID."
},
"stream_id": {
"type": "number",
"description": "ID of the stream that generated the event."
},
"stream_label": {
"type": "string",
"description": "label of the stream that generated the event."
},
"event_label": {
"type": "string",
"description": "label of recognition. Ex.: license plate no, a person's name."
},
"type": {
"type": "string",
"description": "type related to the event. Ex.: plate type, a unknown/known person."
},
"date": {
"type": "string",
"description": "date when the event was created."
},
"confidence": {
"type": "number",
"description": "confidence percentage related to the recognition."
},
"thumbnail_url": {
"type": "string",
"description": "suffix of the URL to get the event thumbnail image."
},
"image_url": {
"type": "string",
"description": "suffix of the frame's URL when the event first appeared."
},
"face_id": {
"type": "string",
"description": "ID of a dace, if this event has been enrolled to a person"
},
"details": {
"type": "string",
"description": "(object) the recognition details, such as detected bounding boxes."
}
},
"required": [
"id",
"stream_id",
"stream_label",
"event_label",
"type",
"date",
"confidence",
"thumbnail_url",
"image_url",
"face_id",
"details"
],
"additionalProperties": false
}
}
}
Headers
Content-Type: application/json
Body
Invalid event id
Headers
Content-Type: application/json
Body
No APIKey present or unauthorized
Get a specific eventGET/event/{event_id}
Fetches a single event from the database.
- event_id
number
(required) Example: 1Event identifier
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Body
Invalid event id
Headers
Content-Type: application/json
Body
No APIKey present or unauthorized
Delete a specific eventDELETE/event/{event_id}
Deletes a single event from the system, without recovery.
- event_id
number
(required) Example: 1Event identifier
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"last_events": [
{
"id": 23,
"stream_id": 3,
"stream_label": "camera1",
"event_label": "Ernesto",
"type": "TypeA",
"date": "2018-10-02T00:53:24.955850Z",
"confidence": 90.32,
"thumbnail_url": "/images/image-cd323658-7077-4117-9dc3-055ab377f795.jpg",
"image_url": "/images/image-b11f2b59-bce1-4fbf-8a95-9e07fc3b2f29",
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"details": "{...}"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"last_events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "the event ID."
},
"stream_id": {
"type": "number",
"description": "ID of the stream that generated the event."
},
"stream_label": {
"type": "string",
"description": "label of the stream that generated the event."
},
"event_label": {
"type": "string",
"description": "label of recognition. Ex.: license plate no, a person's name."
},
"type": {
"type": "string",
"description": "type related to the event. Ex.: plate type, a unknown/known person."
},
"date": {
"type": "string",
"description": "date when the event was created."
},
"confidence": {
"type": "number",
"description": "confidence percentage related to the recognition."
},
"thumbnail_url": {
"type": "string",
"description": "suffix of the URL to get the event thumbnail image."
},
"image_url": {
"type": "string",
"description": "suffix of the frame's URL when the event first appeared."
},
"face_id": {
"type": "string",
"description": "ID of a dace, if this event has been enrolled to a person"
},
"details": {
"type": "string",
"description": "(object) the recognition details, such as detected bounding boxes."
}
},
"required": [
"id",
"stream_id",
"stream_label",
"event_label",
"type",
"date",
"confidence",
"thumbnail_url",
"image_url",
"face_id",
"details"
],
"additionalProperties": false
}
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Invalid parameters. Check the message on payload to see what happened.
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Getting the last eventsGET/events/last{?n_events}
Get the last stored events from the system.
- n_events
number
(required) Example: 10Last events to return.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"events": [
{
"id": 23,
"stream_id": 3,
"stream_label": "camera1",
"event_label": "Ernesto",
"type": "TypeA",
"date": "2018-10-02T00:53:24.955850Z",
"confidence": 90.32,
"thumbnail_url": "/images/image-cd323658-7077-4117-9dc3-055ab377f795.jpg",
"image_url": "/images/image-b11f2b59-bce1-4fbf-8a95-9e07fc3b2f29",
"face_id": "'f69853aad8abc8d7943950e2f5e1b76e'",
"details": "{...}"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "the event ID."
},
"stream_id": {
"type": "number",
"description": "ID of the stream that generated the event."
},
"stream_label": {
"type": "string",
"description": "label of the stream that generated the event."
},
"event_label": {
"type": "string",
"description": "label of recognition. Ex.: license plate no, a person's name."
},
"type": {
"type": "string",
"description": "type related to the event. Ex.: plate type, a unknown/known person."
},
"date": {
"type": "string",
"description": "date when the event was created."
},
"confidence": {
"type": "number",
"description": "confidence percentage related to the recognition."
},
"thumbnail_url": {
"type": "string",
"description": "suffix of the URL to get the event thumbnail image."
},
"image_url": {
"type": "string",
"description": "suffix of the frame's URL when the event first appeared."
},
"face_id": {
"type": "string",
"description": "ID of a dace, if this event has been enrolled to a person"
},
"details": {
"type": "string",
"description": "(object) the recognition details, such as detected bounding boxes."
}
},
"required": [
"id",
"stream_id",
"stream_label",
"event_label",
"type",
"date",
"confidence",
"thumbnail_url",
"image_url",
"face_id",
"details"
],
"additionalProperties": false
}
}
}
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Invalid parameters. Check the message on payload to see what happened.
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Filtering events with paginationGET/events{?page,per_page,like_event_label,type,stream_id,start_date,end_date,order_by,order_asc}
Filter the events, with pagination (required). You need to provide page
(page number) and per_page
(page size) values. Filtering options are as follow:
-
like_event_label
: search for a portion of the label name. -
type
: string to filter events of this type (exact). -
stream_id
: specify the events of a single stream. -
Specify a date range using
start_date
andend_date
. Expect ISO format strings. -
order_by
: field to order by it. Default it’s the event date. -
order_asc
: select if you want ascending (asc
) or descending order (desc
- default).
- page
number
(required) Example: 1page number
- per_page
number
(required) Example: 10page length
- like_event_label
string
(optional) Example: Ernestsearch for a portion of the label name.
- type
string
(optional) Example: TypeAfilter events of this type (exact).
- stream_id
number
(optional) Example: 1which stream has generate the event.
- start_date
string
(optional) Example: 2018-10-01T00:22:00.000000ZISO format start date for event.
- end_date
string
(optional) Example: 2018-10-02T00:22:00.000000ZISO format end date for event.
- order_by
string
(optional) Example: confidencefield to order by it. Default: event date.
- order_asc
string
(optional) Example: descascending (asc) or descending (desc) order.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"like_event_label": "Ernest",
"type": "TypeA",
"stream_id": 1,
"start_date": "2018-10-01T00:22:00.000000Z",
"end_date": "2018-10-02T00:22:00.000000Z",
"order_by": "confidence",
"order_asc": "desc",
"limit": 5000
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"like_event_label": {
"type": "string",
"description": "search for a portion of the label name."
},
"type": {
"type": "string",
"description": "filter events of this type (exact)."
},
"stream_id": {
"type": "number",
"description": "which stream has generate the event."
},
"start_date": {
"type": "string",
"description": "ISO format start date for event."
},
"end_date": {
"type": "string",
"description": "ISO format end date for event."
},
"order_by": {
"type": "string",
"description": "field to order by it. Default: event date."
},
"order_asc": {
"type": "string",
"description": "ascending (asc) or descending (desc) order."
},
"limit": {
"type": "number",
"description": "max number of rows to be included in the file"
}
}
}
Headers
Content-Type: application/json
Body
{
"file_url: `/outatime/export/<YOUR_APP_KEY>/outatime_events_2019": "Hello, world!"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"file_url: `/outatime/export/<YOUR_APP_KEY>/outatime_events_2019": {
"type": "string",
"description": "03-15T18:12:29.270355Z.csv` (string, fixed-type) - the url to download the path, relative to the outatime host address"
}
}
}
Invalid parameters. Check the message on payload to see what happened.
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Export events CSVPOST/events/csv
Export events to a CSV file. Filtering options are as follow:
-
like_event_label
: search for a portion of the label name. -
type
: string to filter events of this type (exact). -
stream_id
: specify the events of a single stream. -
Specify a date range using
start_date
andend_date
. Expect ISO format strings. -
order_by
: field to order by it. Default it’s the event date. -
order_asc
: select if you want ascending (asc
) or descending order (desc
- default). -
limit
: the max number of events that will be included in the file. If not provided, all events are included.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
No App Key present or unauthorized
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Your license expired
Headers
Content-Type: application/json
Body
{
"error": "Invalid arguments",
"message": "The input field is invalid."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "error description."
},
"message": {
"type": "string",
"description": "details on what caused the error."
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Clear all eventsDELETE/events/clear_all
WARNING: Deletes all events from the system, without recovery. The action is irreversible, so make sure you really want to do that!
Lists ¶
Menage lists of labels (generic strings). Usually lists are used in the alarms to define black/white lists, or any other type that you want.
Manage lists ¶
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"name": "my list",
"description": "fist list",
"type": "streams",
"labels": [
"ash",
"misty",
"brock"
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"type": {
"type": "string"
},
"labels": {
"type": "array"
}
},
"required": [
"name",
"labels"
]
}
Headers
Content-Type: application/json
Body
{
"lists": {
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"lists": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string",
"description": "Name of the list"
},
"description": {
"type": "string",
"description": "Description of the list"
},
"type": {
"type": "string",
"description": "Type of the list (unused)"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
},
"labels": {
"type": "array",
"description": "the labels in the list"
}
},
"required": [
"id",
"name",
"description",
"type",
"updated_at",
"created_at",
"labels"
],
"additionalProperties": false
}
}
}
The provided app key is not autorized to create lists.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Create a listPOST/label_lists
Create a new list, containing the specified labels.
Headers
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"list": {
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"list": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string",
"description": "Name of the list"
},
"description": {
"type": "string",
"description": "Description of the list"
},
"type": {
"type": "string",
"description": "Type of the list (unused)"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
},
"labels": {
"type": "array",
"description": "the labels in the list"
}
},
"required": [
"id",
"name",
"description",
"type",
"updated_at",
"created_at",
"labels"
],
"additionalProperties": false
}
}
}
The provided app key is not autorized to access this list.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Retrieve a listGET/label_lists/{list_id}
Returns an existing list.
- list_id
int
(required) Example: 1The ID of the desired list
Headers
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"lists": [
{
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"lists": {
"type": "array"
}
}
}
Body
No APIKey present or unauthorized
Retrieve all listsGET/label_lists
Returns all existing lists.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"name": "my list",
"description": "fist list",
"type": "streams",
"labels": [
"ash",
"misty",
"brock"
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"type": {
"type": "string"
},
"labels": {
"type": "array"
}
}
}
Headers
Content-Type: application/json
Body
{
"list": {
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"list": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string",
"description": "Name of the list"
},
"description": {
"type": "string",
"description": "Description of the list"
},
"type": {
"type": "string",
"description": "Type of the list (unused)"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
},
"labels": {
"type": "array",
"description": "the labels in the list"
}
},
"required": [
"id",
"name",
"description",
"type",
"updated_at",
"created_at",
"labels"
],
"additionalProperties": false
}
}
}
The provided app key is not autorized to access this list.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Edit a listPATCH/label_lists/{list_id}
Partially update a list contents. If “labels” is sent, the new value will replace all previous list elements.
- list_id
int
(required) Example: 1The ID of the desired list
Headers
app_key: YOUR_APP_KEY
The provided app key is not autorized to access this list.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Removing this element would result in a conlfict. Maybe other resource depends on this.
Headers
Content-Type: application/json
Body
{
"error": "Existing Dependents",
"message": "Cannot delete List because it's refered by one or more {Dependancies}."
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
}
}
Removes a listDELETE/label_lists/{list_id}
- list_id
int
(required) Example: 1The ID of the desired list
Alarms ¶
Alarms are used in the system to let you know when an specific event has happened. They generally consist on a set of rules for triggering and a couple of actions to perform when set off.
Event Alarms ¶
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"description": "test streams",
"combination_type": "ANY",
"rules": [
{
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": "14:35:31",
"weekdays": [
0,
6
],
"min_confidence": "number",
"label_list_id": 1,
"event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": "Hello, world!",
"stream_id": 5
}
],
"actions": [
{
"type": "email",
"send_photo": false,
"email": "meerkat@meerkat.com.br",
"url": "http://www.myserver.com/meerkat/event",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Description of the alarm"
},
"combination_type": {
"type": "string",
"description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "`Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`"
},
"negate": {
"type": "boolean",
"description": "`Type of the list (unused)`"
},
"start_time": {
"type": "string",
"description": "`Alarm start hour`"
},
"timeout": {
"type": "string",
"description": "`Alarm timeout (max 24h)`"
},
"weekdays": {
"type": "array",
"description": "`day of the week the alarm will be active`"
},
"min_confidence": {
"type": "string",
"description": "`Minimal event confidence to trigger the alarm`"
},
"label_list_id": {
"type": "number",
"description": "`ID of label_list of event_labels that will trigger the alarm`"
},
"event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": {
"type": "string"
},
"stream_id": {
"type": "number",
"description": "`ID of the stream that will trigger the alarm`"
}
},
"required": [
"type",
"negate",
"start_time",
"timeout",
"weekdays",
"min_confidence",
"label_list_id",
"event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`",
"stream_id"
],
"additionalProperties": false
},
"description": "the conditions to trigger the alarm"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "`Type of action: email, webhook`"
},
"send_photo": {
"type": "boolean",
"description": "`set to True to attach a photo of the recognition event to the action call`"
},
"email": {
"type": "string",
"description": "`email rule destination`"
},
"url": {
"type": "string",
"description": "`webhook action URL`"
},
"updated_at": {
"type": "string",
"description": "`date & time of last update`"
},
"created_at": {
"type": "string",
"description": "`date & time of creation`"
}
},
"required": [
"type",
"send_photo",
"email",
"url",
"updated_at",
"created_at"
],
"additionalProperties": false
},
"description": "the actions to execute then the alarm is triggered"
}
},
"required": [
"combination_type",
"rules",
"actions"
]
}
Headers
Content-Type: application/json
Body
{
"alarm": {
"id": 1,
"description": "test streams",
"combination_type": "ANY",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"rules": [
{
"id": 1,
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": "14:35:31",
"weekdays": [
0,
6
],
"min_confidence": "number",
"label_list_id": 1,
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
"stream": {
"id": 1,
"label": "my little stream"
},
"list": {
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
},
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
],
"actions": [
{
"id": 1,
"type": "email",
"send_photo": false,
"email": "meerkat@meerkat.com.br",
"url": "http://www.myserver.com/meerkat/event",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"alarm": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"description": {
"type": "string",
"description": "Description of the alarm"
},
"combination_type": {
"type": "string",
"description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
},
"updated_at": {
"type": "string"
},
"created_at": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"type": {
"type": "string",
"description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
},
"negate": {
"type": "boolean",
"description": "Type of the list (unused)"
},
"start_time": {
"type": "string",
"description": "Alarm start hour"
},
"timeout": {
"type": "string",
"description": "Alarm timeout (max 24h)"
},
"weekdays": {
"type": "array",
"description": "day of the week the alarm will be active"
},
"min_confidence": {
"type": "string",
"description": "Minimal event confidence to trigger the alarm"
},
"label_list_id": {
"type": "number",
"description": "ID of stream_label or event_label"
},
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
"type": "string"
},
"stream": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "stream ID"
},
"label": {
"type": "string",
"description": "name of the stream"
}
},
"required": [
"id",
"label"
],
"additionalProperties": false,
"description": "Data of the stream that will trigger the alarm"
},
"list": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string",
"description": "Name of the list"
},
"description": {
"type": "string",
"description": "Description of the list"
},
"type": {
"type": "string",
"description": "Type of the list (unused)"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
},
"labels": {
"type": "array",
"description": "the labels in the list"
}
},
"required": [
"id",
"name",
"description",
"type",
"updated_at",
"created_at",
"labels"
],
"additionalProperties": false,
"description": "the labels in the list"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
}
},
"required": [
"id",
"type",
"negate",
"start_time",
"timeout",
"weekdays",
"min_confidence",
"label_list_id",
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
"stream",
"list",
"updated_at",
"created_at"
],
"additionalProperties": false
},
"description": "the labels in the list"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"type": {
"type": "string",
"description": "Type of action: email, webhook"
},
"send_photo": {
"type": "boolean",
"description": "set to True to attach a photo of the recognition event to the action call"
},
"email": {
"type": "string",
"description": "email rule destination"
},
"url": {
"type": "string",
"description": "webhook action URL"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
}
},
"required": [
"id",
"type",
"send_photo",
"email",
"url",
"updated_at",
"created_at"
],
"additionalProperties": false
},
"description": "the labels in the list"
}
},
"required": [
"id",
"description",
"combination_type",
"updated_at",
"created_at",
"rules",
"actions"
],
"additionalProperties": false
}
}
}
The provided app key is not autorized to create alarms.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Create an alarmPOST/alarms
Create a new alarm for events. Alarms have 4 components:
-
description
: a free text description of the alarm. -
actions
: a list of what to do when the alarm is triggered. See Actions for more details. -
rules
: a list of conditions determining which events will triggers the this alarm. See Rules for more details. -
combination_type
: how to combine the rules. must be one of the following values:ALL
: all rules in the alarm must be satisfied. At least one Rule must be provided.ANY
: al least one rule in the alarm must be satisfied. At least one Rule must be provided.ALWAYS
: trigger this alarm in every event. In this case, rules are ignored and the field ‘rules’ may be empty. Rules require at least one action to be provided at time of creation.
Headers
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"alarm": {
"id": 1,
"description": "test streams",
"combination_type": "ANY",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"rules": [
{
"id": 1,
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": "14:35:31",
"weekdays": [
0,
6
],
"min_confidence": "number",
"label_list_id": 1,
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
"stream": {
"id": 1,
"label": "my little stream"
},
"list": {
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
},
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
],
"actions": [
{
"id": 1,
"type": "email",
"send_photo": false,
"email": "meerkat@meerkat.com.br",
"url": "http://www.myserver.com/meerkat/event",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"alarm": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"description": {
"type": "string",
"description": "Description of the alarm"
},
"combination_type": {
"type": "string",
"description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
},
"updated_at": {
"type": "string"
},
"created_at": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"type": {
"type": "string",
"description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
},
"negate": {
"type": "boolean",
"description": "Type of the list (unused)"
},
"start_time": {
"type": "string",
"description": "Alarm start hour"
},
"timeout": {
"type": "string",
"description": "Alarm timeout (max 24h)"
},
"weekdays": {
"type": "array",
"description": "day of the week the alarm will be active"
},
"min_confidence": {
"type": "string",
"description": "Minimal event confidence to trigger the alarm"
},
"label_list_id": {
"type": "number",
"description": "ID of stream_label or event_label"
},
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
"type": "string"
},
"stream": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "stream ID"
},
"label": {
"type": "string",
"description": "name of the stream"
}
},
"required": [
"id",
"label"
],
"additionalProperties": false,
"description": "Data of the stream that will trigger the alarm"
},
"list": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string",
"description": "Name of the list"
},
"description": {
"type": "string",
"description": "Description of the list"
},
"type": {
"type": "string",
"description": "Type of the list (unused)"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
},
"labels": {
"type": "array",
"description": "the labels in the list"
}
},
"required": [
"id",
"name",
"description",
"type",
"updated_at",
"created_at",
"labels"
],
"additionalProperties": false,
"description": "the labels in the list"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
}
},
"required": [
"id",
"type",
"negate",
"start_time",
"timeout",
"weekdays",
"min_confidence",
"label_list_id",
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
"stream",
"list",
"updated_at",
"created_at"
],
"additionalProperties": false
},
"description": "the labels in the list"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"type": {
"type": "string",
"description": "Type of action: email, webhook"
},
"send_photo": {
"type": "boolean",
"description": "set to True to attach a photo of the recognition event to the action call"
},
"email": {
"type": "string",
"description": "email rule destination"
},
"url": {
"type": "string",
"description": "webhook action URL"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
}
},
"required": [
"id",
"type",
"send_photo",
"email",
"url",
"updated_at",
"created_at"
],
"additionalProperties": false
},
"description": "the labels in the list"
}
},
"required": [
"id",
"description",
"combination_type",
"updated_at",
"created_at",
"rules",
"actions"
],
"additionalProperties": false
}
}
}
Headers
Content-Type: application/json
Body
The provided app key is not autorized to access this alarm.
Get an alarmGET/alarms/{alarm_id}
Returns an existing alarm.
- alarm_id
int
(required) Example: 1The ID of the desired alarm
Headers
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"alarms": [
{
"id": 1,
"description": "test streams",
"combination_type": "ANY",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"rules": [
{
"id": 1,
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": "14:35:31",
"weekdays": [
0,
6
],
"min_confidence": "number",
"label_list_id": 1,
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
"stream": {
"id": 1,
"label": "my little stream"
},
"list": {
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
},
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
],
"actions": [
{
"id": 1,
"type": "email",
"send_photo": false,
"email": "meerkat@meerkat.com.br",
"url": "http://www.myserver.com/meerkat/event",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
]
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"alarms": {
"type": "array"
}
}
}
Get all alarmsGET/alarms
Returns an existing list.
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"description": "test streams",
"combination_type": "ANY",
"rules": [
{
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": "14:35:31",
"weekdays": [
0,
6
],
"min_confidence": "number",
"label_list_id": 1,
"event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": "Hello, world!",
"stream_id": 5
}
],
"actions": [
{
"type": "email",
"send_photo": false,
"email": "meerkat@meerkat.com.br",
"url": "http://www.myserver.com/meerkat/event",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Description of the alarm"
},
"combination_type": {
"type": "string",
"description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
},
"rules": {
"type": "array",
"description": "the labels in the list"
},
"actions": {
"type": "array",
"description": "the labels in the list"
}
},
"required": [
"description",
"combination_type",
"rules",
"actions"
]
}
Headers
Content-Type: application/json
Body
{
"alarm": {
"id": 1,
"description": "test streams",
"combination_type": "ANY",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"rules": [
{
"id": 1,
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": "14:35:31",
"weekdays": [
0,
6
],
"min_confidence": "number",
"label_list_id": 1,
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
"stream": {
"id": 1,
"label": "my little stream"
},
"list": {
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
},
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
],
"actions": [
{
"id": 1,
"type": "email",
"send_photo": false,
"email": "meerkat@meerkat.com.br",
"url": "http://www.myserver.com/meerkat/event",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
]
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"alarm": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"description": {
"type": "string",
"description": "Description of the alarm"
},
"combination_type": {
"type": "string",
"description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
},
"updated_at": {
"type": "string"
},
"created_at": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"type": {
"type": "string",
"description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
},
"negate": {
"type": "boolean",
"description": "Type of the list (unused)"
},
"start_time": {
"type": "string",
"description": "Alarm start hour"
},
"timeout": {
"type": "string",
"description": "Alarm timeout (max 24h)"
},
"weekdays": {
"type": "array",
"description": "day of the week the alarm will be active"
},
"min_confidence": {
"type": "string",
"description": "Minimal event confidence to trigger the alarm"
},
"label_list_id": {
"type": "number",
"description": "ID of stream_label or event_label"
},
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
"type": "string"
},
"stream": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "stream ID"
},
"label": {
"type": "string",
"description": "name of the stream"
}
},
"required": [
"id",
"label"
],
"additionalProperties": false,
"description": "Data of the stream that will trigger the alarm"
},
"list": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string",
"description": "Name of the list"
},
"description": {
"type": "string",
"description": "Description of the list"
},
"type": {
"type": "string",
"description": "Type of the list (unused)"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
},
"labels": {
"type": "array",
"description": "the labels in the list"
}
},
"required": [
"id",
"name",
"description",
"type",
"updated_at",
"created_at",
"labels"
],
"additionalProperties": false,
"description": "the labels in the list"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
}
},
"required": [
"id",
"type",
"negate",
"start_time",
"timeout",
"weekdays",
"min_confidence",
"label_list_id",
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
"stream",
"list",
"updated_at",
"created_at"
],
"additionalProperties": false
},
"description": "the labels in the list"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"type": {
"type": "string",
"description": "Type of action: email, webhook"
},
"send_photo": {
"type": "boolean",
"description": "set to True to attach a photo of the recognition event to the action call"
},
"email": {
"type": "string",
"description": "email rule destination"
},
"url": {
"type": "string",
"description": "webhook action URL"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
}
},
"required": [
"id",
"type",
"send_photo",
"email",
"url",
"updated_at",
"created_at"
],
"additionalProperties": false
},
"description": "the labels in the list"
}
},
"required": [
"id",
"description",
"combination_type",
"updated_at",
"created_at",
"rules",
"actions"
],
"additionalProperties": false
}
}
}
The provided app key is not autorized to access this alarm.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Edit an alarmPATCH/alarms/{alarm_id}
Partially update an alarm. If rules or actions sent in this route will replace existing ones.
- alarm_id
int
(required) Example: 1The ID of the desired alarm
Headers
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
The provided app key is not autorized to access this alarm.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Remove an alarmDELETE/alarms/{alarm_id}
- alarm_id
int
(required) Example: 1The ID of the desired alarm
Headers
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"rules": [
{
"id": 1,
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": "14:35:31",
"weekdays": [
0,
6
],
"min_confidence": "number",
"label_list_id": 1,
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
"stream": {
"id": 1,
"label": "my little stream"
},
"list": {
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
},
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"rules": {
"type": "array"
}
}
}
The provided app key is not autorized to access this rule.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
List alarm rulesGET/alarms/{alarm_id}/rules
Returns all the rules associated with an existing alarm.
- alarm_id
int
(required) Example: 1The ID of the desired alarm
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": "14:35:31",
"weekdays": [
0,
6
],
"min_confidence": "number",
"label_list_id": 1,
"event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": "Hello, world!",
"stream_id": 5
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "`Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`"
},
"negate": {
"type": "boolean",
"description": "`Type of the list (unused)`"
},
"start_time": {
"type": "string",
"description": "`Alarm start hour`"
},
"timeout": {
"type": "string",
"description": "`Alarm timeout (max 24h)`"
},
"weekdays": {
"type": "array",
"description": "`day of the week the alarm will be active`"
},
"min_confidence": {
"type": "string",
"description": "`Minimal event confidence to trigger the alarm`"
},
"label_list_id": {
"type": "number",
"description": "`ID of label_list of event_labels that will trigger the alarm`"
},
"event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": {
"type": "string"
},
"stream_id": {
"type": "number",
"description": "`ID of the stream that will trigger the alarm`"
}
},
"required": [
"type",
"negate",
"start_time",
"timeout",
"weekdays",
"min_confidence",
"label_list_id",
"event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`",
"stream_id"
],
"additionalProperties": false
}
Headers
Content-Type: application/json
Body
{
"rule": {
"id": 1,
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": "14:35:31",
"weekdays": [
0,
6
],
"min_confidence": "number",
"label_list_id": 1,
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
"stream": {
"id": 1,
"label": "my little stream"
},
"list": {
"id": 1,
"name": "test streams",
"description": "test streams",
"type": "stream",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31",
"labels": [
"ash",
"misty",
"brock"
]
},
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"rule": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"type": {
"type": "string",
"description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
},
"negate": {
"type": "boolean",
"description": "Type of the list (unused)"
},
"start_time": {
"type": "string",
"description": "Alarm start hour"
},
"timeout": {
"type": "string",
"description": "Alarm timeout (max 24h)"
},
"weekdays": {
"type": "array",
"description": "day of the week the alarm will be active"
},
"min_confidence": {
"type": "string",
"description": "Minimal event confidence to trigger the alarm"
},
"label_list_id": {
"type": "number",
"description": "ID of stream_label or event_label"
},
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
"type": "string"
},
"stream": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "stream ID"
},
"label": {
"type": "string",
"description": "name of the stream"
}
},
"required": [
"id",
"label"
],
"additionalProperties": false,
"description": "Data of the stream that will trigger the alarm"
},
"list": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string",
"description": "Name of the list"
},
"description": {
"type": "string",
"description": "Description of the list"
},
"type": {
"type": "string",
"description": "Type of the list (unused)"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
},
"labels": {
"type": "array",
"description": "the labels in the list"
}
},
"required": [
"id",
"name",
"description",
"type",
"updated_at",
"created_at",
"labels"
],
"additionalProperties": false,
"description": "the labels in the list"
},
"updated_at": {
"type": "string",
"description": "date & time of last update"
},
"created_at": {
"type": "string",
"description": "date & time of creation"
}
},
"required": [
"id",
"type",
"negate",
"start_time",
"timeout",
"weekdays",
"min_confidence",
"label_list_id",
"event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
"stream",
"list",
"updated_at",
"created_at"
],
"additionalProperties": false
}
}
}
The provided app key is not autorized to create rules.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
Add alarm rulePOST/alarms/{alarm_id}/rules
Add a new rule defining a condition to when the alarm should be triggered. Rules have the following fields:
-
type
: Type of rule: min_confidence, stream_label, event_label, time_range, weekdays -
negate
: Set to True to invert this rule -
start_time
: time of the day to activate the alarm, string with format “hh:mm:ss”. Used only when type=“time_range”. -
timeout
: Alarm timeout afterstart_time
(max 24h), integer in seconds. Used only when type=“time_range”. -
weekdays
: List of days of the week the alarm will be active. Array of integers where 0=Monday, …, 6=Sunday. Used only when type=“weekdays”. -
min_confidence
: Minimal detection/recognition confidence to trigger the alarm. Float between [0, 100]. Used only when type=“min_confidence”. -
label_list_id
: ID of Label List for which the alarm is valid. Used only when type=“event_label”. -
event_label
: a single Event Label for which the alarm is valid. Used only when type=“event_label”. -
stream_id
: ID of Stream for which the alarm is valid. Used only when type=“stream_label”.
Note that not all fields are used in every rule. Only some fields are required depending to the rule type:
-
type=min_confidence
: usesmin_confidence
-
type=stream_label
: usesstream_id
-
type=event_label
: useslabel_list_id
andevent_label
-
type=time_range
: usesstart_time
andtimeout
-
type=weekdays
: usesweekdays
- alarm_id
int
(required) Example: 1The ID of the desired alarm
Headers
app_key: YOUR_APP_KEY
Headers
Content-Type: application/json
Body
{
"actions": [
{
"id": 1,
"type": "email",
"send_photo": false,
"email": "meerkat@meerkat.com.br",
"url": "http://www.myserver.com/meerkat/event",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
]
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"actions": {
"type": "array"
}
}
}
The provided app key is not autorized to access this rule.
Headers
Content-Type: application/json
Body
{
"error": "Unauthorized access",
"message": "error details"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
},
"required": [
"error",
"message"
],
"additionalProperties": false
}
List alarm actionsGET/alarms/{alarm_id}/actions
- alarm_id
int
(required) Example: 1The ID of the desired alarm
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
"type": "email",
"send_photo": false,
"email": "meerkat@meerkat.com.br",
"url": "http://www.myserver.com/meerkat/event",
"updated_at": "20180925 14:35:31",
"created_at": "20180925 14:35:31"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "`Type of action: email, webhook`"
},
"send_photo": {
"type": "boolean",
"description": "`set to True to attach a photo of the recognition event to the action call`"
},
"email": {
"type": "string",
"description": "`email rule destination`"
},
"url": {
"type": "string",
"description": "`webhook action URL`"
},
"updated_at": {
"type": "string",
"description": "`date & time of last update`"
},
"created_