# 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="/files/xUz4QAPGzKhHmg4F7LzQ" 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="/files/chS5SEQvJpm0394xZ2mY" alt="" width="375"><figcaption></figcaption></figure>

<figure><img src="/files/Yq9XCRQ7JdI8ePf8jMCL" 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hivel.ai/integrations/api-documentation/create-incident-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.