Hivel-managed

Overview

The Hivel Incident API enables submitting incident data to Hivel, allowing for precise calculation of metrics such as CFR (Change Failure Rate) and MTTR (Mean Time to Recovery).

---

Base URL

The base URL for accessing Hivel is: https://app.hivel.ai

---

Authentication

All requests require an organization API token. Pass this in the request header:

Authorization: X-API-Token

---

Retrieving Your API Key

1. Open Hivel and navigate to Integrations under the Settings.

   
2. Click on Connect on Hivel API Authorization card

   
3. Follow the given steps to start your integration

4. By clicking on Generate your API Key will be generated.

---

Incident Events API

Endpoint

POST https://app.hivel.ai/api/hooks/v1/incident

Request Parameters

Field Name	Type	Description	Example
description	string	A detailed description of the incident (max 255 chars).	Database connection timeout error
severity Required	string	The severity level of the incident (e.g., low, medium, high, critical) (max 255 chars).	high
affected_systems	array	A list of systems affected by the incident.	["database", "backend"]
reported_time Required	string	The date and time when the incident occurred (ISO 8601 format).	2024-08-01T12:34:56Z
reported_by	string	The username or identifier of the person who reported the incident (max 255 chars).	jdoe
resolution_time Required	string	The date and time when the incident was resolved (ISO 8601 format).	2024-08-01T13:34:56Z
provider_id	string	The unique identifier of the incident in your incident management provider (max 255 chars).	incident-123456
repo_url Required	string	The URL of the repository related to the deployment or incident (max 255 chars).	https://github.com/your-repo/project
pr_number Required	string	The Pull Request (PR) identifier associated with the deployment.	44

Request Example

Example

curl --location 'https://app.hivel.ai/api/hooks/v1/incident' \
--header 'X-API-Token: YOUR_API_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data-raw '{
  "description": "Database connection timeout affecting API",
  "severity": "HIGH",
  "affected_systems": ["database", "api-gateway"],
  "reported_time": "2025-09-22T10:30:00Z",
  "reported_by": "[e-mail]",
  "resolution_time": "2025-09-22T11:15:00Z",
  "provider_id": "inc-20250922-1030",
  "repo_url": "https://github.com/hivelai/webhook-logger",
  "pr_number": "71"
}'

Response

200 - Successful

{
  "message": "Success",
  "incident_id": "incident-2024-08-01-12345",
}

• 400 - Bad Request

• 401 - Unauthorized

• 403 - Org inactive

• 500 - Internal Server Error

A request body that fails to parse as valid JSON, or has a field of the wrong type (e.g. a number where a string is expected), returns a 400 Bad Request with the specific parse error in error:

{
  "message": "Validation failed",
  "error": "Invalid JSON request body: json: cannot unmarshal number into Go struct field .pr_number of type string",
  "details": null,
  "correlation_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"
}