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

# Idempotency

> How the Idempotency-Key header makes mutating /api/v3 and /api/v2 requests safe to retry: key format, scope, replay, the five idempotency error codes, retention and client behavior.

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](#stored-response-replay)).

> [!WARNING]
>
> 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](https://docs.gloo.com/forge/reference/index.md#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](https://docs.gloo.com/forge/reference/mcp-server.md#unknown-outcomes).

## The header

```http theme={null}
Idempotency-Key: 3f9c2e18-5a4d-4b7e-9c11-8e2f6a0d4b53
```

| Property | Value |
| - | - |
| Name | `Idempotency-Key` — matched case-insensitively |
| Required | No. Omit it and the request executes normally, unprotected. |
| Value | A client-supplied opaque string. Forge never parses it. |
| Length | 1–255 characters |
| Character set | Printable ASCII only (`0x21`–`0x7E`) — no spaces, tabs, newlines, control characters, or non-ASCII |

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.

```json theme={null}
{
  "error": {
    "code": "idempotency_key_invalid",
    "message": "Idempotency-Key must be at most 255 characters."
  },
  "meta": { "requestId": "req_abc123" }
}
```

## Where it applies

| Surface | Behavior |
| - | - |
| Mutating `/api/v3/*` and `/api/v2/*` routes (`POST`, `PUT`, `PATCH`, `DELETE`) | Idempotency enforced. The OpenAPI spec declares the header (`components.parameters.IdempotencyKey`) on every one of these operations, and on no other. |
| Read-only `/api/v3/*` and `/api/v2/*` routes (`GET`) | Header ignored. Reads have no side effect to deduplicate. |
| Reads sent as `POST` (`/api/v3/knowledge-entries/{entryId}/lookup`, `/api/v3/knowledge-chunks/search`, `/api/v3/knowledge/ask`, `/api/v3/knowledge-snapshots/search`, `/api/v3/knowledge-records/search`, `/api/v3/knowledge-records/lookup`, `/api/v3/knowledge-synchronized-source-providers/{providerKey}/search-containers`, `/api/v3/governance-trust-policies/simulate`, `/api/v3/pods/preview-membership`, `/api/v3/pods/preview-customer-assignment`, `/api/v3/persons/preview-merge`, the four `/api/v3/projects/{projectId}/…preview…` staffing reads, `/api/v3/workflows/test-route-condition`, and their `/api/v2` routes) | Header ignored, and not declared in the spec. Every call re-checks your scopes and access, so a repeat never returns data you can no longer see. A repeated `ask` runs the model again and is billed again. |
| `POST /api/v2/ingress/*` | **Excluded by design** — see below |

### 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](https://docs.gloo.com/forge/run/ingress.md#idempotency).

## Scope of a key

A key is scoped to the triple:

```text theme={null}
(principal, route, key)
```

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](#stored-response-replay)). A denied permission returns `403`. A response that was never stored answers only its `data.id` ([Id-only replay](#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](#workflow-dispatch-replay), [Webhook revoke and replay](#webhook-revoke-and-replay), [Chat write replay](#chat-write-replay), [Memory write replay](#memory-write-replay), [Knowledge write replay](#knowledge-write-replay), [Knowledge remedy replay](#knowledge-remedy-replay), [Knowledge source replay](#knowledge-source-replay), [Knowledge curation replay](#knowledge-curation-replay), [Knowledge settings and re-embed replay](#knowledge-settings-and-re-embed-replay), [External App customer writes](#external-app-customer-writes), [Customer directory writes](#customer-directory-writes), [Skill write replay](#skill-write-replay), [Run cancel replay](#run-cancel-replay) and [Run control replay](#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`.

> [!WARNING]
>
> **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](#id-only-replay)), else `409` `idempotency_result_unavailable`. Its reference page says so.

```http theme={null}
HTTP/1.1 201 Created
Idempotent-Replayed: true
Idempotency-Replayed: true
X-Request-Id: req_2

{ "data": { "id": "k57b3f9x2c1d", "name": "nightly" }, "meta": { "requestId": "req_1" } }
```

`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](#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.

> [!NOTE]
>
> `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.

```http theme={null}
HTTP/1.1 201 Created
Idempotent-Replayed: true
Idempotency-Replayed: true
Idempotency-Replay-Disclosure: id-only

{ "data": { "id": "k57b3f9x2c1d" }, "meta": { "requestId": "req_2", "idempotentReplay": "id_only" } }
```

The [OpenAPI spec](https://docs.gloo.com/forge/reference/openapi.json) 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.

> [!WARNING]
>
> **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.

| Original outcome | A repeat with the same key gets |
| - | - |
| A workflow dispatch whose original run you may currently read | The stored `200` response, with `Idempotency-Replayed: true` — not re-executed |
| A webhook revoke, or a webhook delivery replay whose deliveries still belong to your app | The stored response, with `Idempotency-Replayed: true` — not re-executed |
| A chat session create or message send whose session you may currently read | The stored `201` response, with `Idempotency-Replayed: true` — not re-executed |
| A file upload still bound to your current org tree | The stored `201` response, with `Idempotency-Replayed: true` — the file is not stored again |
| An External App customer create, find-or-create or update, while your app is still linked to that customer | The stored response, with `Idempotency-Replayed: true` — not re-executed |
| A customer directory create, update or archive, while you still reach `customers:read` and hold both customer permissions at the deployment root | The stored `201` (create) or `200` response, with `Idempotency-Replayed: true` — not re-executed, and a create provisions nothing in WorkOS again |
| A skill create or update, while you still hold `skills:write` | The stored response, with `Idempotency-Replayed: true` — not re-executed |
| A run cancel request, while you may still read the run and hold `runs:manage` at its home | The stored `200` response, with `Idempotency-Replayed: true` — not re-executed |
| A webhook create | Its original `201` and only the webhook's `data.id` ([Id-only replay](#id-only-replay)) — the secret is never stored, and no second webhook is registered |
| A webhook secret rotation | `409` `idempotency_result_unavailable` — its response names only the secret, which is never stored, and it does not rotate again |
| An outcome rating (`POST /api/v3/outcomes/{outcomeId}/rate`), while you may still rate that outcome (`workflows:use` at its workflow's home, and its owner or a `platform:manage` holder) | The stored `200` response, with `Idempotency-Replayed: true` — not re-executed |
| A procedure administration, lifecycle or Procedure Builder write (`POST /api/v3/procedures/delete-versions`; `POST /api/v3/procedures/{procedureId}/` `deprecate`, `rename`, `set-connections`, `clone`, `promote`, `request-review`, `resolve-review-hold`, `open-in-builder`, `builder-messages`, `retry-builder-turn`, `reset-builder` and `stop-builder-turn`; `POST /api/v3/procedures/start-builder`; `POST /api/v3/procedure-validation-runs/{validationRunId}/cancel`; and `POST /api/v3/procedure-script-promotions/{proposalId}/` `accept` and `dismiss`), while you still hold the route's permission where each record it names lives (a version at its home: a deleted version at its surviving siblings' homes, else the platform scope; a rename at the family head's home; a validation run at its procedure's home; a proposal at the platform scope) | The stored success response (`200`, `201` or `202`), with `Idempotency-Replayed: true` — not re-executed |
| A sandbox command replay (`POST /api/v3/sandbox-snapshots/{snapshotId}/replay-command`) | `409` `idempotency_result_unavailable` — its output may hold secrets and is never stored, and the command is not run again |
| Any stored response, on a route without a replay policy of its own that requires a permission, while you still hold the route's permissions | The identical stored status and body, with `Idempotent-Replayed: true` ([Stored-response replay](#stored-response-replay)) — not re-executed |
| A success that named `data.id` on a route without a replay policy of its own, when its response was not stored (over 32 KiB) or the route decides access at the record's home or by who you are | Its original status and only that id ([Id-only replay](#id-only-replay)) — not re-executed |
| A stored response on a route whose own replay policy withholds it | `409` `idempotency_result_unavailable` — not re-executed |
| The request failed before producing a response | `409` `idempotency_result_unavailable` — not re-executed |
| A success of a route that returns a one-time secret (see below) | Its original status and only the `data.id` it named, never the secret — not re-executed |
| Any other outcome of a route that returns a one-time secret | `409` `idempotency_result_unavailable` — not re-executed |

### 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](#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](https://docs.gloo.com/forge/reference/http-api/workflows/listTriggers.md), 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](https://docs.gloo.com/forge/reference/http-api/files#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](https://docs.gloo.com/forge/reference/http-api/externalApps#who-can-manage-an-app). 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](#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](https://docs.gloo.com/forge/reference/http-api/chat/getSession.md) 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](https://docs.gloo.com/forge/reference/http-api/memory/get.md) 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](https://docs.gloo.com/forge/reference/http-api/knowledge/get.md) 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](#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](#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](https://docs.gloo.com/forge/reference/http-api/projects/getStaffing.md) or [Get project pod staffing](https://docs.gloo.com/forge/reference/http-api/projects/getPodStaffing.md) 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](https://docs.gloo.com/forge/reference/http-api/workforce/getEngineeringScope.md) or [List reporting categories](https://docs.gloo.com/forge/reference/http-api/workforce/listReportingCategories.md) 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](https://docs.gloo.com/forge/reference/http-api/workforce/getPerson.md), [List person identities](https://docs.gloo.com/forge/reference/http-api/workforce/listPersonIdentities.md), [List person email claims](https://docs.gloo.com/forge/reference/http-api/workforce/listPersonEmailClaims.md) or [Get person communication profile](https://docs.gloo.com/forge/reference/http-api/workforce/getPersonCommunicationProfile.md) 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](https://docs.gloo.com/forge/reference/http-api/workflows/getFiscalCalendar.md) or [listSteps](https://docs.gloo.com/forge/reference/http-api/workflows/listSteps.md) 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](https://docs.gloo.com/forge/reference/http-api/workflows/listVersions.md) or [getDraft](https://docs.gloo.com/forge/reference/http-api/workflows/getDraft.md) 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](#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](#workflow-dispatch-replay): 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](https://docs.gloo.com/forge/reference/http-api/workflows/getTrigger.md) for the current state. `createIngressTrigger` and `rotateIngressToken` are [never replayed](#routes-that-return-a-one-time-secret).

## 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](https://docs.gloo.com/forge/reference/http-api/synthesis/getRequest.md) 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](https://docs.gloo.com/forge/reference/http-api/governance/getHumanTask.md) 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](https://docs.gloo.com/forge/reference/http-api/governance/getHumanTask.md) 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:

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/workflows/dispatch" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9c2e18-5a4d-4b7e-9c11-8e2f6a0d4b53" \
  -d '{
    "name": "monthly-close",
    "runtimeArgs": { "period": "2026-07" }
  }'
```

First call — a normal dispatch:

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_a1

{
  "data": { "convexWorkflowId": "engine_4d2e", "runId": "run_7fb1c9" },
  "meta": { "requestId": "req_a1" }
}
```

The same command run again inside the 24-hour window, by a caller that may currently read the original run:

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
Idempotency-Replayed: true
X-Request-Id: req_a2

{
  "data": { "convexWorkflowId": "engine_4d2e", "runId": "run_7fb1c9" },
  "meta": { "requestId": "req_a1" }
}
```

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:

```http theme={null}
HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_result_unavailable",
    "message": "This request completed, but its response cannot be disclosed under the current authorization policy. The original request was not repeated."
  },
  "meta": { "requestId": "req_a2" }
}
```

In both cases the completed claim remains in place and the workflow is not dispatched again.

## Error codes

| `error.code` | HTTP | When it fires | Consumer action |
| - | - | - | - |
| `idempotency_key_invalid` | 400 | The `Idempotency-Key` header is empty, longer than 255 characters, or contains a byte outside printable ASCII (`0x21`–`0x7E`). | Fix the key generator. This is a client bug — a UUIDv4 string always satisfies the format. |
| `idempotency_key_in_flight` | 409 | A request with the same (principal, route, key) triple is still executing. | Retryable. Wait a short delay and retry the identical request. |
| `idempotency_outcome_unknown` | 409 | An earlier attempt with this key stopped without recording an outcome. Whether it took effect is unknown. It was **not** retried. | Not retryable with this key. Reconcile authorized resource state or escalate; use a new key only if another effect is appropriate. |
| `idempotency_key_reuse` | 422 | The key was already used **on this same route** with a different query string or body. Nothing was executed. | Not retryable. This is a client bug — the key was reused for a different logical operation. Generate a new key. |
| `idempotency_result_unavailable` | 409 | The original response cannot be disclosed under current policy, exceeded the 32 KiB storage ceiling, or was never recorded, and it named no created id an [id-only replay](#id-only-replay) could return. The original request was **not** re-executed. | Do not automatically retry with a new key. Query the resource directly to reconcile the outcome first. |

These five codes join the canonical set on the [Errors](https://docs.gloo.com/forge/reference/errors.md) page.

## Recommended client behavior

**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](#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.

> [!TIP]
>
> 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.

## Related

* [Conventions](https://docs.gloo.com/forge/reference/conventions.md) — base URL, envelopes, scopes, pagination, rate limiting
* [Errors](https://docs.gloo.com/forge/reference/errors.md) — the full canonical error-code catalog
* [Set up an External App](https://docs.gloo.com/forge/build/set-up-external-app.md) — provisioning an External App, one of the principals a key is scoped to
* [Signed workflow ingress](https://docs.gloo.com/forge/run/ingress.md) — the separate `dedupeHeader` mechanism for the excluded ingress surface


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