> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/integrations/deployment-integrations/api.md).

# API deployment pipeline

Post deployment events to ilert from any system that can make an HTTP request, and enrich alerts with what changed just before they fired.

Where no native integration fits — a bespoke rollout script, a release tool ilert has no connector for, or something that is not a software deployment at all — an **API** pipeline gives you an integration key and an endpoint, and leaves the payload to you.

## Create the pipeline

Follow [Create a deployment pipeline](/integrations/deployment-integrations.md#create-a-deployment-pipeline) and choose type **API**. An API pipeline has no branch or event filters: it records everything you post to it, so filtering is yours to do on the sending side.

The detail view then shows the **Integration key** you will post with.

## Send a deployment event

`POST` to `https://api.ilert.com/api/deployment-events` with the key in the body. No authentication header is needed — the integration key is the credential.

```bash
curl --request POST \
  --url https://api.ilert.com/api/deployment-events \
  --header 'Content-Type: application/json' \
  --data '{
    "integrationKey": "YOUR_INTEGRATION_KEY",
    "summary": "Checkout service v4.12.0 rolled out to production",
    "timestamp": "2026-08-31T22:17:38Z",
    "userEmail": "helena.guzman@acme.example",
    "customDetails": { "service": "checkout", "environment": "production" },
    "links": [
      { "href": "https://github.com/acme/checkout/releases/tag/v4.12.0", "text": "Release notes" }
    ]
  }'
```

| Field            | Required | Notes                                                                                                                                                                                         |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `integrationKey` | Yes      | From the pipeline's detail view                                                                                                                                                               |
| `summary`        | Yes      | The one line shown on the deployment row and on any alert it is correlated with                                                                                                               |
| `timestamp`      | No       | Epoch seconds, epoch milliseconds, or an ISO 8601 string. Defaults to the time the event arrives — set it explicitly when you post after the fact, because correlation is entirely time-based |
| `userEmail`      | No       | Maps the deployment to an ilert user, so the row shows who shipped it                                                                                                                         |
| `customDetails`  | No       | Any JSON object. Shown on the deployment's detail view                                                                                                                                        |
| `links`          | No       | `href` and `text` pairs, surfaced as links on the deployment                                                                                                                                  |

The full reference is in the [REST API documentation](https://api.ilert.com/api-docs/#tag/deployment-events/post/deployment-events).

## Confirm it arrived

{% hint style="warning" %}
**`202` does not mean the event landed.** The endpoint accepts and queues the request before it looks at the integration key, so a wrong, rotated, or truncated key returns `202 Accepted` exactly like a correct one, and the event is discarded afterwards. Nothing on the sending side can tell the difference.

Check **Alerting** → **Deployment events** instead. The row is the only confirmation there is.
{% endhint %}

## Deployment events are not only for deployments

The pipeline records timestamped facts and correlates them with alerts, and nothing in it is specific to software releases. Anything that changes the state of a system and might explain an alert 20 minutes later is a reasonable event to post — a campaign going live, a price list being published, a batch of goods moving, a compliance release, a course opening for enrollment.

If it can break something, it is worth having on the alert.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.ilert.com/integrations/deployment-integrations/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.