API overview

All data is sent and received as JSON over HTTPS. All endpoints are relative to the base URL:

https://api.layer.com

Headers

Every request must include an Accept header (see Versioning below) and a Content-Type header. Most requests must include an Authorization header (see Authenticating requests below):

Accept: application/vnd.layer+json; version=3.0
Content-Type: application/json
Authorization: Bearer <TOKEN>

Versioning

The API is versioned via an Accept header:

Accept: application/vnd.layer+json; version=3.0

You must explicitly require a version via the header. This allows us to make changes in future versions, and gives you time to update, without breaking your app in the meantime. An error is returned if you fail to request a specific version of the API:

Invalid header | Status: 406 (Not Acceptable)

{
  "id": "invalid_header",
  "code": 107,
  "message": "Invalid Accept header; must be of form application/vnd.layer+json; version=x.y",
  "url": "http://docs.layer.com/reference/server_api#versioning",
  "data": {
    "header": "Accept"
  }
}

PATCH requests

If you are unable to send PATCH requests, a POST request with the X-HTTP-Method-Override: PATCH header is also supported.

curl  -X POST \
      -H 'X-HTTP-Method-Override: PATCH'
      -H 'Accept: application/vnd.layer+json; version=3.0' \
      -H 'Authorization: Bearer TOKEN' \
      -H 'Content-Type: application/vnd.layer-patch+json' \
      -d '[{"operation": "set",    "property": "metadata.stats.counter", "value": "10"}, {"operation": "delete", "property": "metadata.admin"}]' \
      https://api.layer.com/apps/APP_UUID/conversations/CONVERSATION_UUID

Deduplicating requests

When retrying requests that fail or timeout, duplicate actions may be possible (for example, creating the same conversation or sending the same message twice). Deduplication is a technique for ignoring additional requests beyond the first. This is done using an If-None-Match header field with a RFC 4122–compliant UUID for requests that create new resources. If this header field exists in a request, the server will not re-execute the request if the tag has already been seen, and will respond with the previously created resource.

The If-None-Match header requires you to use a unique UUID for each distinct request. If the request fails, reuse the UUID when retrying the request.

Illustrative code example:

var uuid = generateUUID();
request.addHeader("If-None-Match", '"' + uuid + '"');

try {
  request.execute();
} catch {
  delayAndRetryWithSameUUID(request);
}

The If-None-Match header is optional. It is only required if you want the ability to retry failed requests.

Authenticating requests

Server API requests must be authenticated with a token generated from the Developer Dashboard within the “Server API” section. The token can be revoked at any time from the dashboard as well.

The Authorization header of each request should be the word “Bearer” followed by the token:

Authorization: Bearer <TOKEN>

If the token is missing, revoked, or invalid, the response will contain a 401 (Unauthorized) status code.

Token security

The Server API tokens provide administrator-level access to your users’ data and as such should be kept secure. One important precaution is to avoid using them from a web browser. While traffic may be encoded and encrypted, anyone with access to your browser can open a Javascript console, copy your tokens and gain unrestricted access to all of your users’ data.

If you wish to perform actions in your application that in turn trigger Server API methods, you should expose endpoints on your own backend and enforce suitable access controls. Your users can then interact with your backend application, which then makes the corresponding call to the Layer Server API.