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_KEYdisplayed on the top right of the webpage. Alternatively, you can request yourAPP_KEYthrough 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.
GET http://localhost/frapi/version
Requests
Headers
Content-Type: application/jsonResponses
Headers
Content-Type: application/jsonBody
{
"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 ¶
GET http://localhost/frapi/activation
Requests
Headers
Content-Type: application/jsonResponses
Headers
Content-Type: application/jsonBody
{
"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.
POST http://localhost/frapi/activation
Requests
Headers
Content-Type: application/jsonBody
{
"key": "61683eb9642326ebc458efe5d7414e21"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Your license key"
}
}
}Responses
This response has no content.
Your key provided as argument is invalid or something went wrong during activation
Headers
Content-Type: application/jsonBody
{
"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).
GET http://localhost/frapi/app_keys/default
Requests
Headers
Content-Type: application/jsonResponses
Headers
Content-Type: application/jsonBody
{
"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.
POST http://localhost/frapi/faces
Requests
Headers
Content-Type: application/jsonBody
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg",
"label": "name"
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/faces
Requests
Headers
Content-Type: application/jsonBody
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA...",
"label": "name"
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/faces
Requests
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEYBody
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
data
--BOUNDARY--Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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 ¶
POST http://localhost/frapi/faces/from_events
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
GET http://localhost/frapi/people
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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).
GET http://localhost/frapi/faces
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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).
GET http://localhost/frapi/people/mandela
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- person_label
string(required) Example: mandela
GET http://localhost/frapi/faces/abc
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- face_id
string(required) Example: abc
DELETE http://localhost/frapi/people/mandela
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
This response has no content.
No App Key present or unauthorized
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- person_label
string(required) Example: mandela
DELETE http://localhost/frapi/faces/abc
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
This response has no content.
No App Key present or unauthorized
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- face_id
string(required) Example: abc
Detection ¶
Face detection bounding boxes ¶
Detects faces in an image, returning their bounding boxes.
POST http://localhost/frapi/detection/faces
Requests
Headers
Content-Type: application/jsonBody
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg"
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/detection/faces
Requests
Headers
Content-Type: application/jsonBody
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA..."
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/detection/faces
Requests
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEYBody
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
data
--BOUNDARY--Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/detection/landmarks
Requests
Headers
Content-Type: application/jsonBody
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg"
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/detection/landmarks
Requests
Headers
Content-Type: application/jsonBody
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA..."
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/detection/landmarks
Requests
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEYBody
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
data
--BOUNDARY--Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/recognition
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg"
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/recognition
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA..."
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/recognition
Requests
Headers
Content-Type: multipart/form-data; boundary=--{boundary value}
app_key: YOUR_APP_KEYBody
--{boundary value}
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
{file content}
--{boundary value}--Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/recognition/top_n
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg",
"n": 5
}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
}
},
"required": [
"imageUrl"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/recognition/top_n
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA...",
"n": 5
}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
}
},
"required": [
"imageB64"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/recognition/top_n
Requests
Headers
Content-Type: multipart/form-data; boundary=--{boundary value}
app_key: YOUR_APP_KEYBody
--{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}--Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/verification
Requests
Headers
Content-Type: application/jsonBody
{
"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"
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/verification
Requests
Headers
Content-Type: application/jsonBody
{
"imageB641": "/9j/4RiDRXhpZgAATU0AKgA...",
"imageB642": "/9j/4RiDRXhpZgAATU0AKgA..."
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/verification
Requests
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEYBody
--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--Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/verification/mandela
Requests
Headers
Content-Type: application/jsonBody
{
"imageUrl": "https://upload.wikimedia.org/wikipedia/commons/0/02/Nelson_Mandela_1994.jpg"
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- person_label
string(required) Example: mandela
POST http://localhost/frapi/verification/mandela
Requests
Headers
Content-Type: application/jsonBody
{
"imageB64": "/9j/4RiDRXhpZgAATU0AKgA..."
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- person_label
string(required) Example: mandela
POST http://localhost/frapi/verification/mandela
Requests
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEYBody
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg
data
--BOUNDARY--Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- person_label
string(required) Example: mandela
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.aviin 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).0is 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.
POST http://localhost/frapi/streams
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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
}Responses
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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
GET http://localhost/frapi/streams/1
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- stream_id
number(required) Example: 1Stream identifier
PATCH http://localhost/frapi/streams/1
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- stream_id
number(required) Example: 1Stream identifier
GET http://localhost/frapi/streams
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
GET http://localhost/frapi/streams/1/run
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
This response has no content.
No App Key present or unauthorized
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- stream_id
number(required) Example: 1
GET http://localhost/frapi/streams/1/stop
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
This response has no content.
No App Key present or unauthorized
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- stream_id
number(required) Example: 1
GET http://localhost/frapi/streams/1/status
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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).
URI Parameters
- stream_id
number(required) Example: 1
DELETE http://localhost/frapi/streams/1
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
This response has no content.
Removing a streamDELETE/streams/{stream_id}
Remove the stream using the stream_id.
URI Parameters
- 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 totrueif you want to save JSON files with the stream results. -
make_http_requests: set totrueif 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 totrueif you want to write the video output to a file -
video_optionsmax_video_mins: the maximum video duration in minutesinclude_date_in_video: set totrueto 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_optionsas 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 totrueif you want the stream date to be printed on the video as well.make_raw_video_output: set totrueif you want to store the raw stream (without any results drawings) as well.
GET http://localhost/frapi/admin/stream/output
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/admin/stream/output
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
GET http://localhost/frapi/admin/event/settings
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
POST http://localhost/frapi/admin/event/settings
Requests
Headers
Content-Type: application/jsonBody
{
"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
}Responses
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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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 ¶
GET http://localhost/frapi/event/1
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
Invalid event idHeaders
Content-Type: application/jsonBody
No APIKey present or unauthorizedGet a specific eventGET/event/{event_id}
Fetches a single event from the database.
URI Parameters
- event_id
number(required) Example: 1Event identifier
DELETE http://localhost/frapi/event/1
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonHeaders
Content-Type: application/jsonBody
Invalid event idHeaders
Content-Type: application/jsonBody
No APIKey present or unauthorizedDelete a specific eventDELETE/event/{event_id}
Deletes a single event from the system, without recovery.
URI Parameters
- event_id
number(required) Example: 1Event identifier
GET http://localhost/frapi/events/last?n_events=10
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- n_events
number(required) Example: 10Last events to return.
GET http://localhost/frapi/events?page=1&per_page=10&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
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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_dateandend_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).
URI Parameters
- 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.
POST http://localhost/frapi/events/csv
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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"
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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/jsonBody
{
"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_dateandend_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.
DELETE http://localhost/frapi/events/clear_all
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYResponses
This response has no content.
No App Key present or unauthorized
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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 ¶
POST http://localhost/frapi/label_lists
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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.
GET http://localhost/frapi/label_lists/1
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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/jsonBody
{
"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.
URI Parameters
- list_id
int(required) Example: 1The ID of the desired list
GET http://localhost/frapi/label_lists
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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 unauthorizedRetrieve all listsGET/label_lists
Returns all existing lists.
PATCH http://localhost/frapi/label_lists/1
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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"
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- list_id
int(required) Example: 1The ID of the desired list
DELETE http://localhost/frapi/label_lists/1
Requests
Headers
app_key: YOUR_APP_KEYResponses
This response has no content.
The provided app key is not autorized to access this list.
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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}
URI Parameters
- 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 ¶
POST http://localhost/frapi/alarms
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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.
GET http://localhost/frapi/alarms/1
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
The provided app key is not autorized to access this alarm.Get an alarmGET/alarms/{alarm_id}
Returns an existing alarm.
URI Parameters
- alarm_id
int(required) Example: 1The ID of the desired alarm
GET http://localhost/frapi/alarms
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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.
PATCH http://localhost/frapi/alarms/1
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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"
]
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- alarm_id
int(required) Example: 1The ID of the desired alarm
DELETE http://localhost/frapi/alarms/1
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonThe provided app key is not autorized to access this alarm.
Headers
Content-Type: application/jsonBody
{
"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}
URI Parameters
- alarm_id
int(required) Example: 1The ID of the desired alarm
GET http://localhost/frapi/alarms/1/rules
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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.
URI Parameters
- alarm_id
int(required) Example: 1The ID of the desired alarm
POST http://localhost/frapi/alarms/1/rules
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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
}Responses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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_idandevent_label -
type=time_range: usesstart_timeandtimeout -
type=weekdays: usesweekdays
URI Parameters
- alarm_id
int(required) Example: 1The ID of the desired alarm
GET http://localhost/frapi/alarms/1/actions
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"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
URI Parameters
- alarm_id
int(required) Example: 1The ID of the desired alarm
POST http://localhost/frapi/alarms/1/actions
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"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_at": {
"type": "string",
"description": "`date & time of creation`"
}
},
"required": [
"type",
"send_photo",
"email",
"url",
"updated_at",
"created_at"
],
"additionalProperties": false
}Responses
Headers
Content-Type: application/jsonBody
{
"action": {
"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": {
"action": {
"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
}
}
}The provided app key is not autorized to create rules.Headers
Content-Type: application/jsonBody
{
"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 actionPOST/alarms/{alarm_id}/actions
Add a new action to execute when this alarm is triggered. Actions have the following fields:
-
type: Type of action: “email” or “webhook” -
send_photo: set to True to attach a photo of the recognition event in the action execution -
email: email address to send and email if type is “email”. Otherwise ignored . -
url: HTTP URL to call if type is “webhook”. Otherwise ignored.
Note that not all fields are used in every action. Only some fields are required depending to the action type:
-
type=email: usesemail -
type=webhook: usesurl
URI Parameters
- alarm_id
int(required) Example: 1The ID of the desired alarm
Alarm rules ¶
Directly manipulates alarm rules.
GET http://localhost/frapi/alarms/rules/1
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"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 access this rule.
Headers
Content-Type: application/jsonBody
{
"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
}Get a specific alarm ruleGET/alarms/rules/{rule_id}
URI Parameters
- rule_id
int(required) Example: 1The ID of the desired rule
PATCH http://localhost/frapi/alarms/rules/1
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"type": "weekdays",
"negate": false,
"start_time": "14:35:31",
"timeout": 3600,
"weekdays": [
1
],
"min_confidence": 98,
"label_list_id": 1
}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": "number",
"description": "Alarm timeout in seconds"
},
"weekdays": {
"type": "array",
"description": "day of the week the alarm will be active"
},
"min_confidence": {
"type": "number",
"description": "Minimal event confidence to trigger the alarm"
},
"label_list_id": {
"type": "number",
"description": "ID of stream_label or event_label"
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"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 access this rule.
Headers
Content-Type: application/jsonBody
{
"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 rulePATCH/alarms/rules/{rule_id}
URI Parameters
- rule_id
int(required) Example: 1The ID of the desired rule
DELETE http://localhost/frapi/alarms/rules/1
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonThe provided app key is not autorized to access this rule.
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"error": "Existing Dependents",
"message": "Cannot delete Rule because it's refered by one or more Alarms."
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
}
}Delete a ruleDELETE/alarms/rules/{rule_id}
URI Parameters
- rule_id
int(required) Example: 1The ID of the desired rule
Actions ¶
Manipulate alarm actions directly by is action_id.
GET http://localhost/frapi/alarms/actions/1
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonBody
{
"action": {
"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": {
"action": {
"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
}
}
}The provided app key is not authorized to perform this action.
Headers
Content-Type: application/jsonBody
{
"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
}Get an actionGET/alarms/actions/{action_id}
URI Parameters
- action_id
int(required) Example: 1The ID of the desired action
PATCH http://localhost/frapi/alarms/actions/1
Requests
Headers
Content-Type: application/json
app_key: YOUR_APP_KEYBody
{
"type": "email",
"send_photo": false,
"email": "robin.hood@meerkat.com.br",
"url": "http://www.myserver.com/images/event"
}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"
}
}
}Responses
Headers
Content-Type: application/jsonBody
{
"action": {
"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": {
"action": {
"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
}
}
}The provided app key is not authorized to perform this action.
Headers
Content-Type: application/jsonBody
{
"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 actionPATCH/alarms/actions/{action_id}
URI Parameters
- action_id
int(required) Example: 1The ID of the desired action
DELETE http://localhost/frapi/alarms/actions/1
Requests
Headers
app_key: YOUR_APP_KEYResponses
Headers
Content-Type: application/jsonThe provided app key is not authorized to perform this action.
Headers
Content-Type: application/jsonBody
{
"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/jsonBody
{
"error": "Existing Dependents",
"message": "Cannot delete Action because it's refered by one or more Alarms."
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error Name"
},
"message": {
"type": "string",
"description": "Error Details"
}
}
}