Skip to main content
POST
Retry a run's failed notification
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

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 answers 403 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

A 409 invalid_state names the reason in its message: A same-key retry returns the recorded answer only while you still hold runs:manage at the run’s home (see Idempotency).

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string

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.

Required string length: 1 - 255

Path Parameters

obligationId
string
required
Minimum string length: 1

Body

application/json

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.

expectedUpdatedAt
number
required
reason
string
required
replacementTarget
object

Response

The notification will dispatch again

data
object
required

id is the obligation that will dispatch: the same one, or a new one when the retry replaced its recipient. runId is its run.

meta
object
required