openapi: 3.0.0
info:
  title: Spectacles API
  version: 1.0.0
  description: >-
    Learn to use Spectacles' REST API. Click an endpoint, like `/runs`, to see
    its full URL, e.g., `https://app.spectacles.dev/api/v1/runs`.
  contact:
    name: Contact Us
    email: hello@spectacles.dev
servers:
  - url: https://app.spectacles.dev/api/v1
components:
  securitySchemes:
    Bearer Token:
      type: http
      description: >
        To get started, follow <a href="/app/guides/how-to-use-the-api/">this
        guide</a> 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>`
      scheme: bearer
      in: header
      bearerFormat: JWT
  schemas:
    GitHubWebhook:
      type: object
      required:
        - type
        - commit
        - repo
      properties:
        type: string
        commit:
          type: string
          description: The SHA hash of the commit to update with the result of this run
        repo:
          type: string
          description: >-
            The repo containing the commit to update, in `org_name/repo_name`
            format
    HttpWebhook:
      type: object
      required:
        - type
        - url
      properties:
        type: string
        url:
          description: The destination URL where you would like to receive the webhook.
          type: string
security:
  - Bearer Token: []
paths:
  /healthcheck:
    get:
      summary: Get the API version
      description: Return the version of the Spectacles API being requested.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
  /org/{orgId}/proj/{projectId}/run/{runId}:
    get:
      summary: Get a run
      description: >
        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.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  org_id:
                    type: string
                  project_id:
                    type: string
                  run_id:
                    type: string
                  suite_id:
                    type: string
                  suite_name:
                    type: string
                  url:
                    type: string
                  result:
                    type: array
                    items:
                      type: object
                      properties:
                        status: string
                        validator: string
                  ref:
                    type: object
                    properties:
                      type: string
                      value: string
                  created_at:
                    type: string
                  started_at:
                    type: string
                  finished_at:
                    type: string
                  status:
                    type: string
                  trigger:
                    type: string
                  user_attributes:
                    type: object
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: string
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: string
      parameters:
        - name: orgId
          in: path
          description: >-
            The ID of the organisation the run belongs to. Find this in the URL
            of the run after `/org/`
          required: true
          schema:
            type: string
        - name: projectId
          in: path
          description: >-
            The ID of the project the run belongs to. Find this in the URL of
            the run after `/proj/`
          required: true
          schema:
            type: string
        - name: runId
          in: path
          description: >-
            The ID of the run to get. Find this in the URL of the run after
            `/run/`
          required: true
          schema:
            type: string
  /runs:
    post:
      summary: Create a new run
      description: >
        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.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                org_id:
                  description: >-
                    The ID of the organisation to create the run in. Find this
                    in the URL of the Suite after `/org/`
                  type: string
                project_id:
                  description: >-
                    The ID of the project to create the run in. Find this in the
                    URL of the Suite after `/proj/`
                  type: string
                suite_id:
                  description: >-
                    The ID of the suite to use. Find this in the URL of the
                    Suite after `/suites/`
                  type: string
                branch:
                  description: The branch to test. Omit to test production.
                  type: string
                target:
                  description: >
                    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.
                  type: string
                commit:
                  description: The commit to test. Omit to test production.
                  type: string
                user_attributes:
                  description: >
                    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.
                  type: object
                webhooks:
                  description: >
                    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.
                  type: array
                  items:
                    oneOf:
                      - $ref: '#/components/schemas/GitHubWebhook'
                    discriminator:
                      propertyName: type
                      mapping:
                        github: '#/components/schemas/GitHubWebhook'
              required:
                - org_id
                - project_id
                - suite_id
              example:
                org_id: XstGk40FKAhElMNPMiZ9
                project_id: KFmxNOfdWj0A60A6zqE6
                suite_id: cMHbCPeWokwVhgqAh9AZ
                commit: ea23ba
                target: develop
                user_attributes:
                  dbt_project: spectacles
                  dbt_dataset: analytics
                webhooks:
                  - type: github
                    commit: abc123
                    repo: spectacles-ci/spectaces-dbt
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  run_id:
                    type: string
                  status:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: string
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: string
