Skip to main content
Documentation Powered by ReDoc

Spectacles API (1.0.0)

Contact Us: hello@spectacles.dev

This documentation explains how to interact with Spectacles via our REST API.

Click on any API endpoint route to expand it into a full URL. For example, /runs will expand into https://app.spectacles.dev/api/v1/runs.

Authentication

Bearer Token

To get started, follow this guide to create an API key.

To authenticate to the Spectacles API, you'll need to obtain a token from the Settings page of the Spectacles application. You can only have one API token active at a time, so be sure to store it securely. If you lose it, you'll need to replace it with a new one.

Once you have the token, pass it in the header of your API calls as a bearer token, like this: Authorization: Bearer <token>

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Get the API version

Return the version of the Spectacles API being requested.

Authorizations:
Bearer Token

Responses

Response samples

Content type
application/json
{
  • "version": "string"
}

Get a run

Retrieve the details for a given run, including:

  • The current status (queued, running, success, etc.)
  • The result of each validator (if available)
  • Metadata about the run

You can easily find the organisation, project, and run IDs in the URL of the run details page within the Spectacles app.

Authorizations:
Bearer Token
path Parameters
orgId
required
string

The ID of the organisation the run belongs to. Find this in the URL of the run after /org/

projectId
required
string

The ID of the project the run belongs to. Find this in the URL of the run after /proj/

runId
required
string

The ID of the run to get. Find this in the URL of the run after /run/

Responses

Response samples

Content type
application/json
{
  • "org_id": "string",
  • "project_id": "string",
  • "run_id": "string",
  • "suite_id": "string",
  • "suite_name": "string",
  • "url": "string",
  • "result": [
    ],
  • "ref": {
    },
  • "created_at": "string",
  • "started_at": "string",
  • "finished_at": "string",
  • "status": "string",
  • "trigger": "string",
  • "user_attributes": { }
}

Create a new run

Create a run belonging to a given organisation, project, and suite. Return the ID of the newly created run as well as its status at time of creation.

To create a run against production, omit branch and commit from your request.

You can easily find the organisation, project, and suite IDs in the URL of the suite page within the Spectacles app.

Authorizations:
Bearer Token
Request Body schema: application/json
org_id
required
string

The ID of the organisation to create the run in. Find this in the URL of the Suite after /org/

project_id
required
string

The ID of the project to create the run in. Find this in the URL of the Suite after /proj/

suite_id
required
string

The ID of the suite to use. Find this in the URL of the Suite after /suites/

branch
string

The branch to test. Omit to test production.

target
string

For incremental runs only. The branch or commit to compare against for incremental validation.

When target is not specified for a Suite with incremental validation enabled, it defaults to production.

commit
string

The commit to test. Omit to test production.

user_attributes
object

To set user attributes for your run, specify them here as key/value pairs. These user attributes must first be configured up in your Spectacles settings.

Array of any[ items ]

Send a webhook when the run completes. The behavior of the webhook depends on the type specified.

Specify a github webhook to update the status of a commit with the result of this run. The GitHub integration must be already configured in Spectacles settings. The commit does not have to be in the same repo as the commit that Spectacles is testing. For example, you may want to update the status of a commit on a dbt repo based on the result of a Spectacles run against Looker's production branch.

Responses

Request samples

Content type
application/json
{
  • "org_id": "XstGk40FKAhElMNPMiZ9",
  • "project_id": "KFmxNOfdWj0A60A6zqE6",
  • "suite_id": "cMHbCPeWokwVhgqAh9AZ",
  • "commit": "ea23ba",
  • "target": "develop",
  • "user_attributes": {
    },
  • "webhooks": [
    ]
}

Response samples

Content type
application/json
{
  • "run_id": "string",
  • "status": "string"
}