Create an announcement · Ownrecord docs

Creates a banner shown at the top of the console of every organization in its audience (spec §39.1): all, or the organizations on some plans (plans: keys from data/platform/plans.yaml, e.g. growth). It shows from startsAt (default now) until endsAt, or until a staff member ends it (platform.announcements.end).

id is a slug you choose (3–40 lowercase letters, digits and hyphens), e.g. maintenance-2026-11-08. The message is plain text up to 280 characters, in the content style guide's voice: what happens, when, and what the reader needs to do, if anything. link (an https URL or a path such as /docs/…) adds "Learn more". critical is for incidents only. Platform admins only.

At a glance

REST: POST /api/v1/platform/announcements
MCP tool: platform_announcements_create
Operation ID: platform.announcements.create
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

Body

A JSON object (Content-Type: application/json):

Field	Type	Required	Description
`id`	string	Yes	A slug you choose, e.g. `maintenance-2026-11-08`.
`message`	string	Yes	Plain text, up to 280 characters.
`severity`	one of `info`, `warning`, `critical`	Yes	`info`, `warning` or `critical` (incidents).
`link`	string	No	https URL or `/path`.
`audience`	object	Yes	`{ kind: all }` or `{ kind: plans, plans: [plan keys] }`.
`startsAt`	date-time	No	When it starts showing (default: now).
`endsAt`	date-time	No	When it stops showing (default: until ended).

Response

201 Created 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

Planned maintenance for everyone

HTTP

POST /api/v1/platform/announcements
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "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"
}

Response (201):

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": null,
  "endedBy": null,
  "current": false,
  "state": "scheduled",
  "createdBy": "usr_01m5wvkry1e6w94sjxgme33fsa",
  "createdAt": "2026-11-03T09:00:00.000Z",
  "version": 1
}

Errors

Code	HTTP status	When	What to do
`already_exists`	409	An announcement already has this `id`.	Use a different value, or fetch the existing object and update it.
`validation_failed`	400	A field is invalid: an unknown plan key, a link that isn't https or a path, or `endsAt` not after `startsAt`.	Fix the fields listed in `details.issues` and send the request again.
`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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Planned maintenance for everyone#

Errors#