> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scaling.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Incident

> Creates a new incident in your organization.

Creates a new incident and sets its initial status to `investigating`. Pass `leadId` to assign a specific user, or `leadScheduleId` to let the server resolve the current on-call responder and attach a matching escalation policy — at least one is required.

## Request body

<ParamField body="title" type="string" required>
  Short title describing the incident. Must be between 1 and 100 characters.
</ParamField>

<ParamField body="description" type="string">
  Optional longer description providing additional context about the incident.
  Up to 10,000 characters.
</ParamField>

<ParamField body="severity" type="string" required>
  Severity level of the incident. One of `critical`, `high`, `medium`, or `low`.
</ParamField>

<Note>
  At least one of `leadId` or `leadScheduleId` is required so the paging path
  always has a target — a request without either is rejected with `400`.
</Note>

<ParamField body="leadId" type="string">
  User ID to assign directly as the incident lead. Use this when you already
  know exactly who should be paged (e.g. the engineer who shipped the change).
  If `leadScheduleId` is also supplied, `leadId` wins for the resolved lead and
  the schedule is still used to attach an escalation policy.
</ParamField>

<ParamField body="leadScheduleId" type="string">
  UUID of an on-call schedule. The server resolves the current on-call responder
  (honouring active overrides) as the incident lead and attaches an escalation
  policy whose layers target this schedule (if one exists). If no one is
  currently on-call, the incident is still created without a lead. Returns `404`
  if the schedule does not exist in your organization.
</ParamField>

<ParamField body="componentIds" type="array of string">
  UUIDs of affected components, up to 50. Each ID must reference a component in
  your organization, and duplicates are rejected.
</ParamField>

<Tip>
  Choose severity based on customer and business impact, not just technical scope:

  * **critical** — Full outage or data loss affecting all or most customers.
  * **high** — Significant degradation affecting a large portion of customers or a key feature.
  * **medium** — Partial degradation with a workaround available, or affecting a minority of customers.
  * **low** — Minor issue with minimal customer impact, or a cosmetic/non-functional defect.

  Setting the right severity ensures the correct on-call team is paged and escalation timelines are applied accurately.
</Tip>

## Response

Returns `201 Created` with the new incident.

<ResponseField name="data" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ResponseField name="id" type="string" required>
      Unique identifier for the incident (UUID).
    </ResponseField>

    <ResponseField name="orgId" type="string" required>
      The organization this incident belongs to.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Short title describing the incident.
    </ResponseField>

    <ResponseField name="severity" type="string" required>
      Severity level: `critical`, `high`, `medium`, or `low`.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Always `investigating` for a newly created incident.
    </ResponseField>

    <ResponseField name="affectedComponents" type="array of object" required>
      Components affected by this incident. Each entry has `id` and `name`.
      Empty array if no components were specified.
    </ResponseField>

    <ResponseField name="createdAt" type="string" required>
      ISO 8601 timestamp of when the incident was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="string" required>
      ISO 8601 timestamp of when the incident was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

| Status | Code                     | Description                                                                                                                                                   |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_component_id`   | One of the `componentIds` does not exist in your organization.                                                                                                |
| `400`  | `duplicate_component_id` | `componentIds` contains duplicate entries.                                                                                                                    |
| `400`  | —                        | Request body failed validation (e.g. `title` exceeds 100 characters, `severity` is not a valid value, or neither `leadId` nor `leadScheduleId` was supplied). |
| `401`  | `not_authorized`         | Missing or invalid API key.                                                                                                                                   |
| `404`  | `not_found`              | The `leadScheduleId` does not refer to a schedule in your organization.                                                                                       |
| `500`  | `server_error`           | An unexpected error occurred on our side.                                                                                                                     |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.scaling.cloud/v1/incidents" \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "title": "Payment service elevated error rate",
      "description": "The payment processing service is returning 5xx errors at 12% above baseline.",
      "severity": "critical",
      "leadScheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "componentIds": ["6ba7b810-9dad-11d1-80b4-00c04fd430c8"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "orgId": "org_01HX4K9MNPQRST",
      "title": "Payment service elevated error rate",
      "severity": "critical",
      "status": "investigating",
      "affectedComponents": [
        { "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "name": "Payments API" }
      ],
      "createdAt": "2025-04-07T08:23:11.000Z",
      "updatedAt": "2025-04-07T08:23:11.000Z"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "statusCode": 401,
    "type": "not_authorized_error",
    "code": "not_authorized",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "type": "invalid_request_error",
    "code": "invalid_component_id",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 404 theme={null}
  {
    "statusCode": 404,
    "type": "invalid_request_error",
    "code": "not_found",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```

  ```json 500 theme={null}
  {
    "statusCode": 500,
    "type": "invalid_error",
    "code": "server_error",
    "requestId": "d3e4f5a6-b7c8-9012-defa-bc1234567890"
  }
  ```
</ResponseExample>