openapi: 3.1.0
info:
  title: Squadcast Public API
  description: |
    Public REST API for the Squadcast (SolarWinds Incidents Cloud) incident
    response and on-call management platform. The API exposes incident
    management operations — including bulk acknowledge/resolve, individual
    incident lookup, reassignment, priority updates, exports, and request
    status checks.

    Authentication uses HTTP Bearer access tokens. Access tokens are
    short-lived and exchanged from a long-lived refresh token via the
    `/oauth/access-token` endpoint on the auth host. Send subsequent API
    requests with `Authorization: Bearer <access_token>` against the regional
    API host.
  version: "3.0.0"
  contact:
    name: Squadcast Support
    url: https://support.squadcast.com/
servers:
  - url: https://api.squadcast.com
    description: US region API host
  - url: https://api.eu.squadcast.com
    description: EU region API host
  - url: https://auth.squadcast.com
    description: US region auth host (used only for /oauth/access-token)
  - url: https://auth.eu.squadcast.com
    description: EU region auth host (used only for /oauth/access-token)
tags:
  - name: Authentication
    description: Token exchange endpoints
  - name: Incidents
    description: Incident lifecycle and bulk operations
  - name: Requests
    description: Incident creation request status
security:
  - bearerAuth: []
paths:
  /oauth/access-token:
    get:
      tags:
        - Authentication
      summary: Exchange refresh token for access token
      description: |
        Exchange a long-lived refresh token (passed in the `X-Refresh-Token`
        header) for a short-lived bearer access token used on all other API
        calls. Call this against the auth host (`auth.squadcast.com` or
        `auth.eu.squadcast.com`).
      operationId: getAccessToken
      security: []
      parameters:
        - name: X-Refresh-Token
          in: header
          required: true
          description: Long-lived refresh token issued from the Squadcast console.
          schema:
            type: string
      responses:
        "200":
          description: Access token issued successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessTokenResponse"
        "401":
          description: Invalid or missing refresh token
  /v3/incidents/{incidentID}:
    get:
      tags:
        - Incidents
      summary: Get incident by ID
      description: Retrieve full details of a single incident by its identifier.
      operationId: getIncidentById
      parameters:
        - $ref: "#/components/parameters/IncidentID"
      responses:
        "200":
          description: Incident details
          content:
            application/json:
              schema:
                type: object
        "404":
          description: Incident not found
  /v3/incidents/{incidentID}/acknowledge:
    post:
      tags:
        - Incidents
      summary: Acknowledge an incident
      description: Acknowledge a single incident by ID.
      operationId: acknowledgeIncident
      parameters:
        - $ref: "#/components/parameters/IncidentID"
      responses:
        "200":
          description: Incident acknowledged
  /v3/incidents/{incidentID}/resolve:
    post:
      tags:
        - Incidents
      summary: Resolve an incident
      description: |
        Resolve a single incident by ID. A `resolution_reason` object describing
        why the incident is being resolved is required in the request body.
      operationId: resolveIncident
      parameters:
        - $ref: "#/components/parameters/IncidentID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - resolution_reason
              properties:
                resolution_reason:
                  type: object
                  required:
                    - message
                  properties:
                    message:
                      type: string
                      description: Free-form reason describing the resolution.
      responses:
        "200":
          description: Incident resolved
  /v3/incidents/{incidentID}/events:
    get:
      tags:
        - Incidents
      summary: List incident events
      description: Retrieve the event timeline for an incident with pagination.
      operationId: listIncidentEvents
      parameters:
        - $ref: "#/components/parameters/IncidentID"
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
        - name: limit
          in: query
          required: false
          description: Maximum number of events to return (max 10).
          schema:
            type: integer
            maximum: 10
        - name: sort
          in: query
          required: false
          schema:
            type: string
        - name: deduped
          in: query
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Paginated list of incident events
  /v3/incidents/{incidentID}/reassign:
    post:
      tags:
        - Incidents
      summary: Reassign an incident
      description: |
        Reassign an incident to a different user, escalation policy, or squad.
        The `reassignTo` object requires both an `id` and a `type`.
      operationId: reassignIncident
      parameters:
        - $ref: "#/components/parameters/IncidentID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reassignTo
              properties:
                reassignTo:
                  type: object
                  required:
                    - id
                    - type
                  properties:
                    id:
                      type: string
                    type:
                      type: string
                      enum:
                        - user
                        - escalationpolicy
                        - squad
      responses:
        "200":
          description: Incident reassigned
  /v3/incidents/{incidentID}/priority:
    patch:
      tags:
        - Incidents
      summary: Update a single incident's priority
      operationId: updateIncidentPriority
      parameters:
        - $ref: "#/components/parameters/IncidentID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - priority
              properties:
                priority:
                  type: string
      responses:
        "200":
          description: Incident priority updated
  /v3/incidents/acknowledge:
    post:
      tags:
        - Incidents
      summary: Bulk acknowledge incidents
      description: |
        Acknowledge up to 100 incidents in a single call. Rate limit: 10 calls
        per minute.
      operationId: bulkAcknowledgeIncidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkIncidentIds"
      responses:
        "200":
          description: Incidents acknowledged
  /v3/incidents/resolve:
    post:
      tags:
        - Incidents
      summary: Bulk resolve incidents
      description: |
        Resolve up to 100 incidents in a single call. Rate limit: 10 calls per
        minute.
      operationId: bulkResolveIncidents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BulkIncidentIds"
      responses:
        "200":
          description: Incidents resolved
  /v3/incidents/priority:
    put:
      tags:
        - Incidents
      summary: Bulk update incident priority
      operationId: bulkUpdateIncidentPriority
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - incident_ids
                - priority
              properties:
                incident_ids:
                  type: array
                  items:
                    type: string
                priority:
                  type: string
      responses:
        "200":
          description: Priorities updated
  /v3/incidents/export:
    get:
      tags:
        - Incidents
      summary: Export incidents
      description: Export incident details as CSV or JSON.
      operationId: exportIncidents
      parameters:
        - name: type
          in: query
          required: true
          description: Export format (e.g. csv, json).
          schema:
            type: string
        - name: start_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: end_time
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: owner_id
          in: query
          required: true
          schema:
            type: string
        - name: status
          in: query
          required: false
          schema:
            type: string
        - name: services
          in: query
          required: false
          schema:
            type: string
        - name: sources
          in: query
          required: false
          schema:
            type: string
        - name: assigned_to
          in: query
          required: false
          schema:
            type: string
        - name: priority
          in: query
          required: false
          schema:
            type: string
        - name: tags
          in: query
          required: false
          schema:
            type: string
        - name: slo_affecting
          in: query
          required: false
          schema:
            type: boolean
      responses:
        "200":
          description: Export payload
  /v3/incidents/export/async:
    post:
      tags:
        - Incidents
      summary: Export incidents asynchronously
      description: |
        Kick off an async export job. Returns 202 and emails the download link
        when the export completes.
      operationId: exportIncidentsAsync
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - owner_id
                - type
                - start_time
                - end_time
                - incident_filters
              properties:
                owner_id:
                  type: string
                type:
                  type: string
                start_time:
                  type: string
                  format: date-time
                end_time:
                  type: string
                  format: date-time
                incident_filters:
                  type: object
      responses:
        "202":
          description: Export job accepted
  /v3/requests/status:
    post:
      tags:
        - Requests
      summary: Check incident creation request status
      description: |
        Check the status of incident creation requests by their request IDs.
        Possible statuses include created, deduplicated, suppressed, discarded,
        or error.
      operationId: getRequestStatus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                request_ids:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Request statuses
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Bearer access token obtained via the `/oauth/access-token` endpoint on
        the auth host. Send as `Authorization: Bearer <access_token>`.
  parameters:
    IncidentID:
      name: incidentID
      in: path
      required: true
      description: Unique identifier of the incident.
      schema:
        type: string
  schemas:
    AccessTokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: Bearer token to use for subsequent API calls.
        expires_at:
          type: string
          format: date-time
          description: Expiration timestamp of the access token.
    BulkIncidentIds:
      type: object
      required:
        - incident_ids
      properties:
        incident_ids:
          type: array
          description: Up to 100 incident identifiers.
          maxItems: 100
          items:
            type: string