Announcements API

Endpoints

`GET /api/announcements`

List all announcements, most recent first. Includes author info and read status for the current user.

Permission: view:announcements

Query params:

category — optional filter: process, team, client, or company

Response:

{
  "announcements": [
    {
      "id": "uuid",
      "title": "New process update",
      "content": "Full text content",
      "category": "process",
      "attachment_url": "https://...",
      "attachment_name": "Process Doc",
      "author_id": "uuid",
      "author_name": "Name",
      "author_picture": "https://...",
      "created_at": "2026-03-01T10:00:00",
      "updated_at": "2026-03-01T10:00:00",
      "is_read": 0
    }
  ]
}

`GET /api/announcements/unread-count`

Returns the number of unread announcements for the current user. Used for the sidebar badge.

Permission: view:announcements

Response: { "unread_count": 5 }

`GET /api/announcements/:id`

Get a single announcement with read receipts (receipts only returned for Head/Executive users).

Permission: view:announcements

Response:

{
  "announcement": { ... },
  "read_receipts": [
    { "user_id": "uuid", "user_name": "Name", "read_at": "2026-03-01T10:00:00" }
  ]
}

`POST /api/announcements`

Create a new announcement. Author is set from the authenticated session.

Permission: update:announcements (Head, Executive)

Body:

{
  "title": "string (required)",
  "content": "string (required)",
  "category": "process|team|client|company (required)",
  "attachment_url": "string (optional)",
  "attachment_name": "string (optional)"
}

`PUT /api/announcements/:id`

Update an announcement. Only the original author or an Executive can edit.

Permission: update:announcements

Body: Same fields as POST, all optional for partial update.

`DELETE /api/announcements/:id`

Delete an announcement. Read receipts are cascade-deleted.

Permission: manage:announcements (Executive only)

`POST /api/announcements/:id/read`

Mark an announcement as read for the current user. Idempotent (safe to call multiple times).

Permission: view:announcements

Response: { "ok": true }

`GET /api/announcements/:id/distributions`

Get distribution history for an announcement (which channels it has been posted to).

Permission: view:announcements

Response:

{
  "distributions": [
    {
      "id": "uuid",
      "announcement_id": "uuid",
      "channel": "slack",
      "status": "sent",
      "external_id": "1234567890.123456",
      "error": null,
      "sent_by": "uuid",
      "sent_by_name": "Name",
      "sent_at": "2026-03-02T10:00:00"
    }
  ]
}

`POST /api/announcements/:id/distribute`

Distribute an announcement to selected external channels. Same permission as editing (author or Executive).

Permission: update:announcements

Body:

{
  "slack": true,
  "google_calendar": {
    "date": "2026-03-05",
    "start_time": "09:00",
    "end_time": "10:00"
  },
  "email": true
}

slack — Post to configured Slack channel
google_calendar — Create calendar event. date required, start_time/end_time optional (omit for all-day)
email — Send via Gmail API to configured destination address

Response:

{
  "results": {
    "slack": { "status": "sent", "external_id": "1234567890.123456" },
    "google_calendar": { "status": "sent", "external_id": "event-id" },
    "email": { "status": "failed", "error": "SEND_EMAIL binding not configured" }
  }
}