Retry a run's failed notification
Retries one of a run’s notifications that needs attention, as a Personal key’s owner. Requires permission runs:manage.
v2 compatibility notes
Retry, or send it to someone else
A run records one notification obligation per recipient of each notification it sends. When a delivery fails, the obligation needs attention.POST /api/v2/runs/retryNotification sends it again, to the same recipient or, with replacementTarget, to another person ({ "kind": "user", "userId" }) or a Slack channel ({ "kind": "slack", "connectionId", "channelId" }). The answer is { "id", "runId" }: id is the obligation that will dispatch, which is a new one when the retry replaced the recipient.
The body is exactly { "id", "expectedUpdatedAt", "reason", "replacementTarget"? }. id is the obligation’s id and expectedUpdatedAt its updatedAt as you last read it. reason (1 to 500 characters) is recorded on the retry. Today the obligation id and updatedAt come from the Forge Console’s run inspector.
It acts as a person
The retry records the person who repaired the delivery, so it needs a Personal key: it acts as the key’s owner, and the audit names the key. A platform key or an External App answers403 with personRequired: true.
You need runs:manage at the run’s home. An obligation whose run you cannot read (runs:read at its home and at every company it carries) answers 404 like a missing one; a readable run whose home you do not manage answers 403. A Slack replacement also needs connections:manage, both in the key’s scopes and at the platform scope in its owner’s role grants; otherwise it answers 403.
When a retry is refused
A409 invalid_state names the reason in its message:
runs:manage at the run’s home (see Idempotency).
Related
Authorizations
A Personal key (fmcp_…), bound to the person who created it, or an interactive MCP sign-in that resolves to one. Pass as Authorization: Bearer <key>. It acts for that person, under their role grants narrowed by its scopes; an operation that acts for a person admits only this kind.
Headers
1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.
1 - 255Body
id is the notification obligation's id and expectedUpdatedAt its updatedAt as you last read it. reason, 1 to 500 characters, is recorded on the repair. replacementTarget sends the retry to another person (or a Slack channel) instead of the original recipient.

