All Collections
REST API
Getting Started with the ObservePoint API
Getting Started with the ObservePoint API
Luiza Gircoveanu avatar
Written by Luiza Gircoveanu
Updated this week

Overview

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.

Getting Started

Become familiar with the following concepts to use the ObservePoint API.

Authentication

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' \
https://api.observepoint.com/v2/web-audits

Versioning

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.

Pagination

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:

/v3/web-audits/auditId/runs/runId/reports/page-summary/pages?size=pageLimit&page=pageNumber

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.

"metadata": {
"pagination": {
"totalCount": 544,
"totalPageCount": 6,
"pageSize": 100,
"currentPageSize": 100,
"currentPageNumber": 0
}
},

// 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.

API Requests

When you make a PUT or POST request to the ObservePoint API, you will need to specify a content-type header as follows:

Content-Type: application/json

When you make a PATCH request to the ObservePoint API, you will need to specify a content-type header as follows:

Content-Type: application/json-patch+json

When you make a GET request, no content-type header is needed.

API Responses

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.

Did this answer your question?