Notation in These Documents

In URLs, the content within curly brackets ("{" and "}") must be URL encoded. For example: In the URL{id}, if a thing has an id "a@b", the URL for that thing is because "%40" is the URL-encoded representation of "@".

For brevity, the examples in these documents do not include all of the required request headers. For example, the "Authorization" header is required, but it is not repeated in every example in these documents.

The initial version of the API will be URL namespaced to /api/v1. For example, a request to create a user on should be POSTed to

Authentication is performed by means of OAuth 2.0 (see Authorization). Performing a GET /self will return the User resource for the credentials provided.

Security: The security of OAuth 2.0 depends on the users recognizing secure authenticated connections usually through their web browser.

All authenticated requests should include the Authorization header:

Authorization: Bearer MiwiefjSOfwefJSP+foiwefoSD_FWEFIOWEOF_WEFOISHDSF==

If the token is not provided, has expired, or is otherwise invalid, the server will return the following response:

401 Unauthorized
WWW-Authenticate: Token realm="application"

This indicates that the client should supply a valid token.

See also:,_read,_update_and_delete and:

In general, the API will respond to five different kinds of HTTP requests: create a resource, read a resource, update a resource, delete a resource, and list a collection of resources. In Rails parlance, these would correspond to the create, show, update, destroy, and index controller actions, respectively.

See Examples

All requests/responses must conform to HTTP/1.1 using content-type application/json for posted data unless specified otherwise for specific endpoints.

See Examples

Pagination for most collection resources is done with the query parameters page and per_page. Pagination is "1-based", e.g. GET /resources?page=1&per_page=5 will return the first five resources.

Some collection resources use the Link header (See the Github API as an example of another API that uses the Link header).

The response may contain the X-Total-Count header containing the total number of items across all pages of the collection.

The sort query paramter contains a comma-separated list of property names to sort by. A hyphen ("-") placed before a property name indicates a reverse-sort. The properties that any given endpoint supports for sorting are defined by that endpoint.

For example:

  • GET /resources?sort=field1 sorts by field1
  • GET /resources?sort=field1,field2 sorts by field1, and groupings of field1 are sorted by field2.
  • GET /resources?sort=field1,-field2 sorts by field1, and groupings of field1 are reverse-sorted by field2.

Various different error conditions exist and the following error responses will be returned.


  • 400 Bad Request The request has malformed/unrecognized syntax or is missing required information for processing the request.
  • 401 Unauthorized If a user is not logged in or their session has timed out.
  • 403 Forbidden Insufficient permissions: if a user is not allowed to perform the requested operation, usually due to not having the correct permissions.
  • 404 Not Found The resource does not exist at this time. This could mean that the user did not have permission to see that resource, and the server (for security reasons) is previnting users to be able to discover resources id by guessing.
  • 405 Method Not Allowed
  • 409 Conflict A resource already exists that would prevent this resource from being created.
  • 422 Unprocessable Entity Invalid Properties for create/update.
  • 500 Internal Server Error An unexpected/unrecoverable error happened at the server.

Error Response Formats

When errors are returned in the response, the error key/value should look like:

XX Any HTTP Error
  "code": "server_configuration_error",
  "message": "Message that can be shown to the user about the problem"

Not implemented: Unexpected JSON properties and properties whose values are not the expected types (i.e. expected a String but received a Boolean) will all cause some type of error response, possibly 422 Unprocessable Entity.

Internal Server Error

500 Internal Server Error
  "code": "internal_server_error",
  "message": "Message that can be shown to the user about the problem"

Validation Error

When a Validation Error occurs, the server will respond with 422 Unprocessable Entity:

422 Unprocessable Entity
  "code": "validation_error",
  "message": "There were problems with the data submitted.",
  "errors": [
      "field": "expires_at",
      "code": "must_be_date"
      "field": "message",
      "code": "too_long",
      "range": [0, 255]
      "field": "file_id",
      "code": "not_found"

Note that some error codes have more information. For example: the error code "too_long" has a "range" property.

Format: Requests and Responses

To specify the format of the data being sent, the HTTP header "Content-type" must be set whenever sending data to the server. The server may have a default, but any client that relies on that default may regret that decision if the default ever changes. Best-practice: include the "Content-type" header.

Similarly, the HTTP header "Accept" should be used to specify the format of the response.

Format: Date and Time

Dates and Times will be in ISO 8601 format (ISO, W3C, Wikipedia). While the format supports a few alternatives, we will stick to the following:

  • date only: YYYY-MM-DD
  • time only: hh:mm:ss
  • date and time: ‹date›T ‹time›Z, i.e. YYYY-MM-DDThh:mm:ssZ

The standard allows for offsets from UTC. We will return all dates and times in UTC.

Any POST, PUT, PATCH, or DELETE request may result in a 202 Accepted instead of the standard response. When this happens, the response will contain either a Location header or link in the body to a status URL. The status URL may be polled.

POST /resources
{ "key": "value" }
202 Accepted
Location: /api/v1/resources/3/operations/3324543
  "operation":  "resource.create",
  "progress":   "running",
  "id":         "3324543"
Video player