# Report changes API

> Tell Relia about deploys, config changes and feature flags it can't see, from CI or a script, with one HTTP call.

Section: Reference · Page: https://tryrelia.com/docs/report-changes-api · Last checked against the product: 2026-11-01

Relia sees a deploy by itself when a service starts sending a new version. For changes it can't see (a deploy before your app reports a version, a config edit, a feature flag), send one call to `POST /api/v1/changes`. A reported **deploy with a version** starts fix verification for open incidents on that service and is what Relia suggests rolling back to; other changes appear as recent changes on incidents that start soon after.

Base address: `https://devreliaapi.tryrelia.com`

## POST /api/v1/changes

Records one change.

### Authentication

| Method | How | Who |
|---|---|---|
| Project key | Header `X-Relia-Key: relia_live_…` (or `Authorization: Bearer relia_live_…`) | CI and scripts. Find the key on your project page under **Setup Guide & SDK**. |
| Signed in | A Relia sign-in | Owners, admins and members of the project (not viewers). This is how the `relia_report_change` MCP tool sends it. |

A key that belongs to another project is refused. Without a key or a sign-in the answer is 401.

### Body (JSON)

| Field | Type | Required | What it is | Default |
|---|---|---|---|---|
| `project_id` | string (up to 64) | Yes | Your Relia project id. | |
| `service` | string (up to 120) | No | The service that changed, as named in Relia. | `""` |
| `kind` | `deploy`, `config`, `flag` or `other` | No | What kind of change. | `deploy` |
| `version` | string (up to 80) | No | The new version (a tag or commit). | `""` |
| `previous_version` | string (up to 80) | No | The version before. | `""` |
| `note` | string (up to 500) | No | A short description. | `""` |
| `at` | ISO 8601 date-time | No | When it happened. A time without a zone is read as UTC. Kept within the last 24 hours and never in the future: older times become 24 hours ago, future times become now. | Now |

### Response

`201 Created`

```json
{ "id": "6a7f…", "at": "2026-11-01T09:30:00+00:00" }
```

| Status | Meaning |
|---|---|
| `201` | Recorded. |
| `401` | No key and not signed in, or the key doesn't belong to this project. |
| `403` | Signed in as a viewer, or not a member of the project. |
| `404` | The project doesn't exist. |
| `422` | A field is missing, too long, or `kind` is not one of the four values. |
| `429` | More than 120 calls in an hour from one address. Wait and retry. |

### Examples

A deploy, from a terminal or any CI:

```bash
curl -X POST https://devreliaapi.tryrelia.com/api/v1/changes \
  -H "Content-Type: application/json" \
  -H "X-Relia-Key: $RELIA_KEY" \
  -d '{"project_id": "'"$RELIA_PROJECT_ID"'", "service": "checkout", "kind": "deploy", "version": "1.4.3", "previous_version": "1.4.2"}'
```

A feature flag turned on:

```bash
curl -X POST https://devreliaapi.tryrelia.com/api/v1/changes \
  -H "Content-Type: application/json" \
  -H "X-Relia-Key: $RELIA_KEY" \
  -d '{"project_id": "'"$RELIA_PROJECT_ID"'", "service": "web", "kind": "flag", "note": "new-checkout on for 50% of visitors"}'
```

A GitHub Actions step after your deploy step (store the key and id as repository secrets):

```yaml
- name: Tell Relia about the deploy
  run: |
    curl -sS -X POST https://devreliaapi.tryrelia.com/api/v1/changes \
      -H "Content-Type: application/json" \
      -H "X-Relia-Key: ${{ secrets.RELIA_KEY }}" \
      -d '{"project_id": "${{ secrets.RELIA_PROJECT_ID }}", "service": "api", "kind": "deploy", "version": "${{ github.sha }}"}'
```

> **Tip:** your AI assistant can send the same report with the `relia_report_change` tool, after you confirm. See [MCP tools](https://tryrelia.com/docs/mcp-tools.md).

## GET /api/v1/changes

Lists a project's reported changes, newest first. For signed-in members of the project (any role); the project key is not accepted here.

| Query parameter | Required | What it is | Default |
|---|---|---|---|
| `project_id` | Yes | Your Relia project id. | |
| `limit` | No | How many, 1 to 200. | `50` |

Response:

```json
{
  "changes": [
    { "id": "6a7f…", "service": "checkout", "kind": "deploy", "version": "1.4.3", "note": "", "at": "2026-11-01T09:30:00+00:00" }
  ]
}
```

To see changes from your editor instead, ask your AI assistant: it uses `relia_changes`, which also lists the deploys Relia saw by itself.

## Next

- [Did my deploy break anything?](https://tryrelia.com/docs/did-my-deploy-break.md)
- [From alert to verified fix](https://tryrelia.com/docs/fix-and-verify.md)
- [MCP tools](https://tryrelia.com/docs/mcp-tools.md)
- [Environment variables](https://tryrelia.com/docs/environment-variables.md)

---
All Relia docs for AI assistants: https://tryrelia.com/llms.txt (index) · https://tryrelia.com/llms-full.txt (everything in one file)
