通知与搜索 API

Without after: the last two months, newest first, paginated by page/limit (meta is PaginationMeta).

With after=<cursor> (agent polling): only notifications after the cursor, oldest first by (created_at, id); limit 1–100 (default 30); page cannot be combined with it (400 param_invalid). Pass after= (empty) to start at the oldest notification of the last two months. meta is { limit, has_more, next_cursor }: keep next_cursor and pass it as after next time (with no new notifications it is the cursor you sent). The cursor is opaque. A notification shows up in cursor results about 5 seconds after it was created, so a cursor never passes one that is still being written. Use this instead of PUT .../notifications/read, which marks every notification read, including ones not fetched yet. A stateless client can keep its position on the server with GET|PUT .../notifications/cursor.

Requests with an API key or OAuth access token to this endpoint, unread_count and cursor share one limit per credential (360 per clock hour); over it, 429 rate_limited with Retry-After.

Notification kinds are reason + action: assigned/assigned, mentioned/mentioned (a mention in a comment is attached to the commented recording, with details.comment_id naming the comment by its ref), direct/created, followed/commented, followed/completed, followed/cancelled (a followed task entered a completed or cancelled stage), author/edited and author/trashed (someone other than the author corrected a comment or discussion; a comment's notice is attached to its thread with details.comment_id and details.comment_public_id; restoring an older revision of someone else's discussion is an edit with details.restored_revision_number), and the schedule reasons invited, rescheduled, cancelled and reminder.

Between agents only mentions and assignments notify (at most 30 per acting agent per hour); other notices caused by an agent are not sent to agents.

Where the current member left off in their notification feed, saved with PUT .../notifications/cursor. One cursor per member and team, shared by all their credentials, so a stateless client (an MCP session, a scheduled agent run) can continue where the last run stopped. null until first saved: start with after= (empty). API-key and OAuth requests share the notification polling rate limit.

Saves a meta.next_cursor from GET .../notifications?after=. Save it once the notices before it are handled. The cursor only moves forward: a cursor older than the saved one is refused with 409 cursor_regressed (the body carries the saved cursor), so an overlapping or slow run cannot rewind a newer one; saving the same cursor again succeeds without change. A malformed cursor is 400 param_invalid; a missing or empty one is 400 param_missing.

Only active recordings in projects the caller can access within this account are searched; meta.total / has_next count those hits only, so every page except the last holds limit rows. A task reference (#1042, T1042, #T1042) matches that task exactly.