Snarl Network Protocol

View the Project on GitHub

Warning This is provisional documentation. Applications should not attempt to implement any features listed in this document, other than for development or testing purposes. The documentation is provided for open access to encourage interest in forthcoming features and to solicit feedback and suggestions. It is therefore provided “as is” and is subject to ongoing change and revision.

  1. Overview
  2. Objects
  3. Endpoints


Base URI

The base URI for SNP/HTTP V2 is /v2. So, if Snarl is running on host ninja, and it’s listening for SNP/HTTP on port 4444, an example call would be:



POST requests require a request body that is formatted as JSON. All responses (except when calling the root endpoint) are formatted as JSON.


With the exception of /authorise, every request must include an access_token as an argument within the URL query. For example:

GET http://ninja:4444/v2/notifications?access_token=00000001


All POST requests must set Content-Type to application/json. Other than that, no specific headers are required.



Every request generates the same response. The response will contain two objects:

Example Success Response

  "meta": {
    "code": 201,
    "text": "Created"
  "data": {
    "id": "a7fdb4de-e462-4866-89ce-7b4d28929255"

Example Failure Response

  "meta": {
    "code": 404,
    "text": "NotFound",
    "reason": "Application '' isn't registered."
  "data": {}


Object Description
application Describes a particular application registration
applications Contains an array of application objects
data Response data object
event Describes a single event class
events Contains an array of event objects
meta Response metadata
notification Describes a particular notification
notifications Contains a list of notification objects


The following endpoints are currently defined:

Endpoint Description
/apps Manages application registrations
/events Manages application event creations and deletions
/notifications Manages notifications
/info Returns information about the running instance of Snarl