Skip to main content

​
Overview

The Rootly API allows you to create incidents automatically from monitoring tools, CI/CD pipelines, internal services, or any external automation system. This is the preferred method when you need:
  • Deterministic and repeatable incident creation
  • Automated declarations from alerting or detection systems
  • Consistent metadata applied across incidents
  • The ability to create sub-incidents within orchestrated workflows
  • Fully headless incident creation with no human intervention
API-based creation ensures incidents follow the same lifecycle rules, validations, and workflows as incidents created through Slack or the Web UI. More details are available in the API documentation.

​
Before You Begin

Before creating incidents via API, ensure you have:
  • A Rootly API token with permissions to create incidents
  • Knowledge of any required fields (severity, type, environments, etc.)
  • IDs for any contextual fields you intend to populate:
    • Services
    • Functionalities
    • Environments
    • Groups
    • Incident types
    • Custom form fields
  • The Create Incident endpoint reference: POST /api/v1/incidents
To avoid validation failures, review which fields are required under Configuration → Forms and Configuration → Required Fields.

​
Creating an Incident via API

1

Send a POST request to the Create Incident endpoint

Requests must include:
Any HTTP client or automation system (Python, curl, Terraform, GitHub Actions, etc.) will work.
2

Include the required and optional fields

Below are the commonly used fields.Core fields
  • title
  • summary
  • severity_id
  • incident_type_ids
  • private (boolean)
  • notify_emails (array — used by workflows, not auto-emailed by default)
Contextual fields
  • service_ids
  • functionality_ids
  • environment_ids
  • group_ids
Custom form fieldsUse form_field_selections to populate custom data.Supports all field types: text, dropdowns, multi-select, relations, user selectors, catalog entities, etc.Optional advanced fields
  • parent_incident_id — creates a sub-incident
  • create_test_incident — only works if the Test Incidents feature is enabled
  • mitigation_message, resolution_message, cancellation_message
  • Lifecycle timestamps (advanced):
    • in_triage_at, started_at, mitigated_at, resolved_at, closed_at
To create sub-incidents programmatically, provide parent_incident_id. Rootly automatically links the child to the parent.
3

Review the API response

A successful response includes:
  • The incident ID
  • Lifecycle status
  • Timestamps
  • A URL to open the incident in the web app
  • Slack channel details (if Slack is integrated + auto-create enabled)
You can use these details to perform follow-up actions like:
  • Posting timeline entries
  • Updating lifecycle status
  • Attaching alerts
  • Triggering or monitoring workflows

​
Example Request Payloads

Basic example
With custom fields
Creating a sub-incident

​
Validation & Error Handling

Rootly returns standard error responses for debugging and automation safety. 401 Unauthorized
403 Forbidden
422 Validation Errors
Idempotency (Recommended) To prevent duplicate incidents during retries:

​
Troubleshooting

Ensure required fields in Forms or Required Fields are included.
Check that workflow conditions (severity, type, service, etc.) match the payload.
Verify:
  • Slack is connected
  • Auto-create channels is enabled
  • Incident is not private (depending on settings)

​
Best Practices

  • Pre-fill key metadata to streamline response
  • Use structured fields (services, environments, types) for better analytics
  • Use private incidents for security-sensitive or customer-specific events
  • Follow consistent naming conventions across automated incidents
  • Use idempotency keys to prevent duplication
  • Automate creation of sub-incidents for multi-team or multi-domain issues
  • Avoid manually setting lifecycle timestamps unless necessary