Docs Navigation

API v2 Overview

This document describes all the resources that make up the Semaphore REST API v2. If you have any problems or requests please contact support.

The root of the API is

  1. Constraints
  2. Authentication
  3. Rate limiting
  4. Errors
  5. Pagination
  6. Stability


Every API request and response satisfies the following constraints:

  • All requests must use HTTPS.
  • All data is send and received as JSON.
  • Blank fields are included as null instead of being omitted.
  • All timestamps return in ISO 8601 format.


All API requests require authentication. To authenticate, you need an authentication token. You can find your authentication token by visiting your user settings.

Requests that require authorization will return 404 Not Found, instead of 403 Forbidden. This is to prevent the accidental leakage of private projects to unauthorized users.

There are two ways to authenticate through Semaphore API v2.

Authentication Token Sent as a HTTP header
curl -H "Authorization: Token <token>"
Authentication Token Sent as a query parameter

Rate limiting

All API v2 endpoints are limited to 60 requests per hour per user. When exceeding the limit you will receive an error response:

HTTP/1.1 429 Too Many Requests
Date: Wed, 28 Jun 2017 14:50:34 GMT
Status: 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2017-06-28 15:00:00 +0000



There are several errors that you can receive as a response to an API request:

Failing to authenticate
HTTP/1.1 401 Unauthorized

{"message":"Invalid authentication token."}
Attempting to authenticate by using both the header and query params
HTTP/1.1 401 Unauthorized

{"message":"Multiple authentication tokens provided."}
Sending invalid JSON
HTTP/1.1 400 Bad Request

{"message":"Problems parsing JSON"}
Requesting non existing resources
HTTP/1.1 404 Not Found

{"message":"Not Found"}
Requesting resources that are not visible to the user
HTTP/1.1 404 Not Found

{"message":"Not Found"}
Requesting an action that is not allowed for the resource
HTTP/1.1 405 Not Allowed

{"message":"Can't update ecrypted configuration file."}
Resource validation errors
HTTP/1.1 422 Unprocessable Entity

  "message": "Validation Failed",
  "errors": [
      "resource": "Teams",
      "field": "permission",
      "code": "missing_field"

The response contains an error object that describes the validation issue.

Code Description
not_valid The passed field does not have a valid value.
missing_field A required filed is missing.
unpermitted_parameter The field is not permitted.
Requesting deletion of resources that have existing dependencies
HTTP/1.1 409 Conflict

  "message": "Cannot delete record because of dependent projects",
  "documentation_url": ""


Every request that that returns more than 30 items will be paginated. You can specify further pages by passing the page parameter.

curl ''

The Link header includes information about pagination:

Link: <>; rel="first",
      <>; rel="last"

The response header also contains Total parameter which shows total number of items:

Total: 35

The possible rel values are:

Name Description
next The link for the next page of results
prev The link previous page of results.
first The link for the first page of results.
last The link for the lastpage of results.

It's advised to form calls with Link header values instead of constructing your own URLs.


Each resource in the Semaphore API v2 is annotated with a stability attribute, which will be set to one of three values: prototype, development, or production. This attribute reflects the change management policy in place for the resource. For a full explanation of these policies, please see our API compatibility policy.

Semaphore Docs are open source — Edit on GitHub


Occasional lightweight product and blog updates. Unsubscribe at any time.

2009-2017 © Rendered Text. All rights reserved. Terms of Service, Privacy policy, Security.