API Usage
Guidelines

The Siteimprove API allows you to access all of your site data through a REST API. The API assumes familiarity with the Siteimprove tools and services.

Access and Security

The Siteimprove REST API is served over HTTPS only, to support data privacy. Access to the API requires basic access authentication with a Siteimprove user and your API-key as password. See get access on how to obtain access.

Accept Header

The API serves application/json and text/html content types and will default to text/html. If you specify other media types in the accept: header, the API will respond with a http 406 error. The text/html will allow you to browse the GET requests of the API in a standard browser. To access the entire API from a browser, we suggest the use of a REST plugin like Postman.

Rate Limiting

Usage of the API is limited to 5 requests per second per API-key on average with an allowable burst of up to 50 requests. The rate limitation is implemented as a counter with an maximum limit of 50. Each request decrements the counter by 1 until you reach zero. As long as the counter is zero, the API returns error code 429. Each second the counter is incremented by 5 until the maximum limit is reached.

You can see the rate limit counter in the response headers named X-Rate-Limit, X-Rate-Remaining, and X-Rate-Reset. They show the current maximum limit, the current counter value, and the amount of seconds you should wait before the counter is back to the maximum limit.

Example headers in a API response:

X-Rate-Limit: 50
  X-Rate-Remaining: 25
  X-Rate-Reset: 5 seconds

This says your maximum limit is 50 requests, of which you have 25 left and in 5 seconds you will be back to maximum if you don’t send any requests in the meantime.

Paging

Resources in the API that are paged due to potential large payloads have the general form:

{
    "items": [ <list-of-objects> ],
    "total_items": <total_number_of_items_in_result_set>,
    "total_pages": <total_number_of_pages_in_result_set>,
    "_links": 
    {
      "next": { href: <link_to_next_page_in_result_set>},
      "prev": { href: <link_to_previous_page_in_result_set>}
    }
  }

Where items is a slice of items from the total result set, total_items is the total number of elements in the result set. total_pages is the total number of pages for the result set. next takes you to the next page in the result set and is not present on the last page of a result – vice versa for prev.

The default page size is 10 items per page. You can change this to any value between 1 and 1000 by setting the page_size URL query string parameter to your required value. You can jump to specific pages in the result set by setting the page URL query string parameter to a value between 1 and number of pages (i.e. Assuming there is at least two pages, to get the sites overview in batches of 4 elements starting on page 2, use:

https://api.siteimprove.com/v2/sites?page_size=4&page=2

Query Parameters for Paged Resources

GET ?page_size=:page_size&page=:page

The standard paging parameters

Parameter	Location	Type	Description
:page_size	Query parameter (OPTIONAL)	Integer. Between 1 and 1000. Default 10	Number of items on each page
:page	Query parameter (OPTIONAL)	Integer. Between 1 and number of pages in result set. Default 1	Page to retrieve

Timestamps in Responses

Timestamps in the form yyyy-mm-ddThh:mm:ss, e.g. "2014-09-01T22:13:50" refers to a timestamp in the time zone of the site. The site time zone can be read on the site resource.

Timestamps in the form yyyy-mm-ddThh:mm:ssZ, e.g. “2014-09-01T22:13:50Z” refers to a timestamp in UTC aka Zulu time, and “2014-09-01T22:13:50+01:00” refers to a timestamp in UTC +1 hour.

Web Links and Siteimprove Custom Relations

The _links section in each response contains hypermedia links to related resources in the API.

Some responses contain a _siteimprove section.

{
    "_siteimprove": {
      "webapp": { href : },
      "page_report": { href : }
    }
  }

This section contains deep links into the Siteimprove platform. The webapp links into the Siteimprove web application representation for the resource in the response. The page_report links into the page report which highlights errors found on a page.

HTTP Status Codes

200: OK.
201: Accepted for processing, but the processing has not been completed.
401: Not Authenticated. Missing a valid basic authentication header.
403: Access forbidden. User not authorized to requested resource.
404: Not Found. Requested resource not found.
406: Not Acceptable. Cannot respond with content type requested in accept: header.
429: Too Many Requests. Probably above rate limit.

API Usage Guidelines