CacheBoost Runs API

openapi: 3.2.0
info:
  title: CacheBoost Runs API
  version: '1'
  description: 'The CacheBoost API lets you manage sites, sitemaps, boosts, and runs

    programmatically. All endpoints are under `/v1`.'
servers:
- url: https://api.cache-boost.com/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Runs
paths:
  /runs:
    get:
      operationId: listRuns
      summary: List runs
      description: 'Returns run history across all boosts, newest first. Includes both scheduled

        boost runs (`sitemap`, `csv`) and on-demand warm runs (`inline`). Use the

        `site_id` query parameter to scope results to a single site — particularly

        useful for CMS integrations (WordPress, Magento) that need to display run

        history for the local site only.'
      tags:
      - Runs
      security:
      - bearerAuth:
        - runs:read
      parameters:
      - name: site_id
        in: query
        schema:
          type: integer
        description: Filter by site ID. Useful for third-party integrations (e.g. CMS plugins) that need to scope runs to a specific site.
      - name: boost_id
        in: query
        schema:
          type: integer
        description: Filter by boost ID.
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 100
        description: Number of results to return.
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
        description: Pagination offset.
      responses:
        '200':
          description: Paginated list of runs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Run'
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /runs/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: integer
      description: Run ID
    get:
      operationId: getRun
      summary: Get a run
      description: Retrieve a single run by ID, including summary statistics.
      tags:
      - Runs
      security:
      - bearerAuth:
        - runs:read
      responses:
        '200':
          description: Run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunDetail'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    RunSummary:
      type: object
      nullable: true
      properties:
        total_calls:
          type: integer
          example: 1240
        successful_calls:
          type: integer
          example: 1238
        failed_calls:
          type: integer
          example: 2
        cache_hits:
          type: integer
          example: 1165
        average_response_time_ms:
          type: number
          example: 112.5
        pops:
          type: object
          additionalProperties:
            type: integer
          example:
            CDG: 450
            IAD: 390
    Error:
      type: object
      properties:
        error:
          type: string
          example: Description of the error.
    RunDetail:
      allOf:
      - $ref: '#/components/schemas/Run'
      - type: object
        properties:
          boost_name:
            type: string
            example: Daily warm
          site_id:
            type: integer
            example: 42
    Run:
      type: object
      properties:
        id:
          type: integer
          example: 88
        boost_id:
          type: integer
          example: 15
        status:
          type: string
          enum:
          - pending
          - running
          - done
          - failed
          - paused
          example: done
        status_message:
          type: string
          nullable: true
        source_type:
          type: string
          enum:
          - sitemap
          - csv
          - inline
          description: How the run's URL list was determined. `inline` means URLs were submitted directly via the warm endpoint.
        source_urls:
          type: array
          nullable: true
          items:
            type: string
          description: URLs submitted for warming. Only populated for `inline` runs.
          example:
          - https://www.example.com/
          - https://www.example.com/about
        run_region:
          type: array
          nullable: true
          items:
            type: string
          description: Booster regions used for this run. Only populated for `inline` runs.
          example:
          - fr
          - us
        started_at:
          type: string
          format: date-time
          nullable: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        summary:
          $ref: '#/components/schemas/RunSummary'
        created_at:
          type: string
          format: date-time
  responses:
    NotFound:
      description: Resource not found or not accessible with this key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Valid key but missing required scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key in the format `cb_live_<32hex>`