> ## Documentation Index
> Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer <your API key>.
> Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs.
> A 429 response carries a Retry-After header, in seconds, when the limit has a known wait. Authenticated responses can carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset for the per-minute request budget your SocialAPI account shares across every API key (see /guides/rate-limits).
> Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page.
> Treat every ID as an opaque string: do not parse it or assume a format.
> Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported.

# Announcements

> Read SocialAPI maintenance windows, incidents, product updates, and breaking changes through the API, and mark each one as seen.

Announcements are service notices that SocialAPI publishes: scheduled maintenance, incidents, product updates, and breaking changes. Every SocialAPI account receives the same announcements, and there is nothing to subscribe to.

Poll `GET /v1/announcements` from your own app and show new notices to your team, so they hear about a maintenance window before it starts. Both endpoints cost no credits, and any valid key can call them, including a [scoped key](https://docs.social-api.ai/guides/scoped-keys.md). There is no API to create, edit, or delete an announcement.

## Endpoints

| Method | Path | Description |
| - | - | - |
| `GET` | `/v1/announcements` | List the announcements on display, newest first |
| `POST` | `/v1/announcements/{id}/seen` | Mark an announcement as seen |

## List announcements

```bash theme={null}
curl https://api.social-api.ai/v1/announcements \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

Response (HTTP 200):

```json theme={null}
{
  "data": [
    {
      "id": "9c1e7f2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b",
      "kind": "maintenance",
      "title": "Scheduled maintenance",
      "body": "We are upgrading our servers. Publishing and inbox reads will be unavailable for up to 2 hours.",
      "link_url": "https://status.social-api.ai",
      "link_label": "Status page",
      "window_start": "2026-10-18T02:00:00Z",
      "window_end": "2026-10-18T04:00:00Z",
      "seen": false
    }
  ],
  "count": 1
}
```

An empty `data` array means there is nothing to announce.

| Field | Description |
| - | - |
| `id` | The announcement's ID, a UUID |
| `kind` | `maintenance`, `incident`, `product_update`, or `breaking_change` |
| `title`, `body` | The notice's headline and text |
| `link_url`, `link_label` | A page with more detail and the text for the link. Absent when the announcement has no link |
| `window_start`, `window_end` | The announced downtime, in UTC. Absent when the announcement has no downtime window. Show them in the reader's time zone |
| `seen` | `true` once your SocialAPI account marked the announcement as seen |

An announcement is listed during its display period, which the API does not return. The display period is separate from `window_start` and `window_end`, which describe the announced downtime.

## Mark an announcement as seen

```bash theme={null}
curl -X POST https://api.social-api.ai/v1/announcements/9c1e7f2a-3b4d-4e5f-8a9b-0c1d2e3f4a5b/seen \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

Response (HTTP 200):

```json theme={null}
{ "ok": true }
```

`seen` belongs to your SocialAPI account, not to a key. Marking an announcement as seen with any API key sets `seen` to `true` for every key of the account. Marking it again changes nothing and returns the same response.

An ID that is not a UUID, or that matches no announcement, returns `404 resource.not_found`.

No MCP tool exposes announcements.

## Related

* [Status page](https://status.social-api.ai) for live incident status
* [Changelog](https://docs.social-api.ai/changelog.md) for every change to the API
* [Authentication](https://docs.social-api.ai/guides/authentication.md) for the keys that call these endpoints
* [Scoped API keys](https://docs.social-api.ai/guides/scoped-keys.md) for the endpoints every key can call, whatever its scopes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.