Getting Started with the ObservePoint API
Customers can use ObsevePoint’s API to:
- Create and execute website audits and web journeys
- Ingest audit results data into internal systems
- Automate nearly any task users can perform in the ObservePoint user interface
All data that ObservePoint presents in its user interface is also available via API
ObservePoint’s API is a REST API. It uses predictable, resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and methods. Any programming language and even some low-code tools can be used to integrate with the ObservePoint API.
Become familiar with the following concepts to use the ObservePoint API.
Every ObservePoint API endpoint requires clients to authenticate by passing an API key with the request. You can find your API key on your profile page. Pass your API key via the “Authorization” header, as follows:
Authorization: api_key Your API key here
An example of using the curl command to retrieve a list of web audits in your account:
curl -H 'Authorization: api_key your API key here' \
ObservePoint currently has two supported versions of its API: v2 and v3.
References for each API endpoint for both v2 and v3 are available:
Both versions of the API are fully supported and have no current plans for deprecation.
Note: ObservePoint’s API uses the term “page” with two different meanings, depending on context:
- In the context of pagination, a "page" is a subset of results from an API request.
- In the context of an Audit or Journey, a "page" is a web page.
Some API endpoints use pagination to limit the size of responses, such as:
Endpoints that support pagination allow you to specify two parameters to control the pagination:
|Pagination Input Query Parameter Name||Description|
|size|| The number of records the API should return per page.
Allowed range: 50 - 10,000
Tip: A good rule of thumb is to set this to 100.
|page||The page number, starting at 0, that you want to request.|
To download all results, you need to make multiple requests, increasing the “page” query string argument of each request, starting at 0, until you have downloaded all results.
Each response contains a “metadata” object with a “pagination” sub-object which tells you which page number you are currently processing and the total number of records to expect.
// results will appear here as a JSON array
You will know you have downloaded all records when the total number of records you have downloaded equals “totalCount”
|Pagination Output Field Name||Description|
|totalCount||The total number of records (not pages) across all pages.|
|totalPageCount||The total number of pages in the result.|
|pageSize||The number of records in each page (note: when querying the pages from an audit run, the records are web pages).|
|currentPageSize||The size of the current page. This will be equal to “pageSize” on every request except the last one.|
|currentPageNumber||Starting at 0, this is the number of the current page represented by the current request.|
When you make a PUT or POST request to the ObservePoint API, you will need to specify a content-type header as follows:
When you make a PATCH request to the ObservePoint API, you will need to specify a content-type header as follows:
When you make a GET request, no content-type header is needed.
ObservePoint API responses are JSON encoded, and thus have a Content-Type of “application/json”.
Responses use conventional HTTP status codes to indicate the success or failure of an API request, as described below:
|HTTP Response Code Range||Meaning|
|2xx||The request was successful|
|4xx||There was a mistake in your request. Read the response payload and the HTTP status code to know what was wrong.|
|5xx||There is an error with the ObservePoint servers. You can retry certain 5xx errors (like 502). If retrying doesn’t resolve the problem, contact ObservePoint support.|