> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/integrations/deployments-and-incidents/incident-api/hivel-managed.md).

# 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**.<br>

   <figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FBmr0wKVXridd3vsOMGf0%2FScreenshot%202026-08-18%20at%205.28.40%E2%80%AFPM.png?alt=media&amp;token=bcb84e79-eca3-470e-a077-ac43462fb941" alt="" width="563"><figcaption></figcaption></figure>
2. Click on **Connect** on **Hivel API Authorization card**<br>

   <figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FpZ80VBIdJuv8BsrwZdOI%2Fimage.png?alt=media&amp;token=0869583b-b6f0-4cda-a6b1-bd1ffc53c640" alt=""><figcaption></figcaption></figure>
3. Follow the given steps to start your integration
4. By clicking on **Generate** your API Key will be generated.

<figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FRj7txCE1jkzHG2J822yp%2Fimage%20(98).png?alt=media&amp;token=2759fa06-84bf-4094-879e-8b10ee6d4281" alt="" width="375"><figcaption></figcaption></figure>

***

## Incident Events API

### Endpoint

<mark style="color:green;">`POST`</mark> `https://app.hivel.ai/api/hooks/v1/incident`

### **Request Parameters**

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

### **Request Example**

{% tabs %}
{% tab title="Example" %}
{% code lineNumbers="true" fullWidth="true" %}

```http
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": "alerts@company.com",
  "resolution_time": "2025-09-22T11:15:00Z",
  "provider_id": "inc-20250922-1030",
  "repo_url": "https://github.com/hivelai/webhook-logger",
  "pr_number": "71"
}'
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Response

{% tabs %}
{% tab title="200 - Successful" %}

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

{% endtab %}
{% endtabs %}

* `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`:

{% code expandable="true" %}

```
{
  "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"
}
```

{% endcode %}