# End an announcement

> The platform.announcements.end operation: POST /api/v1/platform/announcements/{id}/end in the REST API and the platform_announcements_end tool in the MCP server.

Stops showing an announcement now (spec §39.1). It stays in the list with when and by whom it was ended. Ending an
announcement that already ended changes nothing. Platform admins only.

## At a glance

- **REST:** `POST /api/v1/platform/announcements/{id}/end`
- **MCP tool:** `platform_announcements_end`
- **Operation ID:** `platform.announcements.end`
- **Scope:** Platform
- **Permission:** `platform:write`
- **Risk tier:** `write`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` required
- **Modes:** Test and live
- **Authentication:** API key with the `platform:write` scope
- **Since:** M12

## Request

### Path parameters

| Field | Type   | Description              |
| ----- | ------ | ------------------------ |
| `id`  | string | The announcement's slug. |

### Body

This operation takes no body.

## Response

`200 OK` with a JSON object:

| Field       | Type                                               | Description                                                                              |
| ----------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `object`    | `"platform_announcement"`                          |                                                                                          |
| `id`        | string                                             | The announcement's slug.                                                                 |
| `message`   | string                                             |                                                                                          |
| `severity`  | one of `info`, `warning`, `critical`               |                                                                                          |
| `link`      | string or null                                     |                                                                                          |
| `audience`  | object                                             |                                                                                          |
| `startsAt`  | date-time                                          |                                                                                          |
| `endsAt`    | date-time or null                                  |                                                                                          |
| `endedAt`   | date-time or null                                  |                                                                                          |
| `endedBy`   | `usr_…` ID or null                                 |                                                                                          |
| `current`   | boolean                                            | Whether it shows now.                                                                    |
| `state`     | one of `scheduled`, `showing`, `finished`, `ended` | `scheduled` (starts later), `showing`, `finished` (past `endsAt`) or `ended` (by staff). |
| `createdBy` | `usr_…` ID                                         |                                                                                          |
| `createdAt` | date-time                                          |                                                                                          |
| `version`   | integer                                            |                                                                                          |

## Examples

### End the maintenance notice early

```http
POST /api/v1/platform/announcements/maintenance-2026-11-08/end
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
```

Response (`200`):

```json
{
  "object": "platform_announcement",
  "id": "maintenance-2026-11-08",
  "message": "Planned maintenance on Sunday, November 8, 02:00–02:30 UTC. Checkout and the API stay up.",
  "severity": "info",
  "link": "/docs",
  "audience": {
    "kind": "all"
  },
  "startsAt": "2026-11-05T00:00:00.000Z",
  "endsAt": "2026-11-08T03:00:00.000Z",
  "endedAt": "2026-11-08T02:31:00.000Z",
  "endedBy": "usr_01m5wvkry1e6w94sjxgme33fsa",
  "current": false,
  "state": "ended",
  "createdBy": "usr_01m5wvkry1e6w94sjxgme33fsa",
  "createdAt": "2026-11-03T09:00:00.000Z",
  "version": 2
}
```

## Errors

| Code                                                                                     | HTTP status | When                                              | What to do                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | No announcement has this ID.                      | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)     | 409         | The announcement changed at the same time; retry. | Fetch the object again and retry the change.                                                         |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)   | 403         | You aren't a platform admin.                      | Ask an organization owner or admin for a role or scope that allows this action.                      |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).