# Create Incident API

## 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 may vary depending on your organization's configuration. Please make sure to select the appropriate base URL according to your setup.

The URL will be either of these:

**`https://app.hivel.ai`**  OR  **`https://app.hivel.in`**

***

### 🔑 Authentication

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

```
Authorization: YOUR_ORGANIZATION_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**<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&#x26;token=0869583b-b6f0-4cda-a6b1-bd1ffc53c640" alt="" width="310"><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&#x26;token=2759fa06-84bf-4094-879e-8b10ee6d4281" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FoXU4heOSD8LS7QSB9Ve5%2Fimage%20(99).png?alt=media&#x26;token=c9958254-4dd1-4120-ba69-a1074ce45ddc" 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
* `500` - Internal Server Error