Skip to main content
Network calls fail in ways the caller cannot distinguish from success: a dropped connection after the server committed, a proxy timeout on a slow dispatch, a client crash between send and receive. Retrying is the only sane response, and a retry on an unprotected mutating endpoint duplicates the side effect. Idempotency-Key closes that gap. Send the same key on a retry of the same request and Forge keeps the completed claim instead of executing again. The retry gets back the identical status and body the first request answered, once Forge has checked your permissions again (Stored-response replay).
Idempotency protects requests authenticated with an External Application JWT, a platform API key, or a Personal key. An External Application’s static companion key used as a bearer passes straight through with no idempotency protection — nothing is recorded and nothing is replayed. That path is being retired; move to the OAuth2 client-credentials flow described in Authentication to get idempotency. The Forge MCP server sends one key with every write — the caller’s, or one it generates — and never retries a write on its own. When a dispatch’s outcome is unknown, forge_dispatch_workflow returns the key so the caller can repeat under it. See MCP server error handling.

The header

A key that violates the format is rejected with 400 and error.code idempotency_key_invalid. It is never silently ignored: a client that sends a malformed key and gets a 200 back would believe it is protected when it is not.

Where it applies

Why ingress is excluded

The capability-URL workflow ingress at POST /api/v2/ingress/* is unauthenticated by design: the URL itself is the secret. There is no principal to scope a key to, so the (principal, route, key) triple the rest of the surface relies on cannot be formed. Ingress does not need it. Each trigger carries its own per-trigger deduplication through its dedupeHeader configuration, which collapses repeated deliveries onto the original run. See Signed Workflow Ingress → Idempotency.

Scope of a key

A key is scoped to the triple:
where the principal is the External Application (for a JWT) or the API key itself (for a platform API key or a Personal key), and route is the operation’s /api/v2 HTTP method plus path — POST /api/v2/workflows/dispatch is a different route from POST /api/v2/runs/cancel. A call to an /api/v3 route has the route of the /api/v2 route it reaches: POST /api/v3/runs/{runId}/cancel is POST /api/v2/runs/cancel. So one key sent first to an operation’s /api/v2 path and then to its /api/v3 path names the same claim. Send each retry to the URL, with the body, of the first attempt. Three consequences follow directly, and all three are load-bearing for client design:
  • The same key value used by a different principal never collides. Two apps, or two API keys, can independently pick the string retry-1 without seeing each other’s results.
  • The same key used against a different route never collides. Reusing a key on runs/cancel after using it on workflows/dispatch starts a fresh execution on the second route.
  • A key is therefore safe to generate per request without coordinating across routes. You do not need a global key registry, a per-route namespace prefix, or any cross-service allocation scheme.

Semantics

1

First request with a key

The request executes normally. Forge records the outcome — HTTP status code and response body — against the (app, route, key) triple.
2

Request sent while Forge is stopped

403 operator_stopped before the key is recorded and before the operation runs — with or without a key, and for a key that already completed. Nothing is recorded, so the same key sent after a person resumes Forge executes once (or, for a key that completed before the stop, replays as below).
3

Repeat with the same key and the same request

Forge re-checks the route’s current permissions, then answers the identical status and body the first request returned (Stored-response replay). A denied permission returns 403. A response that was never stored answers only its data.id (Id-only replay) or 409 idempotency_result_unavailable. In every case the side effect does not happen again. Some routes have a replay policy of their own that also re-checks the resource: see Workflow dispatch replay, Webhook revoke and replay, Chat write replay, Memory write replay, Knowledge write replay, Knowledge remedy replay, Knowledge source replay, Knowledge curation replay, Knowledge settings and re-embed replay, External App customer writes, Customer directory writes, Skill write replay, Run cancel replay and Run control replay, and the sections below them.
4

Repeat with the same key but a different request

422 with error.code idempotency_key_reuse. Nothing is executed.
5

Repeat while the first request is still in flight

409 with error.code idempotency_key_in_flight. Nothing is executed twice. Retry after a short delay.
6

Repeat after an earlier attempt crashed

409 with error.code idempotency_outcome_unknown. Nothing is executed. The key is spent — see below.

When an attempt stops without recording an outcome

If a request begins executing and then dies before recording its result — a crashed process, a lost connection mid-flight — the key enters an unresolved state. After a 15-minute grace period, repeats with that key return 409 idempotency_outcome_unknown.
That key is spent for the next 30 days.We cannot tell you whether the original attempt took effect. POST /api/v3/files stores your upload before recording it, and POST /api/v3/knowledge-entries runs a multi-step ingest — an attempt that died partway through those may well have done real work.Re-running behind the key would be a guess, and the wrong guess duplicates the operation. So we refuse. Check the resource’s current state, then retry under a new Idempotency-Key if the work still needs doing.
Unresolved keys are held for 30 days, far longer than the 24-hour window for ordinary recorded responses. A response is a cache and can be forgotten; the record that a side effect may have happened is the only thing stopping a repeat, so it is kept until no client could still be retrying. This is the deliberate trade: a crashed request costs you one key and one reconciliation, rather than silently performing the operation twice.

What counts as “the same request”

Two requests are the same when their HTTP method, path, query string, and body are identical. Headers are not compared: a POST /api/v3/files retry with the same bytes but a different X-Filename or Content-Type is the same request, and returns the original result. Because a key is scoped per route, the same key sent to a different route is a separate record and simply executes — it is not a 422. Reuse is only detected within one route, where the query string or body differs. Query parameter order does not matter — ?a=1&b=2 and ?b=2&a=1 are the same request, not a reuse conflict.

Stored-response replay

A repeat of a completed write answers exactly what the first request answered: the same status and the same body, byte for byte, including a recorded 4xx refusal. The body keeps the first request’s meta.requestId; the repeat’s own request id is in the X-Request-Id header. Forge answers this way when all of these hold:
  • the same credential sends the repeat: the same API key, or the same External App;
  • the request is the same: method, path, query string and body (otherwise 422 idempotency_key_reuse);
  • the credential still holds every permission the operation requires, including one the request body made apply (otherwise that 403);
  • the operation requires a permission of its own, so Forge can check it again;
  • the first response was stored: JSON, at most 32 KiB, and not one that carries a one-time secret.
An operation that decides access at the record’s own home, or by who you are, requires no permission Forge can check before it runs. Its repeat answers only the data.id its success named (Id-only replay), else 409 idempotency_result_unavailable. Its reference page says so.
Idempotent-Replayed: true marks every replayed answer, full or id-only; Idempotency-Replayed: true is the same signal under the name Forge sent first. A route with a replay policy of its own (the sections below) also re-checks the resource the response names, and answers 409 idempotency_result_unavailable when that check fails.

Responses that cannot be replayed

If the original response was never stored, and it is not a created resource whose id can be returned (Id-only replay), a repeat returns 409 with error.code idempotency_result_unavailable. This includes a response larger than the 32 KiB storage ceiling, a request that failed before producing a response, a route whose own replay policy withholds the response, or a response Forge never stores because it carries a one-time secret: POST /api/v3/webhooks and POST /api/v3/webhooks/{webhookId}/rotate-secret return a webhook signing secret once, and a repeat never returns it again. POST /api/v3/sandbox-snapshots/{snapshotId}/replay-command never stores its output either, because a command’s output may hold secrets: a repeat never runs the command again.
idempotency_result_unavailable means: the original request completed, it was not re-executed, and the original response cannot be shown to you. When a route’s own replay policy withholds disclosure, the response message is: “This request completed, but its response cannot be disclosed under the current authorization policy. The original request was not repeated.” Query the affected resource directly to reconcile the outcome. Do not automatically use a new key: that could repeat an effect you have not yet observed.

Id-only replay

On an operation without a replay policy of its own, a repeat of a completed create whose response was never stored (over the 32 KiB ceiling, or carrying a one-time secret), or whose access is decided at the record’s home or by who you are, still gets back the id it created. Forge answers with the original status and only that id when all of these hold:
  • the same credential sends the repeat: the same API key, or the same External App;
  • the request is the same: method, path, query string and body (otherwise 422 idempotency_key_reuse);
  • the original request succeeded (2xx), and its response named the resource in data.id;
  • the credential still holds every permission the operation requires.
The OpenAPI spec names this body IdOnlyReplay and offers it beside the full success schema on each operation that can answer it; meta.idempotentReplay: "id_only" tells the two apart. The body holds the id and nothing else. A one-time secret, or any other field the route doesn’t disclose on replay, is not returned. Read the resource by its id to get its current state. The id is kept even when the full response is not: a response over the 32 KiB ceiling, or one that carried a one-time secret. A repeat from a different credential is its own request in its own key scope, so it never sees the first credential’s id. meta.idempotentReplay and the Idempotency-Replay-Disclosure header mark the answer as id-only; a full replay carries neither. A repeat still answers 409 idempotency_result_unavailable in these cases:
  • the original response was not stored and was a failure, or named no data.id;
  • the operation’s route could not be checked again;
  • the operation has its own replay policy, like those in the sections below. That policy then decides the whole answer: when it withholds the response, for example because you can no longer read the resource, nothing is returned, not even the id.

Every outcome is recorded, including 5xx

A key is spent by the first request that uses it, whatever the outcome. There is no status code that frees a key for reuse.
A 5xx does not free the key. Retrying with the same key after a 5xx does not attempt the operation again. It answers the stored 5xx, or 409 idempotency_result_unavailable when the request failed before producing a response.This is deliberate. Some endpoints do work in more than one step — POST /api/v3/files stores your upload before recording it, and POST /api/v3/knowledge-entries runs a multi-step ingest — so a 5xx does not reliably mean nothing happened. Re-running under the same key could duplicate a partially applied operation, which is the outcome idempotency exists to prevent.Before making another attempt after a 5xx, reconcile the authorized resource state or escalate. Only after determining that another effect is appropriate should you start a new logical operation under a new Idempotency-Key.
A 4xx is a deterministic outcome of that exact request. It remains recorded, and re-executing would not change it.

Routes that return a one-time secret

POST /api/v3/external-apps, POST /api/v3/external-apps/{externalAppId}/rotate-secret and POST /api/v3/external-apps/{externalAppId}/rotate-callback-secret return a client or callback secret exactly once, as POST /api/v3/webhooks and POST /api/v3/webhooks/{webhookId}/rotate-secret return a signing secret and POST /api/v3/workflows/{workflowId}/ingress-triggers and POST /api/v3/workflow-triggers/{triggerId}/rotate-ingress-token return an ingress token and its URL. Forge records only that the key was used and the status it answered: the response body, secret included, is never stored, whatever its status. A repeat with the same key does not run again, so it never creates a second app, subscription or ingress trigger or rotates a second time. It answers with the original status and only the data.id the response named (Id-only replay), or 409 idempotency_result_unavailable when it named none. A secret lost in transit cannot be recovered from the key. Use the returned id, or list the apps, webhooks or triggers, to find the one you created, then rotate its secret or token.

Retention

A recorded response claim is retained for 24 hours. During that window, current authorization and disclosure policy govern whether its cached response can be returned. After that window the same key starts a fresh execution. A key left unresolved by a crashed attempt is held for 30 days instead. It keeps returning 409 idempotency_outcome_unknown for that whole period rather than becoming reusable at 24 hours, because forgetting it would re-enable exactly the execution it exists to refuse. Records are removed by a scheduled retention job.

Workflow dispatch replay

A completed POST /api/v3/workflows/dispatch response can be disclosed on a repeat. Forge decides it from the original run the first request created, never from the workflow name in the retried request, so a workflow renamed or replaced since the first attempt cannot redirect the decision. A repeat receives the stored response only when all of these hold now:
  • The caller still holds workflows:use, the permission a fresh dispatch needs.
  • The caller also holds runs:read. A caller that can dispatch but not read runs can start fresh work, but cannot receive a cached dispatch result. Neither permission is granted automatically.
  • The caller’s own home org unit still covers the original workflow’s current home, as for a fresh dispatch. Only an organization-owned External App has a home; a platform API key or a Personal key does not, so its repeat is not disclosed.
  • The caller holds runs:read at every company the original run recorded.
A missing workflows:use or runs:read returns 403 with the missing permission. Any other refusal returns 409 idempotency_result_unavailable and names no run or workflow. In every case the workflow is not dispatched again.

Upload replay

A completed POST /api/v3/files response can be disclosed on a repeat. A repeat with the same key and the same bytes receives the stored 201 response when both hold now:
  • The caller still holds files:write, the permission a fresh upload needs. It does not need files:read: the stored body is the caller’s own upload result.
  • The uploaded file is still bound to the org tree the caller currently acts in (the binding the upload created).
A missing files:write returns 403. Any other refusal returns 409 idempotency_result_unavailable and names no file. In every case the file is not stored again. Headers are not part of the request, so the stored result keeps the original X-Filename and Content-Type. A body over the upload limit answers 413 before the key is used. See Retrying an upload.

Webhook revoke and replay

Two webhook routes disclose their stored response to the External App that caused it, while it still holds webhooks:manage:
  • DELETE /api/v3/webhooks/{webhookId} returns its stored 200 {"revoked": true} acknowledgement.
  • POST /api/v3/webhook-deliveries/{deliveryId}/replay returns its stored 202 {deliveryId, replayedFrom} acknowledgement only while both deliveries still belong to a subscription the calling app owns.
Forge recognizes each stored body by its exact shape; any other body, or any other caller, gets 409 idempotency_result_unavailable. Neither route runs again.

External App update and deactivate replay

PATCH /api/v3/external-apps/{externalAppId} and DELETE /api/v3/external-apps/{externalAppId} disclose their stored 200 response only while the caller still holds apps:manage at the app’s management home. Forge reads the app ID from the exact body the route wrote; any other body, or a caller that may no longer manage the app, gets 409 idempotency_result_unavailable. Neither route runs again. POST /api/v3/webhooks and POST /api/v3/webhooks/{webhookId}/rotate-secret are different: their responses carry a one-time signing secret and are never stored. A repeated create answers 201 with only the webhook’s data.id (Id-only replay); a repeated rotation answers 409 idempotency_result_unavailable. Neither returns the secret again. If a create’s outcome is unknown, repeat it with the same key to learn the webhook’s id, then rotate its secret.

Chat write replay

POST /api/v3/chat-channels/{channelId}/sessions and POST /api/v3/chat-sessions/{sessionId}/messages disclose their stored 201 response on a repeat. Forge decides it from the session the stored response names (data.id for a created session, data.sessionId for a sent message), never from the retried request. A repeat receives the stored response only when all of these hold now:
  • The caller still holds the route’s permission: chat:manage for createSession, chat:use for sendMessage.
  • The caller also holds chat:read. A caller that can write chat but not read it can start fresh work, but cannot receive a cached chat result.
  • The caller may read that session exactly as Get a chat session decides it: its channel is a factory, project or team channel, the caller holds chat:read at the channel’s home org unit, and a session with restricted participants was started by this caller.
A missing permission returns 403 with the missing permission. Any other refusal, including a channel moved to another org unit, a channel that became a direct, personal or group conversation, or a response stored before sendMessage returned sessionId, returns 409 idempotency_result_unavailable and names no session or message. In every case the session is not created again and the message is not sent again.

Memory write replay

POST /api/v3/memory, PATCH /api/v3/memory/{memoryId} and DELETE /api/v3/memory/{memoryId} disclose their stored 201 (create) or 200 response on a repeat. Forge decides it from the memory the stored response names (data.id, and for a create data.layer), never from the retried request. A repeat receives the stored response only when all of these hold now:
  • The caller still holds memory:write, the routes’ permission.
  • The caller also holds memory:read.
  • The caller may read that memory exactly as Get a memory entry decides it: its agent is in the caller’s owner-scope chain, is not a Personal Agent, and the caller may read every company the memory is stamped with.
  • The caller may still write that agent’s memory: a platform agent’s memory is read-only, so a repeat after an agent became a platform agent is refused.
A missing permission returns 403 with the missing permission. Any other refusal, including a memory that no longer exists, an agent that left the caller’s chain, or a create response stored before it named its layer, returns 409 idempotency_result_unavailable and names no memory. In every case the memory is not written, patched or forgotten again.

Knowledge write replay

POST /api/v3/knowledge-entries and DELETE /api/v3/knowledge-entries/{entryId} disclose their stored success response on a repeat: an add’s 201 (created) or 200 (deduplicated: true), and a delete’s 200 with alreadyDeleted. Forge decides it from the entry the stored response names (data.id), never from the retried request, under the namespaces a fresh request from the same credential would resolve now. A repeat receives the stored response only when all of these hold now:
  • The caller still holds the route’s permission: knowledge:write for addKnowledge, knowledge:manage for delete.
  • The caller also holds knowledge:read: the stored response names an entry ID.
  • For an add, the entry is still active and in the caller’s readable namespaces, exactly as Get a knowledge entry would find it. For a delete, the entry is still in the caller’s writable namespaces.
A missing permission returns 403 with the missing permission. Any other refusal, including an added entry that was deleted since, or a delete response stored before deletes reported alreadyDeleted, returns 409 idempotency_result_unavailable and names no entry. A repeat of a request that was refused (400, 403, 404, 409 or 413) also returns that 409, not the refusal again. In every case nothing is ingested or deleted again.

Knowledge remedy replay

POST /api/v3/knowledge-entries/{entryId}/retry, POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/request-sync and POST /api/v3/knowledge-synchronized-sources/{synchronizedSourceId}/relist disclose their stored 200 response on a repeat: {entryId, scheduled}, or {sourceId, outcome} with a sync outcome (scheduled, running, inactive) or a re-list outcome (scheduled, queued, inactive). Forge decides it from the entry or source the stored response names, never from the retried request, under the namespaces a fresh request from the same credential would resolve now. A repeat receives the stored response only when all of these hold now:
  • The caller still holds knowledge:manage, the routes’ permission.
  • The caller also holds knowledge:read: the stored response names an entry or source ID.
  • The entry is still in the caller’s writable namespaces and not restricted to named people, or the source is still in them and not being removed.
A missing permission returns 403 with the missing permission. Any other refusal returns 409 idempotency_result_unavailable and names nothing. A repeat of a request that was refused (400, 403 or 404) also returns that 409. In every case nothing is scheduled or re-listed again. A re-list under a new key re-lists again: each logical re-list is its own key.

Knowledge source replay

PATCH /api/v3/knowledge-synchronized-sources/{synchronizedSourceId} and POST /api/v3/knowledge-synchronized-sources disclose their stored source projection on a repeat (update’s 200, create’s 201) while the named source remains in the caller’s writable namespaces. DELETE /api/v3/knowledge-synchronized-sources/{synchronizedSourceId} discloses its stored 200 {sourceId, namespace, purgeScheduled} while the namespace it names remains writable: the purge may already have deleted the source, so the namespace Forge wrote into the response is what it rechecks. Forge extracts the source id or namespace from the stored response rather than trusting the retried body, requires exactly the body each route writes, and round-trips the stored JSON unchanged. A repeat receives it only while the caller still holds the route’s permissions (knowledge:manage, and credentials:use for a create) and knowledge:read. A missing permission returns 403 with the missing permission. A missing source, lost namespace access, a malformed stored body or any other stored response, including a refusal (400, 403 or 404), returns 409 idempotency_result_unavailable and names no source. A source is never connected, updated or removed twice, and nothing is audited twice. Completed responses, including the stored update response, are retained for 24 hours (IDEMPOTENCY_RETENTION_MS). After that window the completed key can be used again; unresolved attempts keep the longer 30-day safety retention described above.

Knowledge curation replay

POST /api/v3/knowledge-cases, PATCH /api/v3/knowledge-cases/{caseId} and POST /api/v3/knowledge-cases/{caseId}/ verify, set-grade and set-steward disclose their stored success response on a repeat: create’s 201, and each other route’s 200. Forge decides it from the case the stored response names, never from the retried request: the live case an edit held for review belongs to (revisionOf), the live case a graded revision was promoted into (promotedInto), else entryId. A repeat receives the stored response only when all of these hold now:
  • The caller still holds knowledge:manage, the routes’ permission.
  • The caller also holds knowledge:read: the stored response names a case ID.
  • The case is still active and in the caller’s readable namespaces, and not restricted by its source, under the namespaces a fresh request from the same credential would resolve now.
POST /api/v3/knowledge-reviews/{reviewId}/decide, POST /api/v3/knowledge-golden-sets, PATCH /api/v3/knowledge-golden-sets/{goldenSetId} and POST /api/v3/knowledge-golden-sets/{goldenSetId}/run follow the same rule for the review item or golden set the stored response names (itemId, or the set’s id or goldenSetId): decideReview’s 200, create’s 201, and update’s and run’s 200. A repeat receives the stored response only when all of these hold now:
  • The caller still holds knowledge:manage, the routes’ permission.
  • The caller also holds knowledge:read: the stored response names an item or set ID.
  • For a decision, the caller can still see the review item, whatever its status: it is in the caller’s readable namespaces and not source-restricted. For a golden set, the caller still reads every namespace the set searches now and, for a create or update, every namespace the recorded response names (a set may be re-scoped before its first run).
Forge recognizes only exactly the success body each route writes, and round-trips the stored JSON unchanged. A missing permission returns 403 with the missing permission. Any other refusal, including a case, item or set deleted or moved out of reach since, returns 409 idempotency_result_unavailable and names nothing. A repeat of a request that was refused (400, 403, 404 or 409) also returns that 409, not the refusal again. Retiring a pending revision deletes it, so a repeat of that grade change always returns the 409; read the live case to reconcile. In every case nothing is written, graded, decided, scheduled or audited again.

Knowledge settings and re-embed replay

PATCH /api/v3/knowledge-settings/{settingKey} and POST /api/v3/knowledge-reembed-runs are deployment-wide: the learning settings and the re-embed have no org-unit home, so they have no replay policy of their own (Stored-response replay) and the route’s permission is the whole rule. A repeat returns the stored response, including a stored refusal such as a 400 for a value its rule refuses, while the caller still holds platform:manage (settings) or knowledge:manage (re-embed). A caller that lost it gets 403 with the missing permission. The setting is never written or audited again, and no second re-embed is scheduled.

External App customer writes

POST /api/v3/me/customers, POST /api/v3/me/customers/find-or-create and PATCH /api/v3/me/customers/{customerId} disclose their stored 200 or 201 {customer} (or {customer, created, linked}) response to an External App, while it still holds customers:manage and is still linked to the customer the response names. A missing customers:manage returns 403. A caller that is not an External App, an app no longer linked to that customer, or any other stored body gets 409 idempotency_result_unavailable, and the write does not run again. A response stored before this policy carried the customer’s createdBy; Forge refuses to disclose it for the rest of its retention window. Only a management JWT is idempotency-scoped: with the deprecated companion key a repeated write runs again (create and find-or-create deduplicate on workosId; an update re-applies the same values). DELETE /api/v3/me/customers/{customerId} discloses its stored 200 {id, unlinked: true} to an External App while it still holds customers:manage. The link it removed is gone by design, so this reply does not depend on the link; it carries only what the same app caused, and a key is already scoped to the caller that used it. A missing customers:manage returns 403. A caller that is not an External App, or any other stored body, gets 409 idempotency_result_unavailable, and the unlink does not run again. With the companion key a repeated unlink runs again and answers 404 once the link is gone.

Customer directory writes

POST /api/v3/customers discloses its stored 201 {customer, created}, and PATCH /api/v3/customers/{customerId} and DELETE /api/v3/customers/{customerId} their stored 200 {customer}, on a repeat only while the credential’s scopes still reach customers:read and its grants still hold customers:read and customers:manage at the deployment root, the authority the original write required. A missing customers:manage returns 403. A stored refusal or failure, a credential whose scopes no longer reach customers:read, or a caller whose grants no longer hold both permissions at the deployment root gets 409 idempotency_result_unavailable, and the write does not run again. A create whose record failed after Forge provisioned its WorkOS entity is a stored failure: the entity was deleted, and a repeat answers 409 without provisioning again. Personal keys, platform API keys and management JWTs are idempotency-scoped; with the deprecated companion key, or without a key, a repeated write runs again (a create without workosId provisions another WorkOS identity; an update re-applies the same values; an archive keeps the customer archived and advances its updatedAt).

Skill write replay

POST /api/v3/skills and PATCH /api/v3/skills/{skillId} disclose their stored response (a 201 or 200 Skill, or the recorded 4xx) on a repeat while the caller still holds skills:write (and skills:manage, when the repeated update carries a status). The skill catalog is platform-global — it has no org-unit home — so the route’s permission is the whole rule: there is no row to recheck. A caller that lost skills:write gets 403 with the missing permission. In every case the skill is not created or patched again. These routes have no replay policy of their own (Stored-response replay); a route whose resource has a home rechecks it before disclosing.

Agent write replay

POST /api/v3/agents, PATCH /api/v3/agents/{agentId} and DELETE /api/v3/agents/{agentId} disclose their stored success response (201 {id, agentId}, 200 {ok, agentId} or 200 {ok, agentId, status: "archived"}) on a repeat only to an External App that still holds agents:write (and switches:use, when the repeated update carries a status), still owns the agent the response names, and may still read it at the agent’s home. A create’s response is bound to the definition id it returned: if that agent was deleted and its agentId reused, the repeat is refused. A caller that lost agents:write gets 403 with the missing permission. A caller that is not an External App, an App that lost the agent or agents:read at its home, a stored refusal, or a response stored before this policy gets 409 idempotency_result_unavailable. In every case the agent is not created, patched or archived again. Only a management JWT is idempotency-scoped: with the deprecated companion key a repeated write runs again (a repeated create is then a 409 conflict on the existing agentId). POST /api/v3/agents/{agentId}/reinstate-version discloses its stored 200 {id, agentId, version, headChanged} on a repeat only to an External App that still holds agents:manage, still owns the agent definition id names (a slug since reused by another agent is refused), and may still read it at its home. A caller that lost agents:manage gets 403 with the missing permission; any other refusal, stored refusal or other stored body gets 409 idempotency_result_unavailable. The rollback does not run again. POST /api/v3/agents/{agentId}/delete-permanently never discloses its stored result: the agent it deleted no longer exists, so nothing can re-decide that the caller may see it. A repeat from a caller that still holds agents:manage gets 409 idempotency_result_unavailable; one that lost it gets 403 with the missing permission. The delete does not run again. To learn an attempt’s outcome, read the agent: 404 resource_missing means it is gone.

Run cancel replay

POST /api/v3/runs/{runId}/cancel discloses its stored 200 {id, disposition, status} response on a repeat. Forge decides it from the run the stored response names, never from the retried request, and only when all of these hold now:
  • The caller still holds runs:manage, the route’s permission.
  • The caller may read that run: runs:read at the run’s home (its own org unit, else its workflow’s owning org unit) and at every company it carries.
  • The caller holds runs:manage at that home.
A missing runs:manage returns 403. Any other refusal, or any other stored body, returns 409 idempotency_result_unavailable and names no run. In every case the cancellation is not requested again; the stored status is the run’s status when the first request answered, so read the run for its current status.

Run control replay

POST /api/v3/runs/{runId}/restart, POST /api/v3/run-notification-obligations/{obligationId}/retry, POST /api/v3/runs/{runId}/start-analysis and POST /api/v3/runs/{runId}/set-kill-switch disclose their stored 200 response on a repeat. Forge decides it from the run the stored response names, never from the retried request, and only when the caller still passes the route’s own rule for that run now:
  • The caller still holds the route’s permission: runs:manage (restart, retry), platform:manage (analysis) or switches:use (kill switch).
  • The caller may read that run: runs:read at the run’s home (its own org unit, else its workflow’s owning org unit) and at every company it carries.
  • For a restart or a retry, the caller holds runs:manage at that home; for the kill switch, switches:use at that home; for an analysis, platform:manage at the platform scope.
A missing route permission returns 403. Any other refusal, or any other stored body (a stored 404, 403, 409 or 500 included), returns 409 idempotency_result_unavailable and names no run. In every case the write does not run again: the run is not restarted twice, the notification is not retried twice, and a repeated kill-switch change writes no second audit event.

Eval set write replay

POST /api/v3/evals, PATCH /api/v3/evals/{evalId} and DELETE /api/v3/evals/{evalId} disclose their stored 201 (create) or 200 response (the EvalSetDetail, or the archive’s {id, status, disposition}) on a repeat. Forge decides it from the eval set the stored response names, never from the retried request, and only when all of these hold now:
  • The caller still holds agents:write, the route’s permission.
  • The caller may read that set: agents:read at its agent’s home org unit (the agent exists and is not PERSONAL), or at the deployment root for a set with no agent.
  • The caller holds agents:write at that same home.
A missing agents:write returns 403. Any other refusal, or any other stored body, returns 409 idempotency_result_unavailable and names no set. In every case nothing is created, edited or archived again; an archived set still qualifies, since its archive is what the caller did. A create or update answer above the 32 KiB storage ceiling is never stored and always answers that 409.

Eval run replay

POST /api/v3/evals/{evalId}/runs and POST /api/v3/eval-runs/{runId}/cancel disclose their stored response (the 201 or 200 EvalRun) on a repeat. Forge decides it from the run the stored response names, never from the retried request, and only when all of these hold now:
  • The caller still holds both agents:write and inference:use, the routes’ permissions.
  • The caller may see that run: its set is readable (agents:read at its agent’s home org unit, the agent exists and is not PERSONAL, or at the deployment root for a set with no agent), and the run’s own agent, when it names one, is readable.
  • The caller holds agents:write at the set’s home.
A missing permission returns 403. Any other refusal, or any other stored body, returns 409 idempotency_result_unavailable and names no run. In every case no run is started or cancelled again; the stored run is its state when the first request answered, so list the set’s runs for its current status.

Project staffing replay

The six project staffing writes (POST /api/v3/projects/{projectId}/staffing-assignments, PATCH /api/v3/projects/{projectId}/staffing-assignments/{assignmentId}, POST /api/v3/projects/{projectId}/staffing-assignments/{assignmentId}/release, POST /api/v3/projects/{projectId}/pod-assignments, POST /api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/reconcile and POST /api/v3/projects/{projectId}/pod-assignments/{podAssignmentId}/release) disclose their stored success response on a repeat. Forge decides it from the project, and for a pod write the pod, that the stored response names, never from the retried request, and only when all of these hold now:
  • The caller still holds workforce:manage, the routes’ permission, at the platform scope.
  • The credential’s scopes still include workforce:read and projects:read, because the stored answer is a staffing read.
  • The caller may read the project: projects:read at its home org unit.
  • For a pod write, the pod still exists and its managing org unit is not a customer organization or under one.
A missing workforce:manage returns 403. Any other refusal, a stored refusal or error, or any other stored body returns 409 idempotency_result_unavailable and names nothing. In every case the staffing change is not made again; the stored rows are their state when the first request answered, so read Get project staffing or Get project pod staffing for the current state. The previews are reads carried in a POST body: they take no Idempotency-Key.

Resourcing settings replay

The three resourcing settings changes (PATCH /api/v3/engineering-scope, POST /api/v3/reporting-categories and PATCH /api/v3/reporting-categories/{reportingCategoryId}) disclose their stored success response on a repeat only when all of these hold now:
  • The caller still holds workforce:manage, the routes’ permission, at the platform scope.
  • The credential’s scopes still include workforce:read, because the stored answer is a workforce read.
These rows have no home org unit, so the platform-scope permission is the whole row rule. A missing workforce:manage returns 403. Any other refusal, a stored refusal or error, or any other stored body returns 409 idempotency_result_unavailable and names nothing. In every case the change is not made again; the stored row is its state when the first request answered, so read Get engineering scope or List reporting categories for the current state.

People replay

The ten person changes (POST /api/v3/persons, PATCH /api/v3/persons/{personId}, POST /api/v3/persons/merge, POST /api/v3/persons/{personId}/offboard, POST /api/v3/persons/{personId}/reactivate, POST /api/v3/persons/{personId}/identities, POST /api/v3/persons/{personId}/identities/{identityId}/unlink, POST /api/v3/persons/{personId}/email-claims, POST /api/v3/persons/{personId}/email-claims/{claimId}/revoke and PATCH /api/v3/persons/{personId}/communication-profile) disclose their stored success response on a repeat only when all of these hold now:
  • The caller still holds workforce:manage, the routes’ permission, at the platform scope.
  • The credential’s scopes still include workforce:read, because the stored answer is a read of the person or their records.
  • Every person the stored answer names (both people of a merge) is still in reach: none of their seats sits in a customer organization or an org unit under one.
PATCH /api/v3/workers/{workerId}/seat follows the org-unit and position command rule (org:manage and workforce:read at the platform scope) and discloses its stored seat only while the seat’s person is still in reach. A missing route permission returns 403. Any other refusal, a stored refusal or error, or any other stored body returns 409 idempotency_result_unavailable and names nothing. In every case the change is not made again; the stored answer is the state when the first request answered, so read Get person, List person identities, List person email claims or Get person communication profile for the current state.

Workflow library replay

The six workflow library changes (POST /api/v3/fiscal-calendars, PATCH /api/v3/fiscal-calendars/{calendarName}, DELETE /api/v3/fiscal-calendars/{calendarName}, POST /api/v3/workflow-steps, PATCH /api/v3/workflow-steps/{stepId} and DELETE /api/v3/workflow-steps/{stepId}) disclose their stored success response on a repeat only while the credential’s scopes still include workflows:read and the caller still holds workflows:read and workflows:manage at the platform scope. The library has no per-row home, so that is the whole rule. A missing workflows:manage returns 403. Any other refusal, a stored refusal or error, or any other stored body returns 409 idempotency_result_unavailable and names nothing. In every case the change is not made again; read getFiscalCalendar or listSteps for the current state.

Workflow lifecycle replay

POST /api/v3/workflows/{workflowId}/publish-draft, POST /api/v3/workflow-versions/{versionId}/activate and POST /api/v3/workflows/{workflowId}/reset-draft use the workflow_lifecycle_write policy. A repeat discloses the stored success response only while the workflow it names still exists (a trashed workflow still counts), the credential’s scopes still include workflows:read, and the caller still holds workflows:read at the workflow’s home and workflows:manage at the platform scope. A missing workflows:manage returns 403. Any other refusal, a stored refusal or error, or any other stored body returns 409 idempotency_result_unavailable and names nothing. In every case the change is not made again; the stored answer is the state when the first request answered, so read listVersions or getDraft for the current state. The workflow catalog writes (POST /api/v3/workflows/{workflowId}/ retire, unretire, trash, restore, replace-asset, set-tags and set-owning-org-unit, and POST /api/v3/workflows/create-from-template) use the same policy, with workflows:manage decided at the workflow’s home rather than the platform scope. POST /api/v3/workflows/{workflowId}/purge has no policy of its own: a same-key repeat returns the recorded result once you still hold workflows:manage (Stored-response replay), and the purge never runs twice. POST /api/v3/workflows/{workflowId}/test-run-draft starts a run, so it replays under the workflow dispatch rule: a repeat returns the original run’s identity only while the caller may read that run (runs:read), and no second run starts.

Workflow trigger replay

POST /api/v3/workflows/{workflowId}/triggers, PATCH updateTrigger, POST pauseTrigger, POST resumeTrigger, POST deleteTrigger, POST setIngressStatus and PATCH updateIngressConfig use the workflow_trigger_write policy. A repeat discloses the stored success response only while the trigger it names still exists (a deleted one only for its delete), the credential’s scopes still include workflows:read, the caller may still read the trigger (workflows:read at its workflow’s home and at its orgUnitId) and holds workflows:manage at the trigger’s org unit and the platform scope. A missing workflows:manage returns 403. Any other refusal, a stored refusal or error, or any other stored body returns 409 idempotency_result_unavailable and names nothing. In every case the change is not made again; read getTrigger for the current state. createIngressTrigger and rotateIngressToken are never replayed.

Synthesis approvals

The four synthesis queue decisions (POST /api/v3/synthesis/promote-requests, POST /api/v3/synthesis/demote-requests, POST /api/v3/synthesis/accept-requests and POST /api/v3/synthesis/assign-reviewer) and the two curator decisions (POST /api/v3/synthesis-curator-recommendations/{curatorRecommendationId}/decide and POST /api/v3/synthesis/close-keep-both-curator-recommendations) use the synthesis_approval policy. The same key and the same body within 24 hours return the recorded 200 ({requested, affected, skipped}, or the decided recommendation) only while the caller still holds synthesis:approve at the platform scope. The queue has no per-request home, so that is the whole rule. The stored answer is the outcome of the caller’s own command over the ids it sent, not a read of the requests, so no read scope is rechecked. A missing synthesis:approve returns 403. A caller that holds it only below the platform scope, a stored refusal or error (a cached 4xx or 5xx is never replayed), or any other stored body gets 409 idempotency_result_unavailable, which names nothing. The same key with a different body is 422. In every case the decision is not made again; the stored outcome is what the first request did, so read Get synthesis request for each request’s current state. Without a key, a repeated promote, demote or accept is a no-op by state: each id already moved is skipped as wrong_status. A repeated assign reviewer is not: it applies the same assignment again, re-stamps the assignment time and writes another audit event. The Forge MCP server sends a fresh key with each call when you pass no idempotencyKey, so to make an MCP retry safe, pass the same idempotencyKey again. A repeated curator decision is 409: the recommendation is already resolved. A repeated keep-both sweep is a no-op by state: each id already closed is skipped as wrong_status.

Policy writes

The seven policy writes (POST /api/v3/governance-trust-policies, PATCH, DELETE and POST …/toggle on /api/v3/governance-trust-policies/{trustPolicyId}, POST /api/v3/governance-approval-policies, and PATCH and DELETE on /api/v3/governance-approval-policies/{approvalPolicyId}) use the policy_write policy. The same key and the same body within 24 hours return the recorded answer (201 for a create, 200 otherwise, each { policyId }) only while the caller still holds policies:manage at the platform scope. Policies have no org-unit home, so that is the whole rule. A stored refusal or error is never replayed: it answers 409 idempotency_result_unavailable, and the write never runs twice.

Synthesis settings writes

The five synthesis settings writes (POST /api/v3/synthesis-templates, PATCH /api/v3/synthesis-templates/{templateId}, DELETE /api/v3/synthesis-templates/{templateId}, POST /api/v3/synthesis/set-budget and POST /api/v3/synthesis/set-jit-default) use the synthesis_settings_write policy. The same key and the same body within 24 hours return the recorded answer (201 for a create, 200 otherwise) only while the credential’s scopes still reach platform:read (the answer is a read) and the caller still holds platform:read and synthesis:manage at the platform scope. The settings belong to the workspace, not to an org unit, so that is the whole rule. A missing synthesis:manage returns 403. Any other refusal, a stored refusal or error (a cached 4xx or 5xx, including a 404, is never replayed), or any other stored body gets 409 idempotency_result_unavailable, which names nothing. The same key with a different body is 422. In every case the write is not made again; read the templates, the budget or the JIT default back for the current state. Without a key, a repeated create makes a second template, as in the Console; a repeated update, budget or JIT default write converges on the same state; a repeated delete is 404.

Judge writes

The eight judge writes (POST /api/v3/judge-verdicts/{verdictId}/override, POST /api/v3/judges/{judgeId}/promote, POST /api/v3/judges/{judgeId}/demote, POST /api/v3/judge-admissions/{admissionId}/resolve, POST /api/v3/judges/rejudge-skill, POST /api/v3/judges/rejudge-agent, POST /api/v3/judges/rejudge-procedure and POST /api/v3/judges/rejudge-workflow) use the judge_write policy. The same key and the same body within 24 hours return the recorded 200 only while the caller still holds the route’s permission at the platform scope: judges:use for an override, judges:manage for promote and demote, synthesis:approve for an admission and a skill or agent re-judge, procedures:approve for a procedure re-judge, and workflows:manage for a workflow re-judge. Judges, verdicts and admissions belong to no org unit, so that is the whole rule. The stored answer is the outcome of the caller’s own command, not a read, so no read scope is rechecked. The skill-set and workspace tool-set writes (POST /api/v3/skill-sets, PATCH /api/v3/skill-sets/{setId}, DELETE /api/v3/skill-sets/{setId}, POST /api/v3/skill-sets/{setId}/members, DELETE /api/v3/skill-sets/{setId}/members/{skillId}, POST /api/v3/tool-sets and PATCH /api/v3/tool-sets/{setId}) use the catalog_admin_write policy. The same key and the same body within 24 hours return the recorded success (201 for a create, otherwise 200) only while the caller still holds the route’s key (skills:manage or tools:manage) at the platform scope. DELETE /api/v3/tool-sets/{setId} is never replayed, because it removes the set and every grant of it: a same-key retry is 409 idempotency_result_unavailable. The seven capability and provider configuration writes (POST /api/v3/capabilities/{domain}/set-chain, POST /api/v3/capabilities/{domain}/disable, POST /api/v3/providers/{providerKey}/set-options, POST /api/v3/providers/{providerKey}/enable, POST /api/v3/providers/{providerKey}/disable, POST /api/v3/provider-records and POST /api/v3/capabilities/{domain}/bind-organization) use the capability_config_write policy. The same key and the same body within 24 hours return the recorded success (201 for createRecord, otherwise 200) only while the caller still holds platform:manage at the platform scope, or, for bindOrganization, at the org unit the recorded result names. A replayed chain write never runs again, so switching the embeddings provider never re-embeds twice. A missing permission returns 403. A caller that holds it only below the platform scope, or a stored refusal or error (a cached 4xx or 5xx is never replayed, including a 404 or a 409 conflict), gets 409 idempotency_result_unavailable, which names nothing. The same key with a different body is 422. In every case the write is not made again, so a re-judge never schedules a second judge; read the verdict, judge or admission back for its current state. Without a key, a repeated override records the override again, a repeated promote or demote answers changed: false, a repeated admission resolution is 409 (already resolved), and a repeated re-judge schedules the judge again.

Human task writes

The four human-task writes (POST /api/v3/governance-human-tasks/{humanTaskId}/act, POST /api/v3/governance-human-tasks/{humanTaskId}/complete, POST /api/v3/governance-human-tasks/reassign and POST /api/v3/governance-human-task-output-files) use the human_task_action policy. The same key and the same body within 24 hours return the recorded 200 only while all of these hold:
  • The caller is a Personal key, the only credential that can make these writes.
  • The key’s scopes still reach approvals:approve and approvals:read, because the stored answer describes the task.
  • The key’s owner can still see the task the stored answer names, by the rule Get a human task applies, judged on the key’s scopes.
Reassign also rechecks its declared approvals:approve first; a missing one returns 403. Any other refusal, a stored refusal or error (a cached 4xx or 5xx is never replayed), or any other stored body returns 409 idempotency_result_unavailable, which names nothing. The same key with a different body is 422. In every case the write is not made again; read the task with Get a human task for its current state. Without a key, a repeat follows each write’s own rules: claiming your own claim or releasing an unclaimed task changes nothing, a second decline, withdraw or completion is refused because the task has closed, and a repeated reassign or attach is a second write (another audit event, or another file version). The Forge MCP server sends a fresh key with each call when you pass no idempotencyKey, so to make an MCP retry safe, pass the same idempotencyKey again.

Workflow Architect writes

Asking the Architect to fix a failed run (POST /api/v3/runs/{runId}/ask-architect-to-fix), saving a chat task as a workflow (POST /api/v3/workflows/create-from-chat-task) and setting the Architect’s JIT mode (POST /api/v3/workflows/{workflowId}/set-architect-jit-mode) use the workflow_architect policy. The same key and the same body within 24 hours return the recorded answer (201 for the first two, 200 for the mode) only while the caller still holds workflows:write and may still write the draft of the workflow the stored answer names: workflows:write and workflows:read at that workflow’s home, decided now. A missing workflows:write returns 403. Any other refusal, a stored refusal or error, or any other stored body returns 409 idempotency_result_unavailable, which names nothing. The same key with a different body is 422. The write never runs twice: no second draft is cloned and no second failure is seeded. The Architect’s turn routes use the same policy: starting a conversation (POST /api/v3/workflows/start-architect-conversation, 201), sending a message (POST /api/v3/workflows/{workflowId}/architect-messages, 202), resetting the conversation and cancelling a turn (200). A replay returns the recorded answer and never starts a second turn. A 429 rate_limited refusal is not recorded: the key is released, so a retry with the same key runs normally once Retry-After passes. Without a key, a repeated fix request adds the failure to the draft’s conversation again (the first request may have cloned the draft), a repeated chat-task save creates a second workflow, and a repeated mode change sets the same mode again. The Forge MCP server sends a fresh key with each call when you pass no idempotencyKey, so to make an MCP retry safe, pass the same idempotencyKey again.

Workflow debug replay

Preparing, launching and cancelling a draft debug attempt (POST /api/v3/workflows/{workflowId}/debug-attempts, and POST /api/v3/workflow-debug-attempts/{attemptId}/ launch and cancel) use the workflow_debug_attempt policy. The same key and the same body within 24 hours return the recorded answer (201, 202 and 200) only while the caller still holds workflows:use, still owns the attempt the stored answer names, and may still debug its workflow at its home (workflows:use and workflows:read there), decided now. Otherwise the repeat returns 409 idempotency_result_unavailable, which names nothing. The same key with a different body is 422. A replay never re-runs the write: no second attempt is prepared and a launch never schedules again. launchDebugAttempt requires the key, and it is also the launch’s own key: the attempt is launched at most once for it, so a repeat after the 24 hours answers idempotent: true without running the node again. The procedure re-pin (POST /api/v3/workflows/{workflowId}/repin-procedure) replays under the draft graph rule: the recorded answer is disclosed only while the caller may still read the workflow it names.

Factory operation

Messaging a factory’s manager agent (POST /api/v3/factories/{factoryId}/send-message) and its kill switches (POST /api/v3/factories/{factoryId}/pause, POST /api/v3/factories/{factoryId}/resume and DELETE /api/v3/factories/{factoryId}) use the factory_operate policy. The same key and the same body within 24 hours return the recorded 200 only while the caller may still perform that operation on the factory the stored response names, decided now with the write’s own rule:
  • a message: factories:manage at the factory’s home and at the session’s home, with the session still open and in one of the factory’s channels;
  • a kill switch: switches:use at the factory’s home.
Otherwise, and for a stored refusal or error or any other stored body, the answer is 409 idempotency_result_unavailable, which names nothing. The same key with a different body is 422. The write never runs twice: a message is stored once, and a kill switch writes one audit event. Without a key, a repeated kill switch is a no-op by state (changed: false, no audit event), but a repeated message stores another message and starts another billable turn. The Forge MCP server sends a fresh key with each call when you pass no idempotencyKey, so to make an MCP retry safe, pass the same idempotencyKey again.

Example

Dispatching a workflow run with an idempotency key:
First call — a normal dispatch:
The same command run again inside the 24-hour window, by a caller that may currently read the original run:
The body is the stored response, byte for byte: meta.requestId is still the original attempt’s, and X-Request-Id names this one. convexWorkflowId identifies the workflow engine instance, not a workflow. The same repeat by a caller that may no longer read the original run:
In both cases the completed claim remains in place and the workflow is not dispatched again.

Error codes

These five codes join the canonical set on the Errors page.
1

Generate a UUID per logical operation

Mint one UUIDv4 at the moment you decide to perform an operation — not per HTTP attempt. “Dispatch the July close” is one logical operation and gets one key, however many times the wire attempt fails.
2

Reuse that key only on retries of that operation

Carry the key through every retry of the same request. Never carry it into a different operation, and never carry it into a request whose body you have changed — that is exactly what idempotency_key_reuse catches.
3

Treat 409 in_flight as retryable

idempotency_key_in_flight means your earlier attempt is still running. Back off briefly and retry the identical request; when the original finishes you get its recorded response.
4

Treat 422 reuse as a client bug

idempotency_key_reuse is never resolved by retrying. It means the key was bound to a different request. Fix the key lifecycle in your client.
5

Reconcile an unknown outcome under the same key

When a request fails without a response — a dropped connection, a timeout, an abort — it may or may not have taken effect. Within the 24-hour retention window, repeat the identical request under the same key: Forge replays the recorded response when current policy permits disclosing it, reports idempotency_key_in_flight or idempotency_outcome_unknown, or executes it once if the first attempt never arrived. After that window a completed key may have expired and the same key executes afresh, so read the resource before repeating. A new key is a new operation and can repeat the side effect. When the original response cannot be replayed or disclosed, Forge answers idempotency_result_unavailable, which confirms the key was used but not what happened — read the resource to learn the outcome.
6

Honour Retry-After on 429 and 503

A 429 or 503 may carry Retry-After (seconds or an HTTP date). Wait at least that long before the next attempt. It is a hint for the caller’s own retry policy; the key rules above still apply.
7

Reconcile before another attempt after a 5xx

Reusing the key after a 5xx does not execute the operation again. A 5xx does not prove the operation did not happen, so reconcile authorized resource state or escalate before deciding whether another logical operation under a fresh key is appropriate.
When current policy permits cached disclosure, Idempotency-Replayed: true identifies that response in client logs and metrics. The body remains byte-for-byte unchanged, including its original meta.requestId; X-Request-Id carries the current attempt ID.
  • Conventions — base URL, envelopes, scopes, pagination, rate limiting
  • Errors — the full canonical error-code catalog
  • Set up an External App — provisioning an External App, one of the principals a key is scoped to
  • Signed workflow ingress — the separate dedupeHeader mechanism for the excluded ingress surface