warhol API Documentation

This documentation provides a simple and easy way to learn about our API and to integrate it with your application using both our web and REST interfaces. We believe that the web interface is the best way to start, since it will show how our system works in a more natural and friendly way. And when the integration time comes, rest assured that all the funcionalities from the web interface are available through our REST interface.

Of course, we’re assuming that you have a valid license activated in your system; if that’s not the case and you want a free trial, contact us at sales@meerkat.com.br.

Geting Started

There are two straightforward ways to test our API. The first is by using Postman. Just download our collection, import it on Postman and start playing around. You will find examples for our most common features such as adding and playing different types of video streams, detecting and recognizing faces and more.

Authentication

Basically, the API’s authentication is performed through your app key. You must include it on every request headers. You app key is a 64-character string and should be included in a header field called app_key. There are some consideration on this, depending on the system’s deploy. In either case, your key will be shown on the top right of the web interface.

  • On-premise: If you are running the system on premise, once you activate your license a key is automatically generated for you. Also, if you did not create additional keys, i.e. you have a single app key, you do not need to provided in your requests. The system will take this single key as default for all operations.
  • Cloud service: Obtain your trial key in our website following the registration procedure. Then, login in to the web interface and find your APP_KEY displayed on the top right of the webpage. Alternatively, you can request your APP_KEY through the /user/<username> endpoint.

Testing API calls

There are two straightforward ways to test our API. The first is by using [Postman] (https://www.getpostman.com/). Just import our collection on it and start playing around. The second one is by using the code snippets bellow in your favorite programming language.

Support

If you need help, send us an e-mail at support@meerkat.com.br or use the support webapp page

Version

Check API version

Will return the current API version. It should be useful to check the API state also.

GET http://localhost/warhol/version
Requestsexample
Headers
Content-Type: application/json
Responses200
Headers
Content-Type: application/json
Body
{
  "version": "1.0",
  "source_commit": "c71266d"
}
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"
    }
  },
  "required": [
    "version",
    "source_commit"
  ]
}

Get system current version
GET/version


Activation

Once you get your on-premise version of warhol, you need to activate it online to start using. If you access your webapp and the API is not activated you’ll be redirected to an activation page. Nonetheless, you can activate or check you license status using the REST API, as described below.

Note: all important routes with the exception of /version and /activate will return 404 until your system is activated with your license key. Also, you need internet access to activate the API.

Activate or check your activation

GET http://localhost/warhol/activation
Requestsexample
Headers
Content-Type: application/json
Responses200
Headers
Content-Type: application/json
Body
{
  "is_activated": true,
  "license": {
    "expiration_date": "21/10/2015",
    "key": "12abc345..."
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "is_activated": {
      "type": "boolean",
      "description": "Value indicating if your system is activated or not"
    },
    "license": {
      "type": "object",
      "properties": {
        "expiration_date": {
          "type": "string"
        },
        "key": {
          "type": "string"
        }
      },
      "required": [
        "expiration_date",
        "key"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "is_activated",
    "license"
  ]
}

Check license status
GET/activation

Will return if your system is activated or not.


POST http://localhost/warhol/activation
Requestsexample
Headers
Content-Type: application/json
Body
{
  "key": "61683eb9642326ebc458efe5d7414e21"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "Your license key"
    }
  }
}
Responses200422
This response has no content.

You key provided as argument is invalid or something went wrong during activation

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Activate your license
POST/activation

This activate your system given 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/warhol/app_keys/default
Requestsexample
Headers
Content-Type: application/json
Responses200
Headers
Content-Type: application/json
Body
{
  "app_key": "abcdeabcde"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "app_key": {
      "type": "string",
      "description": "Your app key"
    }
  },
  "required": [
    "app_key"
  ]
}

Retrieve your default app key
GET/app_keys/default

Retrieve the default app_key if the system is running on premise and a single app_key exists.


Recognition

Object Recognition

Performs object detection in an image, returning the list of recognized objects.

IMPORTANT: Calling these routes will consume API calls from your account current quota cycle.

POST http://localhost/warhol/recognition/object
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "imageUrl": "https://s3-ap-southeast-1.amazonaws.com/media.redmart.com/newmedia/460x/i/m/9002490218058_0212_1480658637758.jpg"
}
Responses200401403422432
Headers
Content-Type: application/json
Body
{
  "recognitions": [
    {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "label": "Big box",
      "confidence": 0.9232231
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recognitions": {
      "type": "array",
      "items": {
        "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
          },
          "label": {
            "type": "string",
            "description": "`The object recognized for this box.`"
          },
          "confidence": {
            "type": "number",
            "description": "`confidence in the recocnized label`"
          }
        },
        "required": [
          "bottom_right",
          "top_left",
          "label",
          "confidence"
        ],
        "additionalProperties": false
      },
      "description": "List of all recognized objects in the image."
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Your license expired

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Wrong or missing input arguments

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Image provided could not be read

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Object Recognition using image URL
POST/recognition/object

IMPORTANT: Calling this route will consume API calls from your account current quota cycle.


POST http://localhost/warhol/recognition/object
Requestsexample
Headers
Content-Type: application/json
Body
{
  "imageB64": "/9j/4RiDRXhpZgAATU0AKgA..."
}
Responses200401403422432
Headers
Content-Type: application/json
Body
{
  "recognitions": [
    {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "label": "Big box",
      "confidence": 0.9232231
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recognitions": {
      "type": "array"
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Your license expired

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Wrong or missing input arguments

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Image provided could not be read

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Object Recognition using string base64 JPEG
POST/recognition/object

IMPORTANT: Calling this route will consume API calls from your account current quota cycle.


POST http://localhost/warhol/recognition/object
Requestsexample 1
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEY
Body
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg

data
--BOUNDARY--
Responses200401403422432
Headers
Content-Type: application/json
Body
{
  "detections": [
    {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "recognitions": [
        {
          "confidence": 0,
          "predicted_label": "name"
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "detections": {
      "type": "array"
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Your license expired

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Wrong or missing input arguments

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Image provided could not be read

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Object Recognition using multipart form-data
POST/recognition/object

IMPORTANT: Calling this route will consume API calls from your account current quota cycle.


Logo Recognition

Performs object detection in an image, returning the list of recognized logos.

IMPORTANT: Calling these routes will consume API calls from your account current quota cycle.

POST http://localhost/warhol/recognition/logo
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "imageUrl": "https://s3-ap-southeast-1.amazonaws.com/media.redmart.com/newmedia/460x/i/m/9002490218058_0212_1480658637758.jpg"
}
Responses200401403422432
Headers
Content-Type: application/json
Body
{
  "recognitions": [
    {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "label": "Big box",
      "confidence": 0.9232231
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recognitions": {
      "type": "array",
      "items": {
        "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
          },
          "label": {
            "type": "string",
            "description": "`The object recognized for this box.`"
          },
          "confidence": {
            "type": "number",
            "description": "`confidence in the recocnized label`"
          }
        },
        "required": [
          "bottom_right",
          "top_left",
          "label",
          "confidence"
        ],
        "additionalProperties": false
      },
      "description": "List of all recognized objects in the image."
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Your license expired

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Wrong or missing input arguments

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Image provided could not be read

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Logo Recognition using image URL
POST/recognition/logo

IMPORTANT: Calling this route will consume API calls from your account current quota cycle.


POST http://localhost/warhol/recognition/logo
Requestsexample
Headers
Content-Type: application/json
Body
{
  "imageB64": "/9j/4RiDRXhpZgAATU0AKgA..."
}
Responses200401403422432
Headers
Content-Type: application/json
Body
{
  "recognitions": [
    {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "label": "Big box",
      "confidence": 0.9232231
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recognitions": {
      "type": "array"
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Your license expired

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Wrong or missing input arguments

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Image provided could not be read

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Logo Recognition using string base64 JPEG
POST/recognition/logo

IMPORTANT: Calling this route will consume API calls from your account current quota cycle.


POST http://localhost/warhol/recognition/logo
Requestsexample 1
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEY
Body
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg

data
--BOUNDARY--
Responses200401403422432
Headers
Content-Type: application/json
Body
{
  "detections": [
    {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "recognitions": [
        {
          "confidence": 0,
          "predicted_label": "name"
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "detections": {
      "type": "array"
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Your license expired

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Wrong or missing input arguments

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Image provided could not be read

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Logo Recognition using multipart form-data
POST/recognition/logo

IMPORTANT: Calling this route will consume API calls from your account current quota cycle.


Full Recognition

Performs object detection in an image, returning the list of recognized objects and logos.

IMPORTANT: Calling these routes will consume API calls from your account current quota cycle.

POST http://localhost/warhol/recognition/all
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "imageUrl": "https://s3-ap-southeast-1.amazonaws.com/media.redmart.com/newmedia/460x/i/m/9002490218058_0212_1480658637758.jpg"
}
Responses200401403422432
Headers
Content-Type: application/json
Body
{
  "recognitions": [
    {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "label": "Big box",
      "confidence": 0.9232231
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recognitions": {
      "type": "array",
      "items": {
        "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
          },
          "label": {
            "type": "string",
            "description": "`The object recognized for this box.`"
          },
          "confidence": {
            "type": "number",
            "description": "`confidence in the recocnized label`"
          }
        },
        "required": [
          "bottom_right",
          "top_left",
          "label",
          "confidence"
        ],
        "additionalProperties": false
      },
      "description": "List of all recognized objects in the image."
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Your license expired

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Wrong or missing input arguments

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Image provided could not be read

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Full Recognition using image URL
POST/recognition/all

IMPORTANT: Calling this route will consume API calls from your account current quota cycle.


POST http://localhost/warhol/recognition/all
Requestsexample
Headers
Content-Type: application/json
Body
{
  "imageB64": "/9j/4RiDRXhpZgAATU0AKgA..."
}
Responses200401403422432
Headers
Content-Type: application/json
Body
{
  "recognitions": [
    {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "label": "Big box",
      "confidence": 0.9232231
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recognitions": {
      "type": "array",
      "description": "List of all recognized objects in the image."
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Your license expired

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Wrong or missing input arguments

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Image provided could not be read

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Full Recognition using string base64 JPEG
POST/recognition/all

IMPORTANT: Calling this route will consume API calls from your account current quota cycle.


POST http://localhost/warhol/recognition/all
Requestsexample 1
Headers
Content-Type: multipart/form-data; boundary=--BOUNDARY
app_key: YOUR_APP_KEY
Body
--BOUNDARY
Content-Disposition: form-data; name="image"; filename="filename.jpg"
Content-Type: image/jpeg

data
--BOUNDARY--
Responses200401403422432
Headers
Content-Type: application/json
Body
{
  "recognitions": [
    {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "recognitions": [
        {
          "confidence": 0,
          "predicted_label": "name"
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recognitions": {
      "type": "array",
      "description": "List of all recognized objects in the image."
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Your license expired

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Wrong or missing input arguments

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Image provided could not be read

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Full Recognition using multipart form-data
POST/recognition/all

IMPORTANT: Calling this route will consume API calls from your account current quota cycle.


Stream

The core vision algorithms can run at real-time in streams, which usually correspond to videos or IP cameras.

Stream configuration and control

To configure a stream you basically has 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: whether the stream is a video or an IP camera. Options are video and ip_camera.

  • path: the location url of the stream. If IP camera, you need to arrange the URL given the local IP address and a suffix which varies from each camera model – a good guide to find you URL can be found here. For the video, you can use the upload on the web interface, or put your video in /var/lib/meerkat/user_data/video/<your_app_key>/ and pass the /user_data/video/<your_app_key>/YOUR_VIDEO.avi in this field.

  • you can pass a set of options that you can latter change for your stream:

    • resize: this tell the algorithm which is the expected size of a plate or face in pixels. Larger values will not detect small plates or faces, but it will improve performance.
    • rotation: an angle to rotate the frames coming from the stream. Positive values rotate counter clockwise and negative values rotate clockwise.
    • roi: this option defines a region of interest (ROI) on the camera. You need to pass the top-left and bottom-right coordinates for it.
    • video_skip_frame: how many video frames will be skipped between each recognition (only work for video type). 0 is the default value which process all frames. You can increase this value to speed-up the stream processing.
    • mode : specifies which object classes are recognized. When set to logo, it recognizes pretrained logos only. When set to object, it recognizes predefined real-world objects only. When set to full, both object grupos are recognized.
    • 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/warhol/streams
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "algo_type": "detection",
  "path": "stream.mp4",
  "stream_label": "test",
  "stream_type": "video",
  "detector_size": 130,
  "rotation": -2,
  "start_on_restart": false,
  "always_on": true,
  "roi": {
    "bottom_right": {
      "x": 0,
      "y": 0
    },
    "top_left": {
      "x": 0,
      "y": 0
    },
    "recognitions": [
      {
        "confidence": 0,
        "predicted_label": "name"
      }
    ]
  },
  "video_skip_frame": 30,
  "mode": "logo",
  "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."
    },
    "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
        },
        "recognitions": {
          "type": "array"
        }
      },
      "required": [
        "bottom_right",
        "top_left",
        "recognitions"
      ],
      "additionalProperties": false,
      "description": "bounding box of the region of interest"
    },
    "video_skip_frame": {
      "type": "number",
      "description": "step between frames, only works for videos."
    },
    "mode": {
      "type": "string",
      "description": "specifies which object classes are recognized. It should be either `logo`, `object` or `full`."
    },
    "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",
    "roi",
    "video_skip_frame",
    "mode",
    "max_FPS",
    "follow_stream_rate"
  ],
  "additionalProperties": false
}
Responses200422401
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,
    "roi": {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "recognitions": [
        {
          "confidence": 0,
          "predicted_label": "name"
        }
      ]
    },
    "video_skip_frame": 30,
    "mode": "logo",
    "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."
        },
        "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"
                }
              }
            },
            "recognitions": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "confidence": {
                    "type": "number",
                    "description": "Confidence of the prediction (ranging from 0 to 100)"
                  },
                  "predicted_label": {
                    "type": "string",
                    "description": "Predicted ID (name) of this person"
                  }
                }
              }
            }
          },
          "description": "bounding box of the region of interest"
        },
        "video_skip_frame": {
          "type": "number",
          "description": "step between frames, only works for videos."
        },
        "mode": {
          "type": "string",
          "description": "specifies which object classes are recognized. It should be either `logo`, `object` or `full`."
        },
        "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#"
}

Invalid parameters to create a stream. Check the message on payload to see what happened.

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Adding a stream
POST/streams

Add a stream to the system to process recognition.


GET http://localhost/warhol/streams/1
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "stream": {
    "algo_type": "detection",
    "path": "/user_data/video/<YOUR_APP_KEY>/video.mp4",
    "stream_label": "test",
    "id": 7,
    "stream_type": "video",
    "detector_size": 130,
    "rotation": -2,
    "start_on_restart": false,
    "always_on": true,
    "roi": {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "recognitions": [
        {
          "confidence": 0,
          "predicted_label": "name"
        }
      ]
    },
    "video_skip_frame": 30,
    "mode": "logo",
    "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."
        },
        "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
            },
            "recognitions": {
              "type": "array"
            }
          },
          "required": [
            "bottom_right",
            "top_left",
            "recognitions"
          ],
          "additionalProperties": false,
          "description": "bounding box of the region of interest"
        },
        "video_skip_frame": {
          "type": "number",
          "description": "step between frames, only works for videos."
        },
        "mode": {
          "type": "string",
          "description": "specifies which object classes are recognized. It should be either `logo`, `object` or `full`."
        },
        "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",
        "roi",
        "video_skip_frame",
        "mode",
        "max_FPS",
        "follow_stream_rate",
        "status"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "stream"
  ]
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Get a specific stream
GET/streams/{stream_id}

Returns a json with the specified stream parameters.

URI Parameters
HideShow
stream_id
number (required) Example: 1

Stream identifier


PATCH http://localhost/warhol/streams/1
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "algo_type": "detection",
  "path": "stream.mp4",
  "stream_label": "test",
  "stream_type": "video",
  "detector_size": 130,
  "rotation": -2,
  "start_on_restart": false,
  "always_on": true,
  "roi": {
    "bottom_right": {
      "x": 0,
      "y": 0
    },
    "top_left": {
      "x": 0,
      "y": 0
    },
    "recognitions": [
      {
        "confidence": 0,
        "predicted_label": "name"
      }
    ]
  },
  "video_skip_frame": 30,
  "mode": "logo",
  "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."
    },
    "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
        },
        "recognitions": {
          "type": "array"
        }
      },
      "required": [
        "bottom_right",
        "top_left",
        "recognitions"
      ],
      "additionalProperties": false,
      "description": "bounding box of the region of interest"
    },
    "video_skip_frame": {
      "type": "number",
      "description": "step between frames, only works for videos."
    },
    "mode": {
      "type": "string",
      "description": "specifies which object classes are recognized. It should be either `logo`, `object` or `full`."
    },
    "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",
    "roi",
    "video_skip_frame",
    "mode",
    "max_FPS",
    "follow_stream_rate"
  ],
  "additionalProperties": false
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "stream": {
    "algo_type": "detection",
    "path": "/user_data/video/<YOUR_APP_KEY>/video.mp4",
    "stream_label": "test",
    "id": 7,
    "stream_type": "video",
    "detector_size": 130,
    "rotation": -2,
    "start_on_restart": false,
    "always_on": true,
    "roi": {
      "bottom_right": {
        "x": 0,
        "y": 0
      },
      "top_left": {
        "x": 0,
        "y": 0
      },
      "recognitions": [
        {
          "confidence": 0,
          "predicted_label": "name"
        }
      ]
    },
    "video_skip_frame": 30,
    "mode": "logo",
    "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."
        },
        "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
            },
            "recognitions": {
              "type": "array"
            }
          },
          "required": [
            "bottom_right",
            "top_left",
            "recognitions"
          ],
          "additionalProperties": false,
          "description": "bounding box of the region of interest"
        },
        "video_skip_frame": {
          "type": "number",
          "description": "step between frames, only works for videos."
        },
        "mode": {
          "type": "string",
          "description": "specifies which object classes are recognized. It should be either `logo`, `object` or `full`."
        },
        "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",
        "roi",
        "video_skip_frame",
        "mode",
        "max_FPS",
        "follow_stream_rate",
        "status"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "stream"
  ]
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Edit a stream
PATCH/streams/{stream_id}

Edit the parameters of the stream. You can the subset of parameters that you want to modify. For the options, you can change a single value of them and the system will merge it with the old values, if not overwritten.

URI Parameters
HideShow
stream_id
number (required) Example: 1

Stream identifier


GET http://localhost/warhol/streams
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "streams": [
    {
      "algo_type": "detection",
      "path": "/user_data/video/<YOUR_APP_KEY>/video.mp4",
      "stream_label": "test",
      "id": 7,
      "stream_type": "video",
      "detector_size": 130,
      "rotation": -2,
      "start_on_restart": false,
      "always_on": true,
      "roi": {
        "bottom_right": {
          "x": 0,
          "y": 0
        },
        "top_left": {
          "x": 0,
          "y": 0
        },
        "recognitions": [
          {
            "confidence": 0,
            "predicted_label": "name"
          }
        ]
      },
      "video_skip_frame": 30,
      "mode": "logo",
      "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."
          },
          "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
              },
              "recognitions": {
                "type": "array"
              }
            },
            "required": [
              "bottom_right",
              "top_left",
              "recognitions"
            ],
            "additionalProperties": false,
            "description": "bounding box of the region of interest"
          },
          "video_skip_frame": {
            "type": "number",
            "description": "step between frames, only works for videos."
          },
          "mode": {
            "type": "string",
            "description": "specifies which object classes are recognized. It should be either `logo`, `object` or `full`."
          },
          "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",
          "roi",
          "video_skip_frame",
          "mode",
          "max_FPS",
          "follow_stream_rate",
          "status"
        ],
        "additionalProperties": false
      }
    }
  }
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

List all streams
GET/streams

Returns the list of all streams.


GET http://localhost/warhol/streams/1/run
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses204401
This response has no content.

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Start running a stream
GET/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
HideShow
stream_id
number (required) Example: 1

GET http://localhost/warhol/streams/1/stop
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses204401
This response has no content.

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Stop a running stream
GET/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
HideShow
stream_id
number (required) Example: 1

GET http://localhost/warhol/streams/1/status
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "status": {
    "fps": 23.2,
    "status": "STOPPED",
    "description": ""
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "object",
      "properties": {
        "fps": {
          "type": "number",
          "description": "Framerate of the stream if its running"
        },
        "status": {
          "type": "string",
          "enum": [
            "STOPPED",
            "STARTING",
            "ERROR"
          ],
          "description": "The stream status"
        },
        "description": {
          "type": "string",
          "description": "error description when status is ERROR, can be ignored otherwise."
        }
      },
      "required": [
        "status",
        "description"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "status"
  ]
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Get the status of a stream
GET/streams/{stream_id}/status

Get the status of stream - it should be one of four values: STOPPED, STARTING, RUNNING or ERROR. It the stream is running it will also provide you the frames per seconds (FPS).

URI Parameters
HideShow
stream_id
number (required) Example: 1

DELETE http://localhost/warhol/streams/1
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses204
This response has no content.

Removing a stream
DELETE/streams/{stream_id}

Remove the stream using the stream_id.

URI Parameters
HideShow
stream_id
number (required) Example: 1

Stream identifier


Admin

The routes under this resource are the user setting preferences. It give 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 to true if you want to save JSON files with the stream results.

  • make_http_requests: set to true if you want to receive HTTP requests with stream results.

  • make_video_output: set to true if you want to write the video output to a file

  • video_options

    • max_video_mins: the maximum video duration in minutes
    • include_date_in_video: set to true to include date on the video
  • min_confidence: the minimum confidence value such as an output is created. Use this value to exclude from processing recognitions in which the system is not sure about.

  • Should you choose to use JSON files, you can provide json_options as follows:

    • batch_window: how many recognitions to group before creating a new JSON files
    • foldername: 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 to true if you want the stream date to be printed on the video as well.
    • make_raw_video_output: set to true if you want to store the raw stream (without any results drawings) as well.
GET http://localhost/warhol/admin/stream/output
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "stream_output_config": {
    "save_json": false,
    "make_http_requests": true,
    "make_video_output": true,
    "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"
        },
        "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",
        "video_options",
        "min_confidence",
        "json_options",
        "http_options"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "stream_output_config"
  ]
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Getting options
GET/admin/stream/output

Get the current stream output options.


POST http://localhost/warhol/admin/stream/output
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "save_json": false,
  "make_http_requests": true,
  "make_video_output": true,
  "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"
    },
    "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",
    "video_options",
    "min_confidence",
    "json_options",
    "http_options"
  ],
  "additionalProperties": false
}
Responses200422401
Headers
Content-Type: application/json
Body
{
  "stream_output_config": {
    "save_json": false,
    "make_http_requests": true,
    "make_video_output": true,
    "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"
        },
        "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",
        "video_options",
        "min_confidence",
        "json_options",
        "http_options"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "stream_output_config"
  ]
}

Invalid parameters. Check the message on payload to see what happened.

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Setting options
POST/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/warhol/admin/event/settings
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "event_settings": {
    "unique_win_seconds": 360,
    "webhook_active": true,
    "webhook_url": "http://somereachableurl:323/event_getter",
    "post_image": true,
    "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."
        },
        "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",
        "auto_clear",
        "max_age"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "event_settings"
  ]
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Getting event options
GET/admin/event/settings

Get the current options.


POST http://localhost/warhol/admin/event/settings
Requestsexample
Headers
Content-Type: application/json
Body
{
  "unique_win_seconds": 360,
  "webhook_active": true,
  "webhook_url": "http://somereachableurl:323/event_getter",
  "post_image": 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."
    },
    "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",
    "auto_clear",
    "max_age"
  ],
  "additionalProperties": false
}
Responses200422401
Body
{
  "event_settings": {
    "unique_win_seconds": 360,
    "webhook_active": true,
    "webhook_url": "http://somereachableurl:323/event_getter",
    "post_image": 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."
        },
        "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#"
}

Invalid parameters. Check the message on payload to see what happened.

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Setting event options
POST/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/warhol/event/1
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses200432401
Headers
Content-Type: application/json
Body
{
  "event": {
    "id": 23,
    "stream_id": 3,
    "stream_label": "camera1",
    "event_label": "Ernesto",
    "type": "TypeA",
    "date": "2018-10-02T00:53:24.955850Z",
    "confidence": 90.32,
    "thumbnail_url": "/images/image-cd323658-7077-4117-9dc3-055ab377f795.jpg",
    "image_url": "/images/image-b11f2b59-bce1-4fbf-8a95-9e07fc3b2f29",
    "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."
        },
        "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",
        "details"
      ],
      "additionalProperties": false
    }
  }
}
Headers
Content-Type: application/json
Body
Invalid event id
Headers
Content-Type: application/json
Body
No APIKey present or unauthorized

Get a specific event
GET/event/{event_id}

Fetches a single event from the database.

URI Parameters
HideShow
event_id
number (required) Example: 1

Event identifier


DELETE http://localhost/warhol/event/1
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses204432401
Headers
Content-Type: application/json
Headers
Content-Type: application/json
Body
Invalid event id
Headers
Content-Type: application/json
Body
No APIKey present or unauthorized

Delete a specific event
DELETE/event/{event_id}

Deletes a single event from the system, without recovery.

URI Parameters
HideShow
event_id
number (required) Example: 1

Event identifier


GET http://localhost/warhol/events/last?n_events=10
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses200422401
Headers
Content-Type: application/json
Body
{
  "last_events": [
    {
      "id": 23,
      "stream_id": 3,
      "stream_label": "camera1",
      "event_label": "Ernesto",
      "type": "TypeA",
      "date": "2018-10-02T00:53:24.955850Z",
      "confidence": 90.32,
      "thumbnail_url": "/images/image-cd323658-7077-4117-9dc3-055ab377f795.jpg",
      "image_url": "/images/image-b11f2b59-bce1-4fbf-8a95-9e07fc3b2f29",
      "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."
          },
          "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",
          "details"
        ],
        "additionalProperties": false
      }
    }
  }
}

Invalid parameters. Check the message on payload to see what happened.

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Getting the last events
GET/events/last{?n_events}

Get the last stored events from the system.

URI Parameters
HideShow
n_events
number (required) Example: 10

Last events to return.


GET http://localhost/warhol/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
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses200422401
Headers
Content-Type: application/json
Body
{
  "events": [
    {
      "id": 23,
      "stream_id": 3,
      "stream_label": "camera1",
      "event_label": "Ernesto",
      "type": "TypeA",
      "date": "2018-10-02T00:53:24.955850Z",
      "confidence": 90.32,
      "thumbnail_url": "/images/image-cd323658-7077-4117-9dc3-055ab377f795.jpg",
      "image_url": "/images/image-b11f2b59-bce1-4fbf-8a95-9e07fc3b2f29",
      "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."
          },
          "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",
          "details"
        ],
        "additionalProperties": false
      }
    }
  }
}

Invalid parameters. Check the message on payload to see what happened.

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Filtering events with pagination
GET/events{?page,per_page,like_event_label,type,stream_id,start_date,end_date,order_by,order_asc}

Filter the events, with pagination (required). You need to provide page (page number) and per_page (page size) values. Filtering options are as follow:

  • like_event_label: search for a portion of the label name.

  • type: string to filter events of this type (exact).

  • stream_id: specify the events of a single stream.

  • Specify a date range using start_date and end_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
HideShow
page
number (required) Example: 1

page number

per_page
number (required) Example: 10

page length

like_event_label
string (optional) Example: Ernest

search for a portion of the label name.

type
string (optional) Example: TypeA

filter events of this type (exact).

stream_id
number (optional) Example: 1

which stream has generate the event.

start_date
string (optional) Example: 2018-10-01T00:22:00.000000Z

ISO format start date for event.

end_date
string (optional) Example: 2018-10-02T00:22:00.000000Z

ISO format end date for event.

order_by
string (optional) Example: confidence

field to order by it. Default: event date.

order_asc
string (optional) Example: desc

ascending (asc) or descending (desc) order.


POST http://localhost/warhol/events/csv
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "like_event_label": "Ernest",
  "type": "TypeA",
  "stream_id": 1,
  "start_date": "2018-10-01T00:22:00.000000Z",
  "end_date": "2018-10-02T00:22:00.000000Z",
  "order_by": "confidence",
  "order_asc": "desc",
  "limit": 5000
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "like_event_label": {
      "type": "string",
      "description": "search for a portion of the label name."
    },
    "type": {
      "type": "string",
      "description": "filter events of this type (exact)."
    },
    "stream_id": {
      "type": "number",
      "description": "which stream has generate the event."
    },
    "start_date": {
      "type": "string",
      "description": "ISO format start date for event."
    },
    "end_date": {
      "type": "string",
      "description": "ISO format end date for event."
    },
    "order_by": {
      "type": "string",
      "description": "field to order by it. Default: event date."
    },
    "order_asc": {
      "type": "string",
      "description": "ascending (asc) or descending (desc) order."
    },
    "limit": {
      "type": "number",
      "description": "max number of rows to be included in the file"
    }
  }
}
Responses200422401
Headers
Content-Type: application/json
Body
{
  "file_url: `/warhol/export/<YOUR_APP_KEY>/warhol_events_2019": "Hello, world!"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "file_url: `/warhol/export/<YOUR_APP_KEY>/warhol_events_2019": {
      "type": "string",
      "description": "03-15T18:12:29.270355Z.csv` (string, fixed-type) - the url to download the path, relative to the Warhol host address"
    }
  }
}

Invalid parameters. Check the message on payload to see what happened.

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Export events CSV
POST/events/csv

Export events to a CSV file. Filtering options are as follow:

  • like_event_label: search for a portion of the label name.

  • type: string to filter events of this type (exact).

  • stream_id: specify the events of a single stream.

  • Specify a date range using start_date and end_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/warhol/events/clear_all
Requestsexample
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Responses204401
This response has no content.

No App Key present or unauthorized

Headers
Content-Type: application/json
Body
{
  "error": "Invalid arguments",
  "message": "The input field is invalid."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "error description."
    },
    "message": {
      "type": "string",
      "description": "details on what caused the error."
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Clear all events
DELETE/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/warhol/label_lists
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "name": "my list",
  "description": "fist list",
  "type": "streams",
  "labels": [
    "ash",
    "misty",
    "brock"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "labels": {
      "type": "array"
    }
  },
  "required": [
    "name",
    "labels"
  ]
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "lists": {
    "id": 1,
    "name": "test streams",
    "description": "test streams",
    "type": "stream",
    "updated_at": "20180925 14:35:31",
    "created_at": "20180925 14:35:31",
    "labels": [
      "ash",
      "misty",
      "brock"
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "lists": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "name": {
          "type": "string",
          "description": "Name of the list"
        },
        "description": {
          "type": "string",
          "description": "Description of the list"
        },
        "type": {
          "type": "string",
          "description": "Type of the list (unused)"
        },
        "updated_at": {
          "type": "string",
          "description": "date & time of last update"
        },
        "created_at": {
          "type": "string",
          "description": "date & time of creation"
        },
        "labels": {
          "type": "array",
          "description": "the labels in the list"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "type",
        "updated_at",
        "created_at",
        "labels"
      ],
      "additionalProperties": false
    }
  }
}

The provided app key is not autorized to create lists.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Create a list
POST/label_lists

Create a new list, containing the specified labels.


GET http://localhost/warhol/label_lists/1
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "list": {
    "id": 1,
    "name": "test streams",
    "description": "test streams",
    "type": "stream",
    "updated_at": "20180925 14:35:31",
    "created_at": "20180925 14:35:31",
    "labels": [
      "ash",
      "misty",
      "brock"
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "list": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "name": {
          "type": "string",
          "description": "Name of the list"
        },
        "description": {
          "type": "string",
          "description": "Description of the list"
        },
        "type": {
          "type": "string",
          "description": "Type of the list (unused)"
        },
        "updated_at": {
          "type": "string",
          "description": "date & time of last update"
        },
        "created_at": {
          "type": "string",
          "description": "date & time of creation"
        },
        "labels": {
          "type": "array",
          "description": "the labels in the list"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "type",
        "updated_at",
        "created_at",
        "labels"
      ],
      "additionalProperties": false
    }
  }
}

The provided app key is not autorized to access this list.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Retrieve a list
GET/label_lists/{list_id}

Returns an existing list.

URI Parameters
HideShow
list_id
int (required) Example: 1

The ID of the desired list


GET http://localhost/warhol/label_lists
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "lists": [
    {
      "id": 1,
      "name": "test streams",
      "description": "test streams",
      "type": "stream",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31",
      "labels": [
        "ash",
        "misty",
        "brock"
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "lists": {
      "type": "array"
    }
  }
}
Body
No APIKey present or unauthorized

Retrieve all lists
GET/label_lists

Returns all existing lists.


PATCH http://localhost/warhol/label_lists/1
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "name": "my list",
  "description": "fist list",
  "type": "streams",
  "labels": [
    "ash",
    "misty",
    "brock"
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "labels": {
      "type": "array"
    }
  }
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "list": {
    "id": 1,
    "name": "test streams",
    "description": "test streams",
    "type": "stream",
    "updated_at": "20180925 14:35:31",
    "created_at": "20180925 14:35:31",
    "labels": [
      "ash",
      "misty",
      "brock"
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "list": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "name": {
          "type": "string",
          "description": "Name of the list"
        },
        "description": {
          "type": "string",
          "description": "Description of the list"
        },
        "type": {
          "type": "string",
          "description": "Type of the list (unused)"
        },
        "updated_at": {
          "type": "string",
          "description": "date & time of last update"
        },
        "created_at": {
          "type": "string",
          "description": "date & time of creation"
        },
        "labels": {
          "type": "array",
          "description": "the labels in the list"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "type",
        "updated_at",
        "created_at",
        "labels"
      ],
      "additionalProperties": false
    }
  }
}

The provided app key is not autorized to access this list.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Edit a list
PATCH/label_lists/{list_id}

Partially update a list contents. If “labels” is sent, the new value will replace all previous list elements.

URI Parameters
HideShow
list_id
int (required) Example: 1

The ID of the desired list


DELETE http://localhost/warhol/label_lists/1
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses204401409
This response has no content.

The provided app key is not autorized to access this list.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Removing this element would result in a conlfict. Maybe other resource depends on this.

Headers
Content-Type: application/json
Body
{
  "error": "Existing Dependents",
  "message": "Cannot delete List because it's refered by one or more {Dependancies}."
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  }
}

Removes a list
DELETE/label_lists/{list_id}

URI Parameters
HideShow
list_id
int (required) Example: 1

The 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/warhol/alarms
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "description": "test streams",
  "combination_type": "ANY",
  "rules": [
    {
      "type": "weekdays",
      "negate": false,
      "start_time": "14:35:31",
      "timeout": "14:35:31",
      "weekdays": [
        0,
        6
      ],
      "min_confidence": "number",
      "label_list_id": 1,
      "event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": "Hello, world!",
      "stream_id": 5
    }
  ],
  "actions": [
    {
      "type": "email",
      "send_photo": false,
      "email": "meerkat@meerkat.com.br",
      "url": "http://www.myserver.com/meerkat/event",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "description": "Description of the alarm"
    },
    "combination_type": {
      "type": "string",
      "description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "`Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`"
          },
          "negate": {
            "type": "boolean",
            "description": "`Type of the list (unused)`"
          },
          "start_time": {
            "type": "string",
            "description": "`Alarm start hour`"
          },
          "timeout": {
            "type": "string",
            "description": "`Alarm timeout (max 24h)`"
          },
          "weekdays": {
            "type": "array",
            "description": "`day of the week the alarm will be active`"
          },
          "min_confidence": {
            "type": "string",
            "description": "`Minimal event confidence to trigger the alarm`"
          },
          "label_list_id": {
            "type": "number",
            "description": "`ID of label_list of event_labels that will trigger the alarm`"
          },
          "event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": {
            "type": "string"
          },
          "stream_id": {
            "type": "number",
            "description": "`ID of the stream that will trigger the alarm`"
          }
        },
        "required": [
          "type",
          "negate",
          "start_time",
          "timeout",
          "weekdays",
          "min_confidence",
          "label_list_id",
          "event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`",
          "stream_id"
        ],
        "additionalProperties": false
      },
      "description": "the conditions to trigger the alarm"
    },
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "`Type of action: email, webhook`"
          },
          "send_photo": {
            "type": "boolean",
            "description": "`set to True to attach a photo of the recognition event to the action call`"
          },
          "email": {
            "type": "string",
            "description": "`email rule destination`"
          },
          "url": {
            "type": "string",
            "description": "`webhook action URL`"
          },
          "updated_at": {
            "type": "string",
            "description": "`date & time of last update`"
          },
          "created_at": {
            "type": "string",
            "description": "`date & time of creation`"
          }
        },
        "required": [
          "type",
          "send_photo",
          "email",
          "url",
          "updated_at",
          "created_at"
        ],
        "additionalProperties": false
      },
      "description": "the actions to execute then the alarm is triggered"
    }
  },
  "required": [
    "combination_type",
    "rules",
    "actions"
  ]
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "alarm": {
    "id": 1,
    "description": "test streams",
    "combination_type": "ANY",
    "updated_at": "20180925 14:35:31",
    "created_at": "20180925 14:35:31",
    "rules": [
      {
        "id": 1,
        "type": "weekdays",
        "negate": false,
        "start_time": "14:35:31",
        "timeout": "14:35:31",
        "weekdays": [
          0,
          6
        ],
        "min_confidence": "number",
        "label_list_id": 1,
        "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
        "stream": {
          "id": 1,
          "label": "my little stream"
        },
        "list": {
          "id": 1,
          "name": "test streams",
          "description": "test streams",
          "type": "stream",
          "updated_at": "20180925 14:35:31",
          "created_at": "20180925 14:35:31",
          "labels": [
            "ash",
            "misty",
            "brock"
          ]
        },
        "updated_at": "20180925 14:35:31",
        "created_at": "20180925 14:35:31"
      }
    ],
    "actions": [
      {
        "id": 1,
        "type": "email",
        "send_photo": false,
        "email": "meerkat@meerkat.com.br",
        "url": "http://www.myserver.com/meerkat/event",
        "updated_at": "20180925 14:35:31",
        "created_at": "20180925 14:35:31"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "alarm": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "description": {
          "type": "string",
          "description": "Description of the alarm"
        },
        "combination_type": {
          "type": "string",
          "description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
        },
        "updated_at": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number"
              },
              "type": {
                "type": "string",
                "description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
              },
              "negate": {
                "type": "boolean",
                "description": "Type of the list (unused)"
              },
              "start_time": {
                "type": "string",
                "description": "Alarm start hour"
              },
              "timeout": {
                "type": "string",
                "description": "Alarm timeout (max 24h)"
              },
              "weekdays": {
                "type": "array",
                "description": "day of the week the alarm will be active"
              },
              "min_confidence": {
                "type": "string",
                "description": "Minimal event confidence to trigger the alarm"
              },
              "label_list_id": {
                "type": "number",
                "description": "ID of stream_label or event_label"
              },
              "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
                "type": "string"
              },
              "stream": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number",
                    "description": "stream ID"
                  },
                  "label": {
                    "type": "string",
                    "description": "name of the stream"
                  }
                },
                "required": [
                  "id",
                  "label"
                ],
                "additionalProperties": false,
                "description": "Data of the stream that will trigger the alarm"
              },
              "list": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "name": {
                    "type": "string",
                    "description": "Name of the list"
                  },
                  "description": {
                    "type": "string",
                    "description": "Description of the list"
                  },
                  "type": {
                    "type": "string",
                    "description": "Type of the list (unused)"
                  },
                  "updated_at": {
                    "type": "string",
                    "description": "date & time of last update"
                  },
                  "created_at": {
                    "type": "string",
                    "description": "date & time of creation"
                  },
                  "labels": {
                    "type": "array",
                    "description": "the labels in the list"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "description",
                  "type",
                  "updated_at",
                  "created_at",
                  "labels"
                ],
                "additionalProperties": false,
                "description": "the labels in the list"
              },
              "updated_at": {
                "type": "string",
                "description": "date & time of last update"
              },
              "created_at": {
                "type": "string",
                "description": "date & time of creation"
              }
            },
            "required": [
              "id",
              "type",
              "negate",
              "start_time",
              "timeout",
              "weekdays",
              "min_confidence",
              "label_list_id",
              "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
              "stream",
              "list",
              "updated_at",
              "created_at"
            ],
            "additionalProperties": false
          },
          "description": "the labels in the list"
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number"
              },
              "type": {
                "type": "string",
                "description": "Type of action: email, webhook"
              },
              "send_photo": {
                "type": "boolean",
                "description": "set to True to attach a photo of the recognition event to the action call"
              },
              "email": {
                "type": "string",
                "description": "email rule destination"
              },
              "url": {
                "type": "string",
                "description": "webhook action URL"
              },
              "updated_at": {
                "type": "string",
                "description": "date & time of last update"
              },
              "created_at": {
                "type": "string",
                "description": "date & time of creation"
              }
            },
            "required": [
              "id",
              "type",
              "send_photo",
              "email",
              "url",
              "updated_at",
              "created_at"
            ],
            "additionalProperties": false
          },
          "description": "the labels in the list"
        }
      },
      "required": [
        "id",
        "description",
        "combination_type",
        "updated_at",
        "created_at",
        "rules",
        "actions"
      ],
      "additionalProperties": false
    }
  }
}

The provided app key is not autorized to create alarms.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Create an alarm
POST/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/warhol/alarms/1
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "alarm": {
    "id": 1,
    "description": "test streams",
    "combination_type": "ANY",
    "updated_at": "20180925 14:35:31",
    "created_at": "20180925 14:35:31",
    "rules": [
      {
        "id": 1,
        "type": "weekdays",
        "negate": false,
        "start_time": "14:35:31",
        "timeout": "14:35:31",
        "weekdays": [
          0,
          6
        ],
        "min_confidence": "number",
        "label_list_id": 1,
        "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
        "stream": {
          "id": 1,
          "label": "my little stream"
        },
        "list": {
          "id": 1,
          "name": "test streams",
          "description": "test streams",
          "type": "stream",
          "updated_at": "20180925 14:35:31",
          "created_at": "20180925 14:35:31",
          "labels": [
            "ash",
            "misty",
            "brock"
          ]
        },
        "updated_at": "20180925 14:35:31",
        "created_at": "20180925 14:35:31"
      }
    ],
    "actions": [
      {
        "id": 1,
        "type": "email",
        "send_photo": false,
        "email": "meerkat@meerkat.com.br",
        "url": "http://www.myserver.com/meerkat/event",
        "updated_at": "20180925 14:35:31",
        "created_at": "20180925 14:35:31"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "alarm": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "description": {
          "type": "string",
          "description": "Description of the alarm"
        },
        "combination_type": {
          "type": "string",
          "description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
        },
        "updated_at": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number"
              },
              "type": {
                "type": "string",
                "description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
              },
              "negate": {
                "type": "boolean",
                "description": "Type of the list (unused)"
              },
              "start_time": {
                "type": "string",
                "description": "Alarm start hour"
              },
              "timeout": {
                "type": "string",
                "description": "Alarm timeout (max 24h)"
              },
              "weekdays": {
                "type": "array",
                "description": "day of the week the alarm will be active"
              },
              "min_confidence": {
                "type": "string",
                "description": "Minimal event confidence to trigger the alarm"
              },
              "label_list_id": {
                "type": "number",
                "description": "ID of stream_label or event_label"
              },
              "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
                "type": "string"
              },
              "stream": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number",
                    "description": "stream ID"
                  },
                  "label": {
                    "type": "string",
                    "description": "name of the stream"
                  }
                },
                "required": [
                  "id",
                  "label"
                ],
                "additionalProperties": false,
                "description": "Data of the stream that will trigger the alarm"
              },
              "list": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "name": {
                    "type": "string",
                    "description": "Name of the list"
                  },
                  "description": {
                    "type": "string",
                    "description": "Description of the list"
                  },
                  "type": {
                    "type": "string",
                    "description": "Type of the list (unused)"
                  },
                  "updated_at": {
                    "type": "string",
                    "description": "date & time of last update"
                  },
                  "created_at": {
                    "type": "string",
                    "description": "date & time of creation"
                  },
                  "labels": {
                    "type": "array",
                    "description": "the labels in the list"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "description",
                  "type",
                  "updated_at",
                  "created_at",
                  "labels"
                ],
                "additionalProperties": false,
                "description": "the labels in the list"
              },
              "updated_at": {
                "type": "string",
                "description": "date & time of last update"
              },
              "created_at": {
                "type": "string",
                "description": "date & time of creation"
              }
            },
            "required": [
              "id",
              "type",
              "negate",
              "start_time",
              "timeout",
              "weekdays",
              "min_confidence",
              "label_list_id",
              "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
              "stream",
              "list",
              "updated_at",
              "created_at"
            ],
            "additionalProperties": false
          },
          "description": "the labels in the list"
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number"
              },
              "type": {
                "type": "string",
                "description": "Type of action: email, webhook"
              },
              "send_photo": {
                "type": "boolean",
                "description": "set to True to attach a photo of the recognition event to the action call"
              },
              "email": {
                "type": "string",
                "description": "email rule destination"
              },
              "url": {
                "type": "string",
                "description": "webhook action URL"
              },
              "updated_at": {
                "type": "string",
                "description": "date & time of last update"
              },
              "created_at": {
                "type": "string",
                "description": "date & time of creation"
              }
            },
            "required": [
              "id",
              "type",
              "send_photo",
              "email",
              "url",
              "updated_at",
              "created_at"
            ],
            "additionalProperties": false
          },
          "description": "the labels in the list"
        }
      },
      "required": [
        "id",
        "description",
        "combination_type",
        "updated_at",
        "created_at",
        "rules",
        "actions"
      ],
      "additionalProperties": false
    }
  }
}
Headers
Content-Type: application/json
Body
The provided app key is not autorized to access this alarm.

Get an alarm
GET/alarms/{alarm_id}

Returns an existing alarm.

URI Parameters
HideShow
alarm_id
int (required) Example: 1

The ID of the desired alarm


GET http://localhost/warhol/alarms
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200
Headers
Content-Type: application/json
Body
{
  "alarms": [
    {
      "id": 1,
      "description": "test streams",
      "combination_type": "ANY",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31",
      "rules": [
        {
          "id": 1,
          "type": "weekdays",
          "negate": false,
          "start_time": "14:35:31",
          "timeout": "14:35:31",
          "weekdays": [
            0,
            6
          ],
          "min_confidence": "number",
          "label_list_id": 1,
          "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
          "stream": {
            "id": 1,
            "label": "my little stream"
          },
          "list": {
            "id": 1,
            "name": "test streams",
            "description": "test streams",
            "type": "stream",
            "updated_at": "20180925 14:35:31",
            "created_at": "20180925 14:35:31",
            "labels": [
              "ash",
              "misty",
              "brock"
            ]
          },
          "updated_at": "20180925 14:35:31",
          "created_at": "20180925 14:35:31"
        }
      ],
      "actions": [
        {
          "id": 1,
          "type": "email",
          "send_photo": false,
          "email": "meerkat@meerkat.com.br",
          "url": "http://www.myserver.com/meerkat/event",
          "updated_at": "20180925 14:35:31",
          "created_at": "20180925 14:35:31"
        }
      ]
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "alarms": {
      "type": "array"
    }
  }
}

Get all alarms
GET/alarms

Returns an existing list.


PATCH http://localhost/warhol/alarms/1
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "description": "test streams",
  "combination_type": "ANY",
  "rules": [
    {
      "type": "weekdays",
      "negate": false,
      "start_time": "14:35:31",
      "timeout": "14:35:31",
      "weekdays": [
        0,
        6
      ],
      "min_confidence": "number",
      "label_list_id": 1,
      "event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": "Hello, world!",
      "stream_id": 5
    }
  ],
  "actions": [
    {
      "type": "email",
      "send_photo": false,
      "email": "meerkat@meerkat.com.br",
      "url": "http://www.myserver.com/meerkat/event",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "description": "Description of the alarm"
    },
    "combination_type": {
      "type": "string",
      "description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
    },
    "rules": {
      "type": "array",
      "description": "the labels in the list"
    },
    "actions": {
      "type": "array",
      "description": "the labels in the list"
    }
  },
  "required": [
    "description",
    "combination_type",
    "rules",
    "actions"
  ]
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "alarm": {
    "id": 1,
    "description": "test streams",
    "combination_type": "ANY",
    "updated_at": "20180925 14:35:31",
    "created_at": "20180925 14:35:31",
    "rules": [
      {
        "id": 1,
        "type": "weekdays",
        "negate": false,
        "start_time": "14:35:31",
        "timeout": "14:35:31",
        "weekdays": [
          0,
          6
        ],
        "min_confidence": "number",
        "label_list_id": 1,
        "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
        "stream": {
          "id": 1,
          "label": "my little stream"
        },
        "list": {
          "id": 1,
          "name": "test streams",
          "description": "test streams",
          "type": "stream",
          "updated_at": "20180925 14:35:31",
          "created_at": "20180925 14:35:31",
          "labels": [
            "ash",
            "misty",
            "brock"
          ]
        },
        "updated_at": "20180925 14:35:31",
        "created_at": "20180925 14:35:31"
      }
    ],
    "actions": [
      {
        "id": 1,
        "type": "email",
        "send_photo": false,
        "email": "meerkat@meerkat.com.br",
        "url": "http://www.myserver.com/meerkat/event",
        "updated_at": "20180925 14:35:31",
        "created_at": "20180925 14:35:31"
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "alarm": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "description": {
          "type": "string",
          "description": "Description of the alarm"
        },
        "combination_type": {
          "type": "string",
          "description": "How to combine the rules: ALL rule must be satisfied, ANY rule must be satisfied, ALLWAYS trigger this alarm"
        },
        "updated_at": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number"
              },
              "type": {
                "type": "string",
                "description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
              },
              "negate": {
                "type": "boolean",
                "description": "Type of the list (unused)"
              },
              "start_time": {
                "type": "string",
                "description": "Alarm start hour"
              },
              "timeout": {
                "type": "string",
                "description": "Alarm timeout (max 24h)"
              },
              "weekdays": {
                "type": "array",
                "description": "day of the week the alarm will be active"
              },
              "min_confidence": {
                "type": "string",
                "description": "Minimal event confidence to trigger the alarm"
              },
              "label_list_id": {
                "type": "number",
                "description": "ID of stream_label or event_label"
              },
              "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
                "type": "string"
              },
              "stream": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number",
                    "description": "stream ID"
                  },
                  "label": {
                    "type": "string",
                    "description": "name of the stream"
                  }
                },
                "required": [
                  "id",
                  "label"
                ],
                "additionalProperties": false,
                "description": "Data of the stream that will trigger the alarm"
              },
              "list": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "name": {
                    "type": "string",
                    "description": "Name of the list"
                  },
                  "description": {
                    "type": "string",
                    "description": "Description of the list"
                  },
                  "type": {
                    "type": "string",
                    "description": "Type of the list (unused)"
                  },
                  "updated_at": {
                    "type": "string",
                    "description": "date & time of last update"
                  },
                  "created_at": {
                    "type": "string",
                    "description": "date & time of creation"
                  },
                  "labels": {
                    "type": "array",
                    "description": "the labels in the list"
                  }
                },
                "required": [
                  "id",
                  "name",
                  "description",
                  "type",
                  "updated_at",
                  "created_at",
                  "labels"
                ],
                "additionalProperties": false,
                "description": "the labels in the list"
              },
              "updated_at": {
                "type": "string",
                "description": "date & time of last update"
              },
              "created_at": {
                "type": "string",
                "description": "date & time of creation"
              }
            },
            "required": [
              "id",
              "type",
              "negate",
              "start_time",
              "timeout",
              "weekdays",
              "min_confidence",
              "label_list_id",
              "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
              "stream",
              "list",
              "updated_at",
              "created_at"
            ],
            "additionalProperties": false
          },
          "description": "the labels in the list"
        },
        "actions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "number"
              },
              "type": {
                "type": "string",
                "description": "Type of action: email, webhook"
              },
              "send_photo": {
                "type": "boolean",
                "description": "set to True to attach a photo of the recognition event to the action call"
              },
              "email": {
                "type": "string",
                "description": "email rule destination"
              },
              "url": {
                "type": "string",
                "description": "webhook action URL"
              },
              "updated_at": {
                "type": "string",
                "description": "date & time of last update"
              },
              "created_at": {
                "type": "string",
                "description": "date & time of creation"
              }
            },
            "required": [
              "id",
              "type",
              "send_photo",
              "email",
              "url",
              "updated_at",
              "created_at"
            ],
            "additionalProperties": false
          },
          "description": "the labels in the list"
        }
      },
      "required": [
        "id",
        "description",
        "combination_type",
        "updated_at",
        "created_at",
        "rules",
        "actions"
      ],
      "additionalProperties": false
    }
  }
}

The provided app key is not autorized to access this alarm.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Edit an alarm
PATCH/alarms/{alarm_id}

Partially update an alarm. If rules or actions sent in this route will replace existing ones.

URI Parameters
HideShow
alarm_id
int (required) Example: 1

The ID of the desired alarm


DELETE http://localhost/warhol/alarms/1
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses204401
Headers
Content-Type: application/json

The provided app key is not autorized to access this alarm.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Remove an alarm
DELETE/alarms/{alarm_id}

URI Parameters
HideShow
alarm_id
int (required) Example: 1

The ID of the desired alarm


GET http://localhost/warhol/alarms/1/rules
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "rules": [
    {
      "id": 1,
      "type": "weekdays",
      "negate": false,
      "start_time": "14:35:31",
      "timeout": "14:35:31",
      "weekdays": [
        0,
        6
      ],
      "min_confidence": "number",
      "label_list_id": 1,
      "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
      "stream": {
        "id": 1,
        "label": "my little stream"
      },
      "list": {
        "id": 1,
        "name": "test streams",
        "description": "test streams",
        "type": "stream",
        "updated_at": "20180925 14:35:31",
        "created_at": "20180925 14:35:31",
        "labels": [
          "ash",
          "misty",
          "brock"
        ]
      },
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "rules": {
      "type": "array"
    }
  }
}

The provided app key is not autorized to access this rule.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

List alarm rules
GET/alarms/{alarm_id}/rules

Returns all the rules associated with an existing alarm.

URI Parameters
HideShow
alarm_id
int (required) Example: 1

The ID of the desired alarm


POST http://localhost/warhol/alarms/1/rules
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "type": "weekdays",
  "negate": false,
  "start_time": "14:35:31",
  "timeout": "14:35:31",
  "weekdays": [
    0,
    6
  ],
  "min_confidence": "number",
  "label_list_id": 1,
  "event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": "Hello, world!",
  "stream_id": 5
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "`Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`"
    },
    "negate": {
      "type": "boolean",
      "description": "`Type of the list (unused)`"
    },
    "start_time": {
      "type": "string",
      "description": "`Alarm start hour`"
    },
    "timeout": {
      "type": "string",
      "description": "`Alarm timeout (max 24h)`"
    },
    "weekdays": {
      "type": "array",
      "description": "`day of the week the alarm will be active`"
    },
    "min_confidence": {
      "type": "string",
      "description": "`Minimal event confidence to trigger the alarm`"
    },
    "label_list_id": {
      "type": "number",
      "description": "`ID of label_list of event_labels that will trigger the alarm`"
    },
    "event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`": {
      "type": "string"
    },
    "stream_id": {
      "type": "number",
      "description": "`ID of the stream that will trigger the alarm`"
    }
  },
  "required": [
    "type",
    "negate",
    "start_time",
    "timeout",
    "weekdays",
    "min_confidence",
    "label_list_id",
    "event_label: `misty` (string) - `Type of rule: min_confidence, stream_label, event_label, time_range, weekdays`",
    "stream_id"
  ],
  "additionalProperties": false
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "rule": {
    "id": 1,
    "type": "weekdays",
    "negate": false,
    "start_time": "14:35:31",
    "timeout": "14:35:31",
    "weekdays": [
      0,
      6
    ],
    "min_confidence": "number",
    "label_list_id": 1,
    "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
    "stream": {
      "id": 1,
      "label": "my little stream"
    },
    "list": {
      "id": 1,
      "name": "test streams",
      "description": "test streams",
      "type": "stream",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31",
      "labels": [
        "ash",
        "misty",
        "brock"
      ]
    },
    "updated_at": "20180925 14:35:31",
    "created_at": "20180925 14:35:31"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "rule": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "type": {
          "type": "string",
          "description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
        },
        "negate": {
          "type": "boolean",
          "description": "Type of the list (unused)"
        },
        "start_time": {
          "type": "string",
          "description": "Alarm start hour"
        },
        "timeout": {
          "type": "string",
          "description": "Alarm timeout (max 24h)"
        },
        "weekdays": {
          "type": "array",
          "description": "day of the week the alarm will be active"
        },
        "min_confidence": {
          "type": "string",
          "description": "Minimal event confidence to trigger the alarm"
        },
        "label_list_id": {
          "type": "number",
          "description": "ID of stream_label or event_label"
        },
        "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
          "type": "string"
        },
        "stream": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "stream ID"
            },
            "label": {
              "type": "string",
              "description": "name of the stream"
            }
          },
          "required": [
            "id",
            "label"
          ],
          "additionalProperties": false,
          "description": "Data of the stream that will trigger the alarm"
        },
        "list": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number"
            },
            "name": {
              "type": "string",
              "description": "Name of the list"
            },
            "description": {
              "type": "string",
              "description": "Description of the list"
            },
            "type": {
              "type": "string",
              "description": "Type of the list (unused)"
            },
            "updated_at": {
              "type": "string",
              "description": "date & time of last update"
            },
            "created_at": {
              "type": "string",
              "description": "date & time of creation"
            },
            "labels": {
              "type": "array",
              "description": "the labels in the list"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "type",
            "updated_at",
            "created_at",
            "labels"
          ],
          "additionalProperties": false,
          "description": "the labels in the list"
        },
        "updated_at": {
          "type": "string",
          "description": "date & time of last update"
        },
        "created_at": {
          "type": "string",
          "description": "date & time of creation"
        }
      },
      "required": [
        "id",
        "type",
        "negate",
        "start_time",
        "timeout",
        "weekdays",
        "min_confidence",
        "label_list_id",
        "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
        "stream",
        "list",
        "updated_at",
        "created_at"
      ],
      "additionalProperties": false
    }
  }
}

The provided app key is not autorized to create rules.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Add alarm rule
POST/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 after start_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: uses min_confidence

  • type=stream_label: uses stream_id

  • type=event_label: uses label_list_id and event_label

  • type=time_range: uses start_time and timeout

  • type=weekdays: uses weekdays

URI Parameters
HideShow
alarm_id
int (required) Example: 1

The ID of the desired alarm


GET http://localhost/warhol/alarms/1/actions
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "actions": [
    {
      "id": 1,
      "type": "email",
      "send_photo": false,
      "email": "meerkat@meerkat.com.br",
      "url": "http://www.myserver.com/meerkat/event",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "actions": {
      "type": "array"
    }
  }
}

The provided app key is not autorized to access this rule.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

List alarm actions
GET/alarms/{alarm_id}/actions

URI Parameters
HideShow
alarm_id
int (required) Example: 1

The ID of the desired alarm


POST http://localhost/warhol/alarms/1/actions
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "type": "email",
  "send_photo": false,
  "email": "meerkat@meerkat.com.br",
  "url": "http://www.myserver.com/meerkat/event",
  "updated_at": "20180925 14:35:31",
  "created_at": "20180925 14:35:31"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "`Type of action: email, webhook`"
    },
    "send_photo": {
      "type": "boolean",
      "description": "`set to True to attach a photo of the recognition event to the action call`"
    },
    "email": {
      "type": "string",
      "description": "`email rule destination`"
    },
    "url": {
      "type": "string",
      "description": "`webhook action URL`"
    },
    "updated_at": {
      "type": "string",
      "description": "`date & time of last update`"
    },
    "created_at": {
      "type": "string",
      "description": "`date & time of creation`"
    }
  },
  "required": [
    "type",
    "send_photo",
    "email",
    "url",
    "updated_at",
    "created_at"
  ],
  "additionalProperties": false
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "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/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Add action
POST/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: uses email

  • type=webhook: uses url

URI Parameters
HideShow
alarm_id
int (required) Example: 1

The ID of the desired alarm


Alarm rules

Directly manipulates alarm rules.

GET http://localhost/warhol/alarms/rules/1
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "rule": {
    "id": 1,
    "type": "weekdays",
    "negate": false,
    "start_time": "14:35:31",
    "timeout": "14:35:31",
    "weekdays": [
      0,
      6
    ],
    "min_confidence": "number",
    "label_list_id": 1,
    "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
    "stream": {
      "id": 1,
      "label": "my little stream"
    },
    "list": {
      "id": 1,
      "name": "test streams",
      "description": "test streams",
      "type": "stream",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31",
      "labels": [
        "ash",
        "misty",
        "brock"
      ]
    },
    "updated_at": "20180925 14:35:31",
    "created_at": "20180925 14:35:31"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "rule": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "type": {
          "type": "string",
          "description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
        },
        "negate": {
          "type": "boolean",
          "description": "Type of the list (unused)"
        },
        "start_time": {
          "type": "string",
          "description": "Alarm start hour"
        },
        "timeout": {
          "type": "string",
          "description": "Alarm timeout (max 24h)"
        },
        "weekdays": {
          "type": "array",
          "description": "day of the week the alarm will be active"
        },
        "min_confidence": {
          "type": "string",
          "description": "Minimal event confidence to trigger the alarm"
        },
        "label_list_id": {
          "type": "number",
          "description": "ID of stream_label or event_label"
        },
        "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
          "type": "string"
        },
        "stream": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "stream ID"
            },
            "label": {
              "type": "string",
              "description": "name of the stream"
            }
          },
          "required": [
            "id",
            "label"
          ],
          "additionalProperties": false,
          "description": "Data of the stream that will trigger the alarm"
        },
        "list": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number"
            },
            "name": {
              "type": "string",
              "description": "Name of the list"
            },
            "description": {
              "type": "string",
              "description": "Description of the list"
            },
            "type": {
              "type": "string",
              "description": "Type of the list (unused)"
            },
            "updated_at": {
              "type": "string",
              "description": "date & time of last update"
            },
            "created_at": {
              "type": "string",
              "description": "date & time of creation"
            },
            "labels": {
              "type": "array",
              "description": "the labels in the list"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "type",
            "updated_at",
            "created_at",
            "labels"
          ],
          "additionalProperties": false,
          "description": "the labels in the list"
        },
        "updated_at": {
          "type": "string",
          "description": "date & time of last update"
        },
        "created_at": {
          "type": "string",
          "description": "date & time of creation"
        }
      },
      "required": [
        "id",
        "type",
        "negate",
        "start_time",
        "timeout",
        "weekdays",
        "min_confidence",
        "label_list_id",
        "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
        "stream",
        "list",
        "updated_at",
        "created_at"
      ],
      "additionalProperties": false
    }
  }
}

The provided app key is not autorized to access this rule.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Get a specific alarm rule
GET/alarms/rules/{rule_id}

URI Parameters
HideShow
rule_id
int (required) Example: 1

The ID of the desired rule


PATCH http://localhost/warhol/alarms/rules/1
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "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"
    }
  }
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "rule": {
    "id": 1,
    "type": "weekdays",
    "negate": false,
    "start_time": "14:35:31",
    "timeout": "14:35:31",
    "weekdays": [
      0,
      6
    ],
    "min_confidence": "number",
    "label_list_id": 1,
    "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": "Hello, world!",
    "stream": {
      "id": 1,
      "label": "my little stream"
    },
    "list": {
      "id": 1,
      "name": "test streams",
      "description": "test streams",
      "type": "stream",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31",
      "labels": [
        "ash",
        "misty",
        "brock"
      ]
    },
    "updated_at": "20180925 14:35:31",
    "created_at": "20180925 14:35:31"
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "rule": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "type": {
          "type": "string",
          "description": "Type of rule: min_confidence, stream_label, event_label, time_range, weekdays"
        },
        "negate": {
          "type": "boolean",
          "description": "Type of the list (unused)"
        },
        "start_time": {
          "type": "string",
          "description": "Alarm start hour"
        },
        "timeout": {
          "type": "string",
          "description": "Alarm timeout (max 24h)"
        },
        "weekdays": {
          "type": "array",
          "description": "day of the week the alarm will be active"
        },
        "min_confidence": {
          "type": "string",
          "description": "Minimal event confidence to trigger the alarm"
        },
        "label_list_id": {
          "type": "number",
          "description": "ID of stream_label or event_label"
        },
        "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm": {
          "type": "string"
        },
        "stream": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number",
              "description": "stream ID"
            },
            "label": {
              "type": "string",
              "description": "name of the stream"
            }
          },
          "required": [
            "id",
            "label"
          ],
          "additionalProperties": false,
          "description": "Data of the stream that will trigger the alarm"
        },
        "list": {
          "type": "object",
          "properties": {
            "id": {
              "type": "number"
            },
            "name": {
              "type": "string",
              "description": "Name of the list"
            },
            "description": {
              "type": "string",
              "description": "Description of the list"
            },
            "type": {
              "type": "string",
              "description": "Type of the list (unused)"
            },
            "updated_at": {
              "type": "string",
              "description": "date & time of last update"
            },
            "created_at": {
              "type": "string",
              "description": "date & time of creation"
            },
            "labels": {
              "type": "array",
              "description": "the labels in the list"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "type",
            "updated_at",
            "created_at",
            "labels"
          ],
          "additionalProperties": false,
          "description": "the labels in the list"
        },
        "updated_at": {
          "type": "string",
          "description": "date & time of last update"
        },
        "created_at": {
          "type": "string",
          "description": "date & time of creation"
        }
      },
      "required": [
        "id",
        "type",
        "negate",
        "start_time",
        "timeout",
        "weekdays",
        "min_confidence",
        "label_list_id",
        "event_label: `jotaro kujo` (string) - a single event_labels that will trigger the alarm",
        "stream",
        "list",
        "updated_at",
        "created_at"
      ],
      "additionalProperties": false
    }
  }
}

The provided app key is not autorized to access this rule.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Edit a rule
PATCH/alarms/rules/{rule_id}

URI Parameters
HideShow
rule_id
int (required) Example: 1

The ID of the desired rule


DELETE http://localhost/warhol/alarms/rules/1
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses204401409
Headers
Content-Type: application/json

The provided app key is not autorized to access this rule.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Removing this element would result in a conlfict. Maybe other resource depends on this.

Headers
Content-Type: application/json
Body
{
  "error": "Existing Dependents",
  "message": "Cannot delete 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 rule
DELETE/alarms/rules/{rule_id}

URI Parameters
HideShow
rule_id
int (required) Example: 1

The ID of the desired rule


Actions

Manipulate alarm actions directly by is action_id.

GET http://localhost/warhol/alarms/actions/1
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "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/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Get an action
GET/alarms/actions/{action_id}

URI Parameters
HideShow
action_id
int (required) Example: 1

The ID of the desired action


PATCH http://localhost/warhol/alarms/actions/1
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "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"
    }
  }
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "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/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Edit an action
PATCH/alarms/actions/{action_id}

URI Parameters
HideShow
action_id
int (required) Example: 1

The ID of the desired action


DELETE http://localhost/warhol/alarms/actions/1
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses204401409
Headers
Content-Type: application/json

The provided app key is not authorized to perform this action.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Removing this element would result in a conlfict. Maybe other resource depends on this.

Headers
Content-Type: application/json
Body
{
  "error": "Existing Dependents",
  "message": "Cannot delete 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"
    }
  }
}

Delete Action
DELETE/alarms/actions/{action_id}

Removes an existing alarm action.

URI Parameters
HideShow
action_id
int (required) Example: 1

The ID of the desired action


Triggers

Alarm triggers are the log of the times in which all the alarms set off. Basically, each log entry contains a timestamp, the event that triggered the alarm and a description of the actions that took place.

GET http://localhost/warhol/alarms/1/triggered
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "triggers": [
    {
      "id": 1,
      "executed_at": "20180925 14:35:31",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31",
      "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"
          }
        ]
      },
      "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",
        "details": "{...}"
      },
      "description": "Email sent to meerkat@meerkat.com.br"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "triggers": {
      "type": "array"
    }
  }
}

The provided app key is not autorized to access this rule.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Read Triggers
GET/alarms/{alarm_id}/triggered

Returns the list of all actions executed due the referred alarm.

URI Parameters
HideShow
alarm_id
int (required) Example: 1

The ID of the desired alarm


GET http://localhost/warhol/events/1/triggered
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200401
Headers
Content-Type: application/json
Body
{
  "triggers": [
    {
      "id": 1,
      "executed_at": "20180925 14:35:31",
      "updated_at": "20180925 14:35:31",
      "created_at": "20180925 14:35:31",
      "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"
          }
        ]
      },
      "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",
        "details": "{...}"
      },
      "description": "Email sent to meerkat@meerkat.com.br"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "triggers": {
      "type": "array"
    }
  }
}

The provided app key is not autorized to access this rule.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Read Triggers by Event
GET/events/{event_id}/triggered

Returns the list of all actions executed due the referred event.

URI Parameters
HideShow
event_id
int (required) Example: 1

The ID of the desired event


User

These routes return information about the user account, such as name, company, subscription date and quotas.

IMPORTANT: Some of these routes are only available on CLOUD.

Users

GET http://localhost/warhol/user/me
Requestsexample 1
Headers
Authorization: Basic <credentials>
Responses200
Headers
Content-Type: application/json
Body
{
  "fullname": "Henri Poincaré",
  "app_key": "abcd1234efgh5678ijkl9010mnop1112"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "fullname": {
      "type": "string",
      "description": "user full name"
    },
    "app_key": {
      "type": "string",
      "description": "`user app_key`"
    }
  }
}

Read Basic User Data
GET/user/me

IMPORTANT: This route is only available on CLOUD.

Retrieves the basic account information.

This route requires user authentication via the Basic Auth protocol, where the credentials is the base64 encoding of “username:password” (without the quotes).


GET http://localhost/warhol/user/quotas
Requestsexample 1
Headers
app_key: YOUR_APP_KEY
Responses200
Headers
Content-Type: application/json
Body
{
  "max_num_calls": 1000,
  "num_calls": 0,
  "max_stream_minutes": 60,
  "stream_minutes": 0,
  "subscription_date": "2019-01-20 19:55:18.356230",
  "last_reset_date": "2019-02-20 19:55:18.356230",
  "reset_frequency": 30,
  "calls_cost": 0,
  "app_key": "YOUR_APP_KEY"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "max_num_calls": {
      "type": "number",
      "description": "total of API calls allowed per quota cycle"
    },
    "num_calls": {
      "type": "number",
      "description": "total of API calls used in the current cycle"
    },
    "max_stream_minutes": {
      "type": "number",
      "description": "total of stream processing time allowed per quota cycle (in minutes)"
    },
    "stream_minutes": {
      "type": "number",
      "description": "total of stream processing time used in the current cycle (in minutes)"
    },
    "subscription_date": {
      "type": "string",
      "description": "account creation date"
    },
    "last_reset_date": {
      "type": "string",
      "description": "date of current quota cycle start"
    },
    "reset_frequency": {
      "type": "number",
      "description": "duration of quota cycle (in days)"
    },
    "calls_cost": {
      "type": "number",
      "description": "total of stream processing time used in the current cycle (in minutes)"
    },
    "app_key": {
      "type": "string",
      "description": "`user app_key`"
    }
  }
}

Read User Quotas
GET/user/quotas

Retrieves the quota information for the requested account.

Note that reset_frequency usually indicates the plan renew interval in days, but when reset_frequency == 30, the account will be instead renewed monthly, at the day that matches the subscription date (or the next working day, when applicable).


POST http://localhost/warhol/user/admin
Requestsexample 1
Headers
Content-Type: application/json
app_key: YOUR_APP_KEY
Body
{
  "email": "myemail@mycompany.com",
  "password": "mypassword"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Credential used to access the webapp"
    },
    "password": {
      "type": "string",
      "description": "Password used to access the system"
    }
  }
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "email": "myemail@mycompany.com",
  "password": "mypassword"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Credential used to access the webapp"
    },
    "password": {
      "type": "string",
      "description": "Password used to access the system"
    }
  }
}

The provided app key is not autorized.

Headers
Content-Type: application/json
Body
{
  "error": "Unauthorized access",
  "message": "error details"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "description": "Error Name"
    },
    "message": {
      "type": "string",
      "description": "Error Details"
    }
  },
  "required": [
    "error",
    "message"
  ],
  "additionalProperties": false
}

Set Admin User
POST/user/admin

Set admin login credentials. Once it is set, the webapp will always require login.


Generated by aglio on 06 Apr 2020