Exit1.dev Checks API

openapi: 3.2.0
info:
  title: exit1.dev Checks API
  description: 'The exit1.dev API provides programmatic access to your website monitoring data.


    This file covers the read endpoints. Write endpoints (create, update,

    delete, toggle) are documented at https://docs.exit1.dev/api-reference.


    ## Authentication

    All requests must include an `X-Api-Key` header with a valid API key.

    API access is available on all plans.


    ## Timestamps

    All timestamps in responses are Unix epoch milliseconds.


    ## Rate Limits (API keys)

    - Pre-authentication: 20 requests/minute per IP

    - Per API key: 5 requests/minute

    - Per endpoint per key: 1 request/minute

    - Daily per key: 500 requests

    - Daily per user: 2,000 requests


    `GET /v1/public/checks/status` has its own limits (6/minute per key,

    12/minute per user) and does not count toward the ones above.'
  version: 1.2.0
  contact:
    name: exit1.dev Support
    url: https://exit1.dev
    email: connect@exit1.dev
servers:
- url: https://us-central1-exit1-dev.cloudfunctions.net/publicApi
  description: Production API
security:
- ApiKeyAuth: []
tags:
- name: Checks
paths:
  /v1/public/checks:
    get:
      operationId: listChecks
      summary: List checks
      description: Retrieve a list of all monitoring checks in your account.
      tags:
      - Checks
      parameters:
      - name: limit
        in: query
        description: Number of results per page (max 100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: page
        in: query
        description: Page number for offset pagination. Ignored when cursor is set.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: cursor
        in: query
        description: The nextCursor value from a previous response
        schema:
          type: string
      - name: status
        in: query
        description: Filter by check status. Any other value returns 400.
        schema:
          type: string
          enum:
          - all
          - online
          - offline
          - degraded
          - unknown
          default: all
      - name: includeTotal
        in: query
        description: Set to false to skip counting; total and totalPages are then null.
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: List of checks
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Check'
                  meta:
                    $ref: '#/components/schemas/CheckListMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/public/checks/status:
    get:
      operationId: getCheckStatuses
      summary: Status of every check
      description: 'The current status of every check, unpaginated, for monitoring systems

        that poll. Has its own rate limit (6/minute per key, 12/minute per

        user) outside the daily quotas. Send the last ETag as If-None-Match

        to get a 304 when nothing changed.'
      tags:
      - Checks
      parameters:
      - name: If-None-Match
        in: header
        description: ETag from a previous response
        schema:
          type: string
      responses:
        '200':
          description: Status of every check
          headers:
            ETag:
              description: Changes only when a check's reported state changes
              schema:
                type: string
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CheckStatus'
                  meta:
                    type: object
                    properties:
                      total:
                        type: integer
        '304':
          description: Nothing changed since the ETag in If-None-Match
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/public/checks/{id}:
    get:
      operationId: getCheck
      summary: Get check
      description: Retrieve details for a single monitoring check.
      tags:
      - Checks
      parameters:
      - $ref: '#/components/parameters/CheckId'
      responses:
        '200':
          description: Check details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Check'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    Retry-After:
      description: Seconds to wait before retrying (429 responses only)
      schema:
        type: integer
    RateLimit-Limit:
      description: Maximum requests allowed in the current window
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests remaining in the current window
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the current window resets
      schema:
        type: integer
    RateLimit:
      description: Combined form, for example "limit=1, remaining=0, reset=42"
      schema:
        type: string
  parameters:
    CheckId:
      name: id
      in: path
      required: true
      description: The unique check identifier (letters, digits, - and _, max 128 characters)
      schema:
        type: string
  schemas:
    CheckRegions:
      type: object
      description: Which regions observed the latest result. A second (peer) region re-checks failures.
      properties:
        primary:
          type:
          - string
          - 'null'
          example: vps-eu-1
        peer:
          type:
          - string
          - 'null'
          description: Null when no peer region was consulted
          example: vps-us-1
        regionsTotal:
          type: integer
          example: 2
        regionsDown:
          type: integer
          example: 2
        confirmedDown:
          type: boolean
          description: Offline and the peer region agreed
    CheckListMeta:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 25
        total:
          type:
          - integer
          - 'null'
          description: Null when includeTotal=false
          example: 12
        totalPages:
          type:
          - integer
          - 'null'
          description: Null when includeTotal=false
          example: 1
        hasNext:
          type: boolean
        hasPrev:
          type: boolean
        nextCursor:
          type:
          - string
          - 'null'
    CheckStatus:
      type: object
      properties:
        id:
          type: string
          example: abc123
        name:
          type: string
          example: Production Website
        status:
          type: string
          enum:
          - online
          - offline
          - degraded
          - unknown
        lastStatusChange:
          type:
          - integer
          - 'null'
          description: Epoch ms when status last changed
        lastError:
          type:
          - string
          - 'null'
          description: Only set while status is offline
        disabled:
          type: boolean
        maintenanceMode:
          type: boolean
        regions:
          $ref: '#/components/schemas/CheckRegions'
    Check:
      type: object
      properties:
        id:
          type: string
          example: abc123
        name:
          type: string
          description: Display name. Falls back to url when unset.
          example: Production Website
        url:
          type: string
          description: Monitored URL, host or domain. Heartbeat checks return heartbeat://<token>, domain checks return domain://<domain>.
          example: https://example.com
        status:
          type: string
          enum:
          - online
          - offline
          - degraded
          - unknown
          example: online
        lastChecked:
          type: integer
          description: Epoch ms of the last synced result (0 if never checked). Synced on status changes and at least once every 24 hours.
          example: 1736951400000
        responseTime:
          type:
          - integer
          - 'null'
          description: Response time in ms from the last synced result
          example: 245
        lastStatusCode:
          type:
          - integer
          - 'null'
          description: HTTP status code from the last synced result
          example: 200
        type:
          type: string
          description: Check type. Some older checks report the legacy values api or rest.
          enum:
          - website
          - rest_endpoint
          - redirect
          - ping
          - tcp
          - udp
          - websocket
          - dns
          - heartbeat
          - domain
          - api
          - rest
          example: website
        checkFrequency:
          type:
          - number
          - 'null'
          description: Minutes between checks
          example: 5
        region:
          type:
          - string
          - 'null'
          description: Region the check runs from
          example: vps-eu-1
        folder:
          type:
          - string
          - 'null'
        severity:
          type:
          - integer
          - 'null'
          minimum: 1
          maximum: 5
          description: 1 (P1, critical) to 5 (P5, minimal); null when unset
        lastError:
          type:
          - string
          - 'null'
        lastStatusChange:
          type:
          - integer
          - 'null'
          description: Epoch ms when status last changed. Null if it has not changed since the field was introduced.
        regions:
          $ref: '#/components/schemas/CheckRegions'
        disabled:
          type: boolean
        maintenanceMode:
          type: boolean
        maintenanceUntil:
          type:
          - integer
          - 'null'
          description: Epoch ms when the current maintenance window ends
        maintenanceScheduledStart:
          type:
          - integer
          - 'null'
          description: Epoch ms of an upcoming one-time maintenance window
        maintenanceRecurring:
          type:
          - object
          - 'null'
          properties:
            daysOfWeek:
              type: array
              items:
                type: integer
            startTimeMinutes:
              type: integer
            durationMinutes:
              type: integer
            timezone:
              type: string
            reason:
              type:
              - string
              - 'null'
            createdAt:
              type: integer
        sslCertificate:
          type:
          - object
          - 'null'
          properties:
            valid:
              type: boolean
            issuer:
              type: string
            subject:
              type: string
            validFrom:
              type: integer
              description: Epoch ms
            validTo:
              type: integer
              description: Epoch ms
            daysUntilExpiry:
              type: integer
            lastChecked:
              type: integer
              description: Epoch ms
            error:
              type: string
        domainExpiry:
          type:
          - object
          - 'null'
          description: Null unless Domain Intelligence is enabled for the check
          properties:
            domain:
              type:
              - string
              - 'null'
            registrar:
              type:
              - string
              - 'null'
            expiryDate:
              type:
              - integer
              - 'null'
              description: Epoch ms
            daysUntilExpiry:
              type:
              - integer
              - 'null'
        lastPingAt:
          type:
          - integer
          - 'null'
          description: Heartbeat checks only (absent for other types). Epoch ms of the last ping.
        createdAt:
          type: integer
          description: Epoch ms
        updatedAt:
          type: integer
          description: Epoch ms
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message
        retryAfter:
          type: integer
          description: Seconds to wait before retrying (429 responses)
        quotaLimit:
          type: integer
          description: Daily request quota (daily-quota 429 responses only)
        quotaReset:
          type: integer
          description: Epoch ms when the daily quota resets (daily-quota 429 responses only)
  responses:
    BadRequest:
      description: Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid check ID format
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found
    RateLimited:
      description: Rate limit exceeded
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate limit exceeded. Please try again later.
            retryAfter: 42
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal error
    Forbidden:
      description: Missing scope, or the check belongs to another account
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'Credential does not have the required scope: checks:read'
    Unauthorized:
      description: Missing, invalid or disabled credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid API key
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'API key for authentication. Create keys at Settings > API.

        Format: `ek_live_<64 hex characters>`

        A key can carry an expiry (401 "API key expired" afterwards) and can be

        restricted to specific checks and/or folders (subfolders included).

        A restricted key only lists its own checks and gets 404 for others.

        '