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 https://api.semaphoreci.com/v2.

  1. Constraints
  2. Authentication
  3. Rate limiting
  4. Errors
  5. Pagination
  6. Cross Origin Resource Sharing
  7. Stability

Constraints

Every API request and response satisfies the following constraints:

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

Authentication

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>" https://api.semaphoreci.com/v2
Authentication Token Sent as a query parameter
curl https://api.semaphoreci.com/v2/orgs?auth_token=<token>

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

Throttled

Errors

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": "https://semaphoreci.com/docs/api-v2-overview.html"
}

Pagination

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

curl 'https://api.semaphoreci.com/v2/orgs?page=2'

The Link header includes information about pagination:

Link: <http://api.semaphoreci.com/v2/orgs?page=1>; rel="first",
      <http://api.semaphoreci.com/v2/orgs?page=2>; 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.

Cross Origin Resource Sharing

The Semaphore API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin.

For more information about Cross Origin Resource Sharing, you can read the CORS W3C Recommendation, or this intro from the HTML 5 Security Guide.

Here's a sample request sent from a browser hitting api.semaphoreci.com/v2:

curl -I https://api.semaphoreci.com/v2

HTTP/1.1 200 OK
access-control-allow-origin: *
access-control-max-age: 86400
access-control-allow-headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, Accept-Encoding, X-Requested-With
access-control-allow-methods: GET, POST, PATCH, PUT, DELETE

This is what the CORS preflight request looks like:

curl -I -X OPTIONS https://api.semaphoreci.com/v2

HTTP/1.1 200 OK
access-control-allow-origin: *
access-control-max-age: 86400
access-control-allow-headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, Accept-Encoding, X-Requested-With
access-control-allow-methods: GET, POST, PATCH, PUT, DELETE

Stability

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

Newsletter

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

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