Common Service API

API Overview

BEACON Web Services APIs use RESTful web services to deliver data in JSON. Most programming environments have readily available libraries for creating HTTP requests and parsing the responses.

Common Service API

All BEACON Web Services follow the common services API design.

HTTP Status Codes

These are the standard response codes all BEACON services return. See each API for specific details about codes.

Code Desc
200 OK Request accepted and there should be some content, assume the operation is complete
202 Accepted Request accepted but processing is not complete. The location header points to a URL that shows the progress or final result
204 No Content Request accepted but there is no more detail/content about it, assume the operation is complete
302 Found To redirect to another URL, such as a download
400 Bad Request Badly formatted request, i.e. the JSON is invalid as opposed to an validation failure (missing required field, date not a date) which is 422
401 Unauthorized No Authorization header, or not authorized
403 Forbidden User does not have permission
404 Not Found If any specific resource or page is not found, i.e. hwr/account/blah. In the case of list calls (i.e. GET /hwrruns) an empty array will be returned
409 Conflict Generally, on create (POST) there is a collision, see the APIs for specifics
412 Precondition Failed Generally, on update (PUT/PATCH) there is an issue with changing the resource, see the APIs for specifics
422 Unprocessable Entity Request is syntactically correct but the entity is not valid, a required field is missing or a date is out of range
5xx Internal server error

Response Objects

All services respond with no ambiguity in object type, that is, a client will be able to deterministically get a response based on the HTTP response code. Depending on the HTTP response code the same object is returned. Some responses use object “wrappers” for pagination.

When an API returns 4xx codes, they are standard error responses.

A 2xx code will return a JSON object as per the API.

Property Names

All JSON objects use camelCase, except uuids are the property with UUID suffixed, e.g. accountUUID, reportUUID, taskUUID etc.

type desc
string string
int int
float float
bool boolean
Object array an array of element type Object
uuid string quoted UUID. “3287912374838239853”
date string quoted ISO 8601. “2015-02-03T13:04:24Z”
email string quoted email address (limit 254). “
url string quoted url, may be relative. “/v1/svc/3323”


The API allows for paginating through results sets. Results that are paginated are returned in a pagination wrapper object, with the actual objects under a results property. The API request must take a standard set of parameters that indicate the pagination criteria.


param type desc
offset int Record number offset, starting at 0. The first record number after this offset is included in the results. Default: 0
limit int Max number of records to return, up to a max of 100. Less records may be returned Default: 50
sort string Field to sort on
dir enum desc | asc. Default: desc

Response Object

property type desc
total int the total number in the set
from int the record number of the first element in results. Record numbers start at 1
to int the record number of the last element in results
results Object array an array of the result objects – see API for type of object. It will be an empty array if total is 0, and may be empty if there are no results beginning at the requested offset

  "total": 532,
  "from": 101,
  "to": 150,
  "results": [ {

API Codes

All services use a common API code format:

apicode:= [E|W|I|D]-tla-nnn

Each service defines the possible error codes and their meanings.

i.e. E-HWR-200 or W-TSK-56

Code Arguments

Some codes might require arguments. These can be used when creating an error message, e.g. code E-HWR-301 might translate in en to “The cloned template ({1}) does not exist”, where {1} is the first argument value, e.g. “Winter Run”.

The optional args property in the error response is an array of strings.

Reason Codes

Reason codes are non human readable points in the code that indicate the location of the API code or underlying reason for generating the code. They are chainable and a service should forward reason codes: If the HWR service calls the TSK service, which returns an error code and reason, the HWR should return a new API code (E-HWR-nnn) and chain the TSK reason code (

reason:= tla-msg[_reason]*
msg:= anyalpha ^_

Error Responses

A service that returns errors respond with a standard object that contains at least the code and reason.

  "code": "E-HWR-200",
  "args": ["a code argument"],
  "reason": "

Common API Codes

These codes are common to all services.

HTTP Status API Code args desc
400 E-API-400 status code An internal issue caused by a bad request
400 E-API-450 lineNbr, colNbr General JSON processing exception
400 E-API-451 lineNbr, colNbr JSON parsing failed. Badly constructed JSON
400 E-API-452 lineNbr, colNbr JSON mapping
400 E-API-453 lineNbr, colNbr JSON generation. Could not generate JSON response
406 E-API-406 Accept response media type not supported
415 E-API-415 Content-Type request media type not supported
422 E-API-422 property:error, … Validation failure. See API for description of required object properties
500 E-API-500 Internal Server Error


The API uses HTTP basic access authentication to provide your applications with secure access to all data available to your account. In addition, all requests must go through our HTTPS endpoint, where all data transfer is encrypted through SSL. Using your BEACON username and password, you can use your programming library base64 method to create an HTTP Authorization header. For an explanation of this procedure, see:

Get Support

Knowledge Base

User Guide
Follow via Email

Enter your email address to get new content notifications by email.