The Envoy API gives you full access to Envoy via HTTP. Every aspect of Envoy can be controled via the API.

Version Prefix

All API routes are prefixed with /api/

This documentation is only for the v1 API


Current transport method supported is HTTP. TLS connections will be added soon.


If a proxy is available in your enterprise, before starting Envoy, set the following variables:

https_proxy=<IP:HTTPS_PORT_OF_PROXY >
Envoy will use those variables to access resources outside your enterprise.


All requests to the Envoy API require a client token. On the profile page you will find an API key. Use your username and the API key to access the API.

curl -H "X-Envoy-User: YOURUSERNAME" -H "X-Envoy-Key: APIKEY"
The returned JSON looks similar to:
{ "status":"OK" }

Error response

A common JSON structure is always returned to represent errors:

{ "code": "400", "message": "error message", "error": "the error" }

This structure will be sent for any HTTP status greater than or equal to 400

Time information

Some requests allow for specifying time information. Explicitly provide an ISO 8601 timestamp with timezone information. These timestamps look something like 2016-02-01T24:03:03+01:00 The timezone is not specified, because the timezone used all over the system is UTC.

HTTP Status Codes

The following HTTP status codes are used for the API:

  • 200 - Success with data
  • 204 - Success with no data
  • 400 - Invalid request, missing or invalid data
  • 403 - Forbidden, you authentication details are either incorrect or you do not have acess to this feature
  • 404 - Invalid path, meaning the path requested does not exist, or you do not have permission to see it. This prevents leakage of information
  • 409 - Conflict. Usually generated if a name is already used
  • 429 - Rate limiting exceeded. Try again after waiting some period of time
  • 500 - Internal server error. An internal error has occured, try again later. If error persists, report a bug