Automated Lighthouse Check: How to Use the API

To start using the public API you'll first need to follow the below steps.

1. Get started with Automated Lighthouse Check by following steps from the documentation.
2. Retrieve your account "API token" from the account page. You can find it by navigating to the account page and click into the "manage" tab.
3. Next, you'll need to retrieve page API tokens for each page (this is in addition to your account API token). To do so, navigate to your dashboard page. Click on the "more" link at the bottom right corner of the results card for the corresponding page you'd like to audit. From the URL details page click the "edit" link at the top right. From this screen you'll find an "API Token" which is your page API token.

UPDATE (5/8/21): This post is about our legacy API. Read about the newest version of our REST API with full examples here.

Methods

Automated Lighthouse Check API uses a REST architectural style. In the future we may add more interfaces, but the REST interface will be the original source of truth.

Queue

Lighthouse runs are organized in a queue - a first-in-first-out data structure as described in Wikipedia. By adding to the queue - you can enqueue pages to be audited. API rate limits are on a per page basis, defined by account type. You can find your limit in account management or see all of them in the Plans and Pricing page.

addItems

POST https://www.foo.software/api/v1/queue/items

Adds a URL or group of URLs to the queue. Each URL requires a API token.
Authentication required?	No
Payload
Name	Description	Type	Required	Default
pages	A comma separated list of page api tokens found in the dashboard - one for each page to be enqueued. You can also just provide one.	String	Yes	--
tag	An optional tag or name of a performance run (example: build #2 or v0.0.2).	String	Yes	--
Example
curl -X POST "https://www.foo.software/api/v1/queue/items" -H "accept: application/json" -H "Authorization: your-account-api-token" -H "Content-Type: application/json" -d "{ \"pages\": \"pagetoken1,pagetoken2\", \"tag\": \"build 3\" }"

Example response body

{
  "status": 200,
  "code": "SUCCESS_GENERIC",
  "message": "Success!",
  "namespace": "Route:addQueueItemsPublicApi()",
  "data": {
    "queue": {
      "results": [
        {
          "code": "SUCCESS_QUEUE_ADD",
          "message": "Added to the queue!",
          "status": 200
        },
        {
          "code": "ERROR_PAGE_MISSING",
          "message": "This page does not exist.",
          "status": 422
        }
      ],
      "errors": 1
    }
  }
}