Eventline is now open source and available on GitHub !

If you are still using the old Eventline platform, contact us to migrate to the new service, and head to the new documentation website for more information.

Interface

Introduction

The Eventline HTTP API lets users access the various features of the platform in a programmatic way.

Endpoint

The API is available at https://api.eventline.net. HTTPS is mandatory for all requests.

Authentication

Access to the Eventline API requires a valid API key. Authentication is based on the HTTP Authorization header field with the Bearer scheme.

For example, for the fictional API key 082ef11a-908f-4fae-819c-eb98b7fd98f6, requests must include the following header field:

Authorization: Bearer 082ef11a-908f-4fae-819c-eb98b7fd98f6

Project selection

Most API routes operate on a specific project. This project must be identified in each request by sending the identifier of the current project using the X-Eventline-Project-Id header field.

For example, for the fictional project 23B1NoaoigGQfmiP9PB9X2nJh4W, requests must include the following header field:

X-Eventline-Project-Id: 23B1NoaoigGQfmiP9PB9X2nJh4W

When an API route does not depend on a project, the X-Eventline-Project-Id can be omitted from the request.

Info
In order to obtain the identifier of a project using its name, you can use the GET /projects/name/:name route to fetch the project by name and read the id field.

Error handling

The Eventline API uses conventional HTTP status codes to indicate success or failure. In general, 2xx status codes indicate success, 4xx status codes indicate an error caused by the request, and 5xx status codes indicate an error in the Eventline platform.

Error responses sent by Eventline servers will contain a body representing an error object.

Warning

It is possible to receive error responses with a body which is not encoded in JSON, for example for errors coming from a load balancer or reverse proxy. Clients should use the Content-Type header field to determine the format of the body.

Errors originating from Eventline API servers will always have the application/json content type.

Pagination

Various API routes return collections of elements. Most of these routes use pagination to group elements.

Paginated routes return a single object representing the page, i.e. the required subset of the collection of elements.

Cursors

Pagination is controlled by cursors. A cursor contains the parameters required the control the selection of elements to be returned and their order.

Each cursor contains the following parameters:

before (string)
An opaque key; return elements positioned before the element designated by the key in the defined order (optional).
after (string)
An opaque key; return elements positioned after the element designated by the key in the defined order (optional).
size (integer)
The number of elements to return, between 0 and 100 (optional, default is 20).
sort (string)
The sort to apply to elements (optional, default is id). Different types of elements support different sorts; all elements support the id sort.
order (string)
The order to use for elements, either asc for ascending order or desc for descending order (optional, default is asc).

Cursors must include one and only one of the before and after parameters.

Requests

When sending requests to fetch elements, the cursor is passed using HTTP query parameters.

For example, sending a request to /v0/pipelines?after=MjNCeENVNURoOTBCM1hWRjRVcmtXcm5qZENP&size=5&order=id&order=desc will result in a response containing up to 5 pipelines at position MjNCeENVNURoOTBCM1hWRjRVcmtXcm5qZENP in the whole list of pipelines ordered by id.

All paginated requests may result in pages containing less elements that the number required using the size parameter.

Responses

When cursors are sent in responses, for example to indicate the previous or next page, they are represented as JSON objects.

For example:

{
  "after": "MjNCeENVNURoOTBCM1hWRjRVcmtXcm5qZENP",
  "size": 5,
  "order": "id",
  "order": "desc"
}

The response to a paginated query is a single page.

API versioning

The Eventline API is versioned; the version number is a single integer which is incremented when the API is updated in a backward incompatible way.

Info
API modifications which do not break backward compatibility are applied without incrementing the version number, for example adding new routes or adding fields to existing objects.

The current API version is 0, indicating that the API is still in beta. In version 0, the API can be modified in a backward incompatible way without incrementing the version number. However we are committed to avoid unnecessary changes and will inform you in advance if such changes are unavoidable. The first stable API version, version 1, will be made available soon.

The API version is represented in the path of each route, using the prefix vN where N is the version of the API. For example, /v0/account is the path of the route which returns the current account using API version 0.