NAV Navbar
shell
  • Introduction
  • Authentication
  • Headers
  • Filtering, paging and sorting
  • Channels
  • Events
  • Errors
  • Support
  • Introduction

    This document outlines the API for Loggable. Loggable is a platform that provides centralized administrative logging and alerting.

    Using this API, you can create, manage, and view all of your channels and events. Alerts are currently not supported. To manage your alerts, log in to your account and use the provided interface.

    This API is built using the JSON API specification. If you are not familiar with this specification, it's recommended that you review it in order to learn about the comprehensive functionality that is available.

    Authentication

    To authenticate, use this code:

    # Authentication via a header
    curl "https://app.loggable.io/api/event"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
    
    # Authentication via a query parameter
    curl "https://app.loggable.io/api/event?api-key=01338aabfd8ef5bff253421ed78d38c0"
    

    Make sure to replace this key with your own API key.

    You can easily authenicate with the API using either a header or a query parameter to supply your account's API key.

    To get and manage your API key, navigate to the key authentication page in the application.

    Authenticate via a header:

    api-key: 01338aabfd8ef5bff253421ed78d38c0

    Authenticate via a query parameter in the endpoint URL:

    ?api-key=01338aabfd8ef5bff253421ed78d38c0

    Headers

    Required headers:

    curl "https://app.loggable.io/api/event"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
    

    All API calls require two headers:

    Header Value
    Content-type application/vnd.api+json
    Accept application/vnd.api+json

    Filtering, paging and sorting

    The JSON API specification allows for extensive filtering, paging and sorting of endpoints that return sets of data, for example, retrieving all channels or events. Below are some common examples

    Filter events by severity

    ?filter[severity][value]=error

    Filter events by channel

    ?filter[channel.uuid][value]=742caa49-19e9-4126-ad35-4089d3eee13b

    Sort events by type

    ?sort=type

    Limit to 10 results

    ?page[limit]=10

    Get the fourth page of events with a page size of 5

    ?page[limit]=5&page[offset]=15

    Channels

    Channel overview

    Channels are containers for events. You want to create one for each event source that you want to integrate with Loggable.

    Examples of channels include web apps, mobile apps, content management systems, shell scripts, etc.

    Channel attributes

    Below are the channel fields:

    Field Type Description
    uuid string Unique ID
    name string The name of the channel. This cannot exceed 64 characters.
    url string An external URL reference.
    description string Description of the channel. This cannot exceed 500 characters.
    created integer Timestamp of the creation.
    updated integer Timestamp of the last update.

    Get all channels

    curl "https://api.loggable.io/api/channel"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
    

    Response: 200 OK

    {
       "data":[
          {
             "type":"channel",
             "id":"742caa49-19e9-4126-ad35-4089d3eee13b",
             "attributes":{
                "uuid":"742caa49-19e9-4126-ad35-4089d3eee13b",
                "created":1523383813,
                "changed":1524936988,
                "name":"Webapp prod",
                "url":"http://myapp.com",
                "description":"Production environment for my webapp"
             },
             "links":{
                "self":"https://app.loggable.io/api/channel/742caa49-19e9-4126-ad35-4089d3eee13b"
             }
          },
          {
             "type":"channel",
             "id":"e471d2db-3310-4aa5-bd9b-f77f9a4c7c75",
             "attributes":{
                "uuid":"e471d2db-3310-4aa5-bd9b-f77f9a4c7c75",
                "created":1524786365,
                "changed":1525384577,
                "name":"Webapp stage",
                "url":"http://stage.myapp.com",
                "description":"Stage environment for my webapp"
             },
             "links":{
                "self":"https://app.loggable.io/api/channel/e471d2db-3310-4aa5-bd9b-f77f9a4c7c75"
             }
          },
          {
             "type":"channel",
             "id":"de801623-01a1-4b80-95a6-6302bbcf7b4a",
             "attributes":{
                "uuid":"de801623-01a1-4b80-95a6-6302bbcf7b4a",
                "created":1523404141,
                "changed":1523404141,
                "name":"Webapp dev",
                "url":"http://dev.myapp.com",
                "description":"Dev environment for my webapp"
             },
             "links":{
                "self":"https://app.loggable.io/api/channel/de801623-01a1-4b80-95a6-6302bbcf7b4a"
             }
          }
       ],
       "jsonapi":{
          "version":"1.0",
          "meta":{
             "links":{
                "self":"http://jsonapi.org/format/1.0/"
             }
          }
       },
       "links":{
          "self":"https://app.loggable.io/api/channel"
       }
    }
    

    Get all of your channels. For filters and paging options, see those sections of this document.

    HTTP Request

    GET https://api.loggable.io/api/channel

    Get a specific channel

    curl "https://api.loggable.io/api/channel/de801623-01a1-4b80-95a6-6302bbcf7b4a"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
    

    Response: 200 OK

    {
       "data":{
          "type":"channel",
          "id":"de801623-01a1-4b80-95a6-6302bbcf7b4a",
          "attributes":{
             "uuid":"de801623-01a1-4b80-95a6-6302bbcf7b4a",
             "created":1523404141,
             "changed":1523404141,
             "name":"My app",
             "url":"http://myapp.com",
             "description":"Production environment for my app."
          },
          "links":{
             "self":"https://app.loggable.io/api/channel/de801623-01a1-4b80-95a6-6302bbcf7b4a"
          }
       },
       "jsonapi":{
          "version":"1.0",
          "meta":{
             "links":{
                "self":"http://jsonapi.org/format/1.0/"
             }
          }
       },
       "links":{
          "self":"https://app.loggable.io/api/channel/de801623-01a1-4b80-95a6-6302bbcf7b4a"
       }
    }
    

    This endpoint retrieves a specific channel.

    HTTP Request

    GET https://app.loggable.io/api/channel/{channel}

    URL Parameters

    Parameter Description
    channel The UUID of the channel to retrieve

    Create a channel

    curl "https://api.loggable.io/api/channel"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
      -X POST
      -d '{
         "data":{
            "type":"channel",
            "attributes":{
               "name":"Mobile app production",
               "url":"http:\/\/mymobileapp.com\/",
               "description":"Production environment for my mobile app."
            }
         }
      }'
    

    Response: 201 Created

    {
       "data":{
          "type":"channel",
          "id":"3ff07b5a-b07c-4ead-8c19-e53e05349eb0",
          "attributes":{
             "uuid":"3ff07b5a-b07c-4ead-8c19-e53e05349eb0",
             "created":1525686842,
             "changed":1525686842,
             "name":"Mobile app production",
             "url":"http://mymobileapp.com/",
             "description":"Production environment for my mobile app."
          },
          "links":{
             "self":"https://app.loggable.io/api/channel/3ff07b5a-b07c-4ead-8c19-e53e05349eb0"
          }
       },
       "jsonapi":{
          "version":"1.0",
          "meta":{
             "links":{
                "self":"http://jsonapi.org/format/1.0/"
             }
          }
       },
       "links":{
          "self":"https://app.loggable.io/api/channel"
       }
    }
    

    This endpoint creates a new channel.

    HTTP Request

    POST https://app.loggable.io/api/channel

    Required fields

    Field Description
    name The channel name

    Update a channel

    curl "https://api.loggable.io/api/channel/3ff07b5a-b07c-4ead-8c19-e53e05349eb0"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
      -X PATCH
      -d '{
         "data":{
            "type":"channel",
            "id":"3ff07b5a-b07c-4ead-8c19-e53e05349eb0",
            "attributes":{
               "name":"Mobile app production 2"
            }
         }
      }'
    

    Response: 200 OK

    {
       "data":{
          "type":"channel",
          "id":"3ff07b5a-b07c-4ead-8c19-e53e05349eb0",
          "attributes":{
             "uuid":"3ff07b5a-b07c-4ead-8c19-e53e05349eb0",
             "created":1525686842,
             "changed":1525686842,
             "name":"Mobile app production 2",
             "url":"http://mymobileapp.com/",
             "description":"Production environment for my mobile app."
          },
          "links":{
             "self":"https://app.loggable.io/api/channel/3ff07b5a-b07c-4ead-8c19-e53e05349eb0"
          }
       },
       "jsonapi":{
          "version":"1.0",
          "meta":{
             "links":{
                "self":"http://jsonapi.org/format/1.0/"
             }
          }
       },
       "links":{
          "self":"https://app.loggable.io/api/channel"
       }
    }
    

    This endpoint updates an existing channel.

    HTTP Request

    PATCH https://app.loggable.io/api/channel/{channel}

    URL Parameters

    Parameter Description
    channel The UUID of the channel to update

    Delete a channel

    curl "https://api.loggable.io/api/channel/3ff07b5a-b07c-4ead-8c19-e53e05349eb0"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
      -X DELETE
    

    Response: 204 No Content

    This endpoint deletes an existing channel.

    HTTP Request

    DELETE https://app.loggable.io/api/channel/{channel}

    URL Parameters

    Parameter Description
    channel The UUID of the channel to delete

    Events

    Event overview

    Events are any action or information that originates from your channels. The usage of events is endless. Some common examples are a new user signing up, an order being placed, a code execution error, an import finishing, etc.

    When events are created, all of your active alerts inside the given channel are checked to see if their rules match the event. If so, a notification is instantly dispatched based on the configuration of that alert. Alert types include email, webhook, text message, etc.

    Event attributes

    Below are the event fields:

    Field Type Description
    uuid string Unique ID
    channel string The unique ID of the channel.
    type string The type of event. This is useful to group your events for easy filtering (ie, "User signup"). This cannot exceed 64 characters.
    severity string The severity level of the event. Allowed values include: debug, info, notice, warning, error, critical, alert, emergency.
    user string The user that triggered the event. This cannot exceed 64 characters.
    url string The URL where the event takes place. This must be a valid external URL.
    message string The event message. This cannot exceed 5000 characters.
    created integer Timestamp of the creation.
    updated integer Timestamp of the last update.
    expire integer Timestamp of the event expiration. This field cannot be set.

    Get all events

    curl "https://api.loggable.io/api/event"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
    

    Response: 200 OK

    {
       "data":[
          {
             "type":"event",
             "id":"6c93e593-963e-4d6d-a7ef-329bdd0dd421",
             "attributes":{
                "uuid":"6c93e593-963e-4d6d-a7ef-329bdd0dd421",
                "created":1524622185,
                "changed":1524622185,
                "type":"User signup",
                "severity":"notice",
                "user":"johndoe",
                "url":"http://mysite.com/user/123",
                "message":"A new user signed up.",
                "expire":1525831781
             },
             "relationships":{
                "channel":{
                   "data":{
                      "type":"channel",
                      "id":"742caa49-19e9-4126-ad35-4089d3eee13b"
                   },
                   "links":{
                      "self":"https://app.loggable.io/api/event/6c93e593-963e-4d6d-a7ef-329bdd0dd421/relationships/channel",
                      "related":"https://app.loggable.io/api/event/6c93e593-963e-4d6d-a7ef-329bdd0dd421/channel"
                   }
                }
             },
             "links":{
                "self":"https://app.loggable.io/api/event/6c93e593-963e-4d6d-a7ef-329bdd0dd421"
             }
          },
          {
             "type":"event",
             "id":"962ece1a-bd9f-4377-8a2c-2ff02d8953d8",
             "attributes":{
                "uuid":"962ece1a-bd9f-4377-8a2c-2ff02d8953d8",
                "created":1524622206,
                "changed":1524622206,
                "type":"PHP",
                "severity":"error",
                "user":"user123",
                "url":"http://myapp.com/section/one",
                "message":"Fatal error: Undefined function getLabel() on NULL on line 123",
                "expire":1525831803
             },
             "relationships":{
                "channel":{
                   "data":{
                      "type":"channel",
                      "id":"742caa49-19e9-4126-ad35-4089d3eee13b"
                   },
                   "links":{
                      "self":"https://app.loggable.io/api/event/962ece1a-bd9f-4377-8a2c-2ff02d8953d8/relationships/channel",
                      "related":"https://app.loggable.io/api/event/962ece1a-bd9f-4377-8a2c-2ff02d8953d8/channel"
                   }
                }
             },
             "links":{
                "self":"https://app.loggable.io/api/event/962ece1a-bd9f-4377-8a2c-2ff02d8953d8"
             }
          },
          {
             "type":"event",
             "id":"3fdb7860-f644-4de7-9dc3-438de2389a62",
             "attributes":{
                "uuid":"3fdb7860-f644-4de7-9dc3-438de2389a62",
                "created":1524622340,
                "changed":1524622358,
                "type":"Imports",
                "severity":"debug",
                "user":null,
                "url":null,
                "message":"Data import execution completed successfully in 17 seconds.",
                "expire":1525831935
             },
             "relationships":{
                "channel":{
                   "data":{
                      "type":"channel",
                      "id":"742caa49-19e9-4126-ad35-4089d3eee13b"
                   },
                   "links":{
                      "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62/relationships/channel",
                      "related":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62/channel"
                   }
                }
             },
             "links":{
                "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
             }
          }
       ],
       "jsonapi":{
          "version":"1.0",
          "meta":{
             "links":{
                "self":"http://jsonapi.org/format/1.0/"
             }
          }
       },
       "links":{
          "self":"https://app.loggable.io/api/event"
       }
    }
    

    Get all of your events. For filters and paging options, see those sections of this document.

    HTTP Request

    GET https://api.loggable.io/api/event

    Get a specific event

    curl "https://api.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
    

    Response: 200 OK

    {
       "data":{
          "type":"event",
          "id":"3fdb7860-f644-4de7-9dc3-438de2389a62",
          "attributes":{
            "uuid":"3fdb7860-f644-4de7-9dc3-438de2389a62",
            "created":1524622340,
            "changed":1524622358,
            "type":"Imports",
            "severity":"debug",
            "user":null,
            "url":null,
            "message":"Data import execution completed successfully in 17 seconds.",
            "expire":1525831935
          },
          "relationships":{
             "channel":{
                "data":{
                   "type":"channel",
                   "id":"742caa49-19e9-4126-ad35-4089d3eee13b"
                },
                "links":{
                   "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62/relationships/channel",
                   "related":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62/channel"
                }
             }
          },
          "links":{
             "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
          }
       },
       "jsonapi":{
          "version":"1.0",
          "meta":{
             "links":{
                "self":"http://jsonapi.org/format/1.0/"
             }
          }
       },
       "links":{
          "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
       }
    }
    

    This endpoint retrieves a specific event.

    HTTP Request

    GET https://app.loggable.io/api/event/{event}

    URL Parameters

    Parameter Description
    event The UUID of the event to retrieve

    Create an event

    curl "https://api.loggable.io/api/event"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
      -X POST
      -d '{
         "data":{
            "type":"event",
            "attributes":{
               "type":"Imports",
               "severity":"debug",
               "user":"admin",
               "url":"http://mysite.com/importer/abc",
               "message":"Data import execution completed successfully in 17 seconds."
            },
            "relationships":{
               "channel":{
                  "data":{
                     "type":"channel",
                     "id":"742caa49-19e9-4126-ad35-4089d3eee13b"
                  }
               }
            }
         }
      }'
    

    Response: 201 Created

    {
       "data":{
          "type":"event",
          "id":"3fdb7860-f644-4de7-9dc3-438de2389a62",
          "attributes":{
            "uuid":"3fdb7860-f644-4de7-9dc3-438de2389a62",
            "created":1524622340,
            "changed":1524622358,
            "type":"Imports",
            "severity":"debug",
            "user":null,
            "url":null,
            "message":"Data import execution completed successfully in 17 seconds.",
            "expire":1525831935
          },
          "relationships":{
             "channel":{
                "data":{
                   "type":"channel",
                   "id":"742caa49-19e9-4126-ad35-4089d3eee13b"
                },
                "links":{
                   "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62/relationships/channel",
                   "related":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62/channel"
                }
             }
          },
          "links":{
             "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
          }
       },
       "jsonapi":{
          "version":"1.0",
          "meta":{
             "links":{
                "self":"http://jsonapi.org/format/1.0/"
             }
          }
       },
       "links":{
          "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
       }
    }
    

    This endpoint creates a new event.

    HTTP Request

    POST https://app.loggable.io/api/event

    Required fields

    Field Description
    channel The channel unique ID
    type The type of event. This is useful to group your events for easy filtering (ie, "User signup")
    severity The severity level of the event. Allowed values include: debug, info, notice, warning, error, critical, alert, emergency.
    message The event message. This cannot exceed 5000 characters.

    Update an event

    curl "https://api.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
      -X PATCH
      -d '{
         "data":{
            "type":"event",
            "id":"3fdb7860-f644-4de7-9dc3-438de2389a62",
            "attributes":{
               "user":"johndoe123"
            }
         }
      }'
    

    Response: 200 OK

    {
       "data":{
          "type":"event",
          "id":"3fdb7860-f644-4de7-9dc3-438de2389a62",
          "attributes":{
            "uuid":"3fdb7860-f644-4de7-9dc3-438de2389a62",
            "created":1524622340,
            "changed":1524622358,
            "type":"Imports",
            "severity":"debug",
            "user":"johndoe123",
            "url":null,
            "message":"Data import execution completed successfully in 17 seconds.",
            "expire":1525831935
          },
          "relationships":{
             "channel":{
                "data":{
                   "type":"channel",
                   "id":"742caa49-19e9-4126-ad35-4089d3eee13b"
                },
                "links":{
                   "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62/relationships/channel",
                   "related":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62/channel"
                }
             }
          },
          "links":{
             "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
          }
       },
       "jsonapi":{
          "version":"1.0",
          "meta":{
             "links":{
                "self":"http://jsonapi.org/format/1.0/"
             }
          }
       },
       "links":{
          "self":"https://app.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
       }
    }
    

    This endpoint updates an existing event.

    HTTP Request

    PATCH https://app.loggable.io/api/event/{event}

    URL Parameters

    Parameter Description
    event The UUID of the event to update

    Delete an event

    curl "https://api.loggable.io/api/event/3fdb7860-f644-4de7-9dc3-438de2389a62"
      -H "api-key: 01338aabfd8ef5bff253421ed78d38c0"
      -H "Content-type: application/vnd.api+json"
      -H "Accept: application/vnd.api+json"
      -X DELETE
    

    Response: 204 No Content

    This endpoint deletes an existing event.

    HTTP Request

    DELETE https://app.loggable.io/api/event/{event}

    URL Parameters

    Parameter Description
    event The UUID of the event to delete

    Errors

    Error response example:

    {
       "errors":[
          {
             "title":"Unprocessable Entity",
             "status":422,
             "detail":"channel: This value should not be null.",
             "code":0,
             "source":{
                "pointer":"/data/attributes/channel"
             }
          }
       ]
    }
    
    Error code Meaning
    400 Bad Request -- The request contained invalid data, fields, or was malformed.
    403 Forbidden -- Either your API key was missing/invalid or you attempted to retrieve an entity that does not belong to your account.
    404 Not Found -- Either the requested entity does not exist or you used an invalid endpoint URL.
    422 Unprocessable Entity -- Either the provided data did not match the required attribute schema, you've referenced an incorrect channel, your subscription was canceled or suspended, or you have exceeded your quota for the given channel.
    500 Internal Server Error -- We had a problem with our server. Please try again later or report the issue to us.
    503 Service Unavailable -- We are temporarily offline for maintenance. Please try again later.

    Support

    If you have any questions, feedback, bug reports or need help implementing our API please email us at info@loggable.io.