{
  "openapi": "3.1.0",
  "info": {
    "title": "Squadcast Organization-Scoped Public APIs",
    "version": "2024-08-11",
    "description": "## Overview\nThe Squadcast Organization-Scoped API provides organization-level operations for managing Squadcast resources at scale. This API currently supports a limited set of operations that are not scoped to individual users, enabling system automation and organization-wide API operations that don't require user context. For operations not available here, the User-Scoped APIs are the only option for now. It's ideal for programmatic access to organization-level resources and integration workflows.\n\n### Service Regions\n\nSquadcast allows customers to choose the geographic region of the Squadcast data centers that host their account. When signing up, you can choose the service region. Currently, the available options are the United States (US) and Europe (EU).\n\n| Service Region | API Endpoints |\n|---|---|\n| US | https://api.squadcast.com |\n| EU | https://api.eu.squadcast.com |\n\n### Authentication\n\nIn order to access the Organization-Scoped APIs, you need to use API key authentication. The API key can be passed as a Bearer token in the `Authorization` header.\n\nSteps to procure an API key:\n\n1. Log in to the Squadcast web application.\n2. Navigate to Settings > API Tokens.\n3. Create a new API token. This is the API key you'll use for authentication. **Important:** The token will only be visible once after creation. Copy and store it securely, as it will be gone forever once you close the dialog or navigate away.\n4. Pass the API key in the `Authorization` header for all subsequent API requests.\n\n#### Example — Using API Key\n\n```bash\ncurl --location --request GET 'https://api.squadcast.com/v4/public/api-key' \\\n--header 'Authorization: Bearer YOUR_API_KEY'\n```\n\n### Access Control\n\nOnly users with the \"API Tokens\" permission can access, create, and delete Organization-Scoped APIs. API access controls are determined by the purpose and permissions of the token selected during token creation. Ensure your API token has the necessary permissions for the operations you intend to perform."
  },
  "tags": [
    {
      "name": "API Key"
    },
    {
      "name": "Requests"
    },
    {
      "name": "Incidents"
    }
  ],
  "paths": {
    "/v4/public/api-key": {
      "get": {
        "operationId": "ApiKeyRoutes_getApiKey",
        "summary": "Get API Key",
        "description": "Requires valid API key authentication in the Authorization header.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "API key details including organization ID, creation date, expiration, and usage information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyResponse"
                }
              }
            }
          }
        },
        "tags": [
          "API Key"
        ]
      }
    },
    "/v4/public/incidents/acknowledge": {
      "post": {
        "operationId": "IncidentOperations_bulkAcknowledgeIncidents",
        "summary": "Bulk Acknowledge Incidents",
        "description": "Acknowledges multiple incidents in a single operation.\nMaximum 20 incidents can be acknowledged per request.\nReturns success and failure details for each incident.\n\nRequires `incidents:write` permission.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bulk response with success and error items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "meta",
                    "data",
                    "errors"
                  ],
                  "properties": {
                    "meta": {
                      "$ref": "#/components/schemas/Common.V4.BulkMeta"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Incidents.BulkAcknowledgeSuccess"
                      }
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Incidents.BulkAcknowledgeError"
                      }
                    }
                  },
                  "description": "Generic response for bulk operations with success and error items"
                }
              }
            }
          }
        },
        "tags": [
          "Incidents"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Incidents.BulkAcknowledgeRequest"
              }
            }
          },
          "description": "Request containing array of incident IDs"
        }
      }
    },
    "/v4/public/incidents/ids": {
      "post": {
        "operationId": "IncidentOperations_listIncidentsByIDs",
        "summary": "List Incidents By IDs",
        "description": "Retrieves detailed information for a list of incidents in the organization.\nMaximum 50 incidents can be fetched in a single request.\n\nRequires `incidents:read` permission.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Array of incident details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Incidents.BaseIncident"
                  }
                }
              }
            }
          }
        },
        "tags": [
          "Incidents"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Incidents.ListIncidentsByIDsRequest"
              }
            }
          },
          "description": "Request containing array of incident IDs"
        }
      }
    },
    "/v4/public/incidents/reassign": {
      "post": {
        "operationId": "IncidentOperations_bulkReassignIncidents",
        "summary": "Bulk Reassign Incidents",
        "description": "Reassigns multiple incidents to a specified user or squad in a single operation.\nMaximum 20 incidents can be reassigned per request.\nReturns success and failure details for each incident.\n\nRequires `incidents:write` permission.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Bulk response with success and error items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "meta",
                    "data",
                    "errors"
                  ],
                  "properties": {
                    "meta": {
                      "$ref": "#/components/schemas/Common.V4.BulkMeta"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Incidents.BulkReassignSuccess"
                      }
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Incidents.BulkReassignError"
                      }
                    }
                  },
                  "description": "Generic response for bulk operations with success and error items"
                }
              }
            }
          }
        },
        "tags": [
          "Incidents"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Incidents.BulkReassignRequest"
              }
            }
          },
          "description": "Request containing incident IDs and reassignment target"
        }
      }
    },
    "/v4/public/requests/{requestID}/status": {
      "get": {
        "operationId": "RequestStatusRoutes_getRequestStatus",
        "summary": "Get Incident Status By Request",
        "description": "Allows checking the status of request ingestion.",
        "parameters": [
          {
            "name": "requestID",
            "in": "path",
            "required": true,
            "description": "The ID of the ingestion request to check status for",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status of the ingestion request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestStatusResponse"
                }
              }
            }
          }
        },
        "tags": [
          "Requests"
        ]
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "schemas": {
      "ApiKeyResponse": {
        "type": "object",
        "required": [
          "orgID",
          "createdAt",
          "isNeverExpires",
          "preferredUsage"
        ],
        "properties": {
          "orgID": {
            "type": "string",
            "description": "The organization ID associated with the API key."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp when the API key was created."
          },
          "expiresAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ],
            "description": "The timestamp when the API key expires (nullable if never expires)."
          },
          "isNeverExpires": {
            "type": "boolean",
            "description": "Whether the API key never expires."
          },
          "preferredUsage": {
            "type": "string",
            "description": "The preferred usage of the API key."
          }
        },
        "description": "Represents an API key for organization-scoped access."
      },
      "Common.V4.BulkMeta": {
        "type": "object",
        "required": [
          "total",
          "success",
          "failed"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "format": "int32"
          },
          "success": {
            "type": "integer",
            "format": "int32"
          },
          "failed": {
            "type": "integer",
            "format": "int32"
          }
        },
        "description": "Metadata for bulk operation responses"
      },
      "Incidents.AssignedTo": {
        "type": "object",
        "required": [
          "id",
          "name",
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the assigned entity."
          },
          "name": {
            "type": "string",
            "description": "The name of the assigned entity."
          },
          "type": {
            "type": "string",
            "enum": [
              "user",
              "squad",
              "escalationpolicy"
            ],
            "description": "The type of the assigned entity (user, squad, or escalationpolicy)."
          }
        },
        "description": "Represents an entity that an incident is assigned to."
      },
      "Incidents.BaseIncident": {
        "type": "object",
        "required": [
          "id",
          "status",
          "assignedTo",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The unique identifier of the incident."
          },
          "status": {
            "type": "string",
            "description": "The current status of the incident."
          },
          "assignedTo": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Incidents.AssignedTo"
              }
            ],
            "description": "The entity currently assigned to the incident."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp when the incident was created."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "The timestamp when the incident was last updated."
          }
        },
        "description": "Represents a basic incident in the organization-scoped API."
      },
      "Incidents.BulkAcknowledgeError": {
        "type": "object",
        "required": [
          "id",
          "error"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The incident ID that failed to acknowledge."
          },
          "error": {
            "type": "string",
            "description": "Error message describing why the operation failed."
          }
        },
        "description": "Error item in a bulk acknowledge operation."
      },
      "Incidents.BulkAcknowledgeRequest": {
        "type": "object",
        "required": [
          "incidentIDs"
        ],
        "properties": {
          "incidentIDs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "description": "Array of incident IDs to acknowledge (max 20 items)."
          }
        },
        "description": "Request body for bulk acknowledging incidents."
      },
      "Incidents.BulkAcknowledgeSuccess": {
        "type": "object",
        "required": [
          "id",
          "message"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The incident ID that was successfully acknowledged."
          },
          "message": {
            "type": "string",
            "description": "Success message."
          }
        },
        "description": "Success item in a bulk acknowledge operation."
      },
      "Incidents.BulkReassignError": {
        "type": "object",
        "required": [
          "id",
          "error"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The incident ID that failed to reassign."
          },
          "error": {
            "type": "string",
            "description": "Error message describing why the operation failed."
          }
        },
        "description": "Error item in a bulk reassign operation."
      },
      "Incidents.BulkReassignRequest": {
        "type": "object",
        "required": [
          "incidentIDs",
          "reassignToID",
          "reassignToType"
        ],
        "properties": {
          "incidentIDs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "description": "Array of incident IDs to reassign (max 20 items)."
          },
          "reassignToID": {
            "type": "string",
            "description": "The ID of the entity to reassign incidents to."
          },
          "reassignToType": {
            "type": "string",
            "enum": [
              "user",
              "squad"
            ],
            "description": "The type of entity to reassign to (user or squad)."
          }
        },
        "description": "Request body for bulk reassigning incidents."
      },
      "Incidents.BulkReassignSuccess": {
        "type": "object",
        "required": [
          "id",
          "message"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The incident ID that was successfully reassigned."
          },
          "message": {
            "type": "string",
            "description": "Success message."
          }
        },
        "description": "Success item in a bulk reassign operation."
      },
      "Incidents.ListIncidentsByIDsRequest": {
        "type": "object",
        "required": [
          "incidentIDs"
        ],
        "properties": {
          "incidentIDs": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 50,
            "description": "Array of incident IDs to fetch (max 50 items)."
          }
        },
        "description": "Request body for listing incidents by IDs."
      },
      "RequestStatus": {
        "type": "string",
        "enum": [
          "created",
          "deduplicated",
          "suppressed",
          "discarded",
          "error"
        ],
        "description": "Represents the status of an ingestion request."
      },
      "RequestStatusResponse": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The request ID."
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RequestStatus"
              }
            ],
            "description": "The status of the request."
          },
          "incidentID": {
            "type": "string",
            "description": "The incident ID associated with the request (if available)."
          },
          "eventID": {
            "type": "string",
            "description": "The event ID associated with the request (if available)."
          }
        },
        "description": "Response containing the status of a single ingestion request."
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "servers": [
    {
      "url": "https://api.eu.squadcast.com",
      "description": "production EU env",
      "variables": {}
    },
    {
      "url": "https://api.squadcast.com",
      "description": "production US env",
      "variables": {}
    }
  ]
}