Replay a policy version over past actions
const url = 'http://127.0.0.1:8080/v1/policies/example/versions/1/replay';const options = { method: 'POST', headers: { 'Deedglass-Version': '2026-10-01', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"from":"2026-09-26T07:03:15Z","to":"2026-10-04T07:03:15Z"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://127.0.0.1:8080/v1/policies/example/versions/1/replay \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Deedglass-Version: 2026-10-01' \ --data '{ "from": "2026-09-26T07:03:15Z", "to": "2026-10-04T07:03:15Z" }'Queues a replay (S27): every decision recorded in the window is evaluated again under this version, in shadow mode, and compared with a baseline. A replay never runs a tool, never reserves a budget or touches usage, never seals a deed and never emits an action event. The baseline is the decisions recorded at the time (recorded, the default) or another version of the same policy evaluated over the same inputs (version), which separates your change from everything else that differed at the time. The answer is 202 with the replay object (status: queued); a runner on any instance picks it up (one running replay per org), and GET /v1/replays/{id} shows its progress and, once it succeeded, its result. The same inputs, version and sqlguard version give the same result_digest. The window defaults to the last 7 days (to defaults to now, from to 7 days before to); from must be before to and the window at most 90 days (400 replay_window_invalid). More than 1,000,000 actions in the window is 400 replay_too_large, and nothing is queued. An unknown policy or version is 404 not_found; a {v} that isn’t a number is 400 validation_failed. Each org starts at most 10 replays an hour (429 rate_limited, with Retry-After). Bodies up to 16 KiB. An admin+ Console session (with the Deedglass-CSRF header) or an org admin key (admin scope); agent keys get 403 insufficient_scope (“Agent keys can’t read Insights. Use the Console or an org admin key.”).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A pol_ id or the policy’s name.
The version number to replay
Header Parameters
Section titled “Header Parameters”The API version (YYYY-MM-DD). Leave it out to use your org’s pinned version (public routes use the latest). An unknown version is 400 api_version_invalid.
Needed when the request uses a Console session (it changes state); without it the answer is 403 csrf_failed. Not sent with an API key.
1 to 255 printable ASCII characters. A retry with the same key and body returns the stored response with Deedglass-Idempotent-Replayed: true for 24 hours.
Request Body
Section titled “Request Body”What to replay over. Every field is optional: the window defaults to the 7 days before to, and to to now; the baseline to the decisions recorded at the time.
object
The window’s start (RFC 3339).
The window’s end (RFC 3339). At most 90 days after from.
object
version only: the version of the same policy to compare with.
Examples
The last 8 days, against the decisions recorded at the time
{ "from": "2026-09-26T07:03:15Z", "to": "2026-10-04T07:03:15Z"}Against version 2 of the same policy, over the same inputs
{ "from": "2026-09-26T07:03:15Z", "to": "2026-10-04T07:03:15Z", "baseline": { "type": "version", "version": 2 }}Responses
Section titled “Responses”The replay, queued.
A replay job (S27): what it replays, its progress and, once status is succeeded, its result (summary through elapsed_ms; transitions and rule_changes are absent when there are none). elapsed_ms is not part of result_digest.
object
The version replayed.
object
The policy id (pol_…).
The version number (0 for a draft).
The version id (pv_…). Absent for a draft.
“sha256:” + lowercase hex of SHA-256.
A draft’s source hash. Absent for a stored version.
What the candidate is compared with: the decisions recorded at the time (recorded), or another version of the same policy evaluated over the same inputs (version).
object
The baseline version number; 0 for recorded.
version only (pv_…).
version only.
object
object
The actions in the window
Processed / total
Who asked for it.
object
usr_…, key_…, or deedglass for the system.
Runs started. A runner that lost its lease starts again from zero.
A failed replay’s cause.
object
actions = evaluated + unknown and evaluated = unchanged + changed + rule_changed.
object
The decision would differ.
The same decision
Counted but not evaluated (see unknown); never guessed.
Every action whose decision would change from from (the baseline) to to (the candidate). The full Transition schema is in openapi.yaml.
object
The same decision, reached by a different rule. The full RuleChange schema is in openapi.yaml.
object
Actions a replay counted but couldn’t evaluate, by reason.
object
Retention removed the stored decision input.
Recorded before decision inputs were stored.
A stored input in a newer format.
A stored input that doesn’t decode.
The evaluation hit its time limit.
The sqlguard versions recorded with the decisions, next to the current one. SQL facts are computed again at replay, so a difference is shown, never hidden.
object
The same inputs, candidate, baseline and sqlguard version give the same digest.
Examples
acme-sim v3 queued over 5,890 actions
{ "object": "replay", "id": "rpl_01m42vjp4z65td5hkdkcefczms", "status": "queued", "purpose": "manual", "candidate": { "policy": "pol_01m42v9q4bjwfqmk8bd58vzkdh", "name": "acme-sim", "version": 3, "version_id": "pv_01m42vcmkk193cy009pdzt4c6s", "version_hash": "sha256:3d09f641a6d5f6962ef719d05a59c6cea0362d950ea6f920418b01125b6bbb7b" }, "baseline": { "type": "recorded", "version": 0 }, "window": { "from": "2026-09-26T07:03:15Z", "to": "2026-10-04T07:03:15Z" }, "progress": { "processed": 0, "total": 5890, "percent": 0 }, "requested_by": { "type": "api_key", "id": "key_01m42vbv2s105agpkrzjpnhzpa" }, "attempts": 0, "created_at": "2026-10-04T07:03:15.359342Z", "started_at": null, "finished_at": null, "error": null}Headers
Section titled “Headers”This request’s id. Quote it to support; it matches error.request_id.
The API version this response follows.
Present, and true, when the response is a stored one replayed for an Idempotency-Key.
replay_window_invalid, replay_too_large or validation_failed.
object
object
One or more calm sentences with the next step.
The request field, query parameter or header the error is about.
On policy_invalid only. Each problem with its line, code and hint.
One finding about a policy file, with its position and the next step. Codes are stable and listed in docs/POLICY_ERRORS.md. In the policy_invalid error envelope each diagnostic also carries object: policy_diagnostic. The full PolicyDiagnostic schema is in openapi.yaml.
object
One agent action. Its sections mirror the deed’s. status is the one field an agent needs; state is the exact lifecycle state (docs/GATE.md). The Gate’s own responses (POST /v1/actions and its result report) add execution.result and witness.reasons; lists leave both out. The full Action schema is in openapi.yaml.
object
On undo_unavailable only. Every check of the undo, each with its fix. Additive (S23).
One of the twelve safety checks (S23 §3.3). Available means no check failed. The full UndoCheck schema is in openapi.yaml.
object
Examples
from is after to
{ "error": { "type": "invalid_request_error", "code": "replay_window_invalid", "message": "The window must start before it ends, and it can be at most 90 days long. Send from before to.", "param": "to", "request_id": "req_01m42vk215p3bfyp3xasewttq4", "doc_url": "https://docs.deedglass.com/errors/replay_window_invalid" }}More than 1,000,000 actions in the window
{ "error": { "type": "invalid_request_error", "code": "replay_too_large", "message": "This replay covers 1,240,512 actions; the limit is 1,000,000. Narrow the window with from and to.", "param": null, "request_id": "req_01m42vk3a7c9e1g3j5m7p9s1v3", "doc_url": "https://docs.deedglass.com/errors/replay_too_large" }}Headers
Section titled “Headers”This request’s id. Quote it to support; it matches error.request_id.
An agent key (insufficient_scope), or a viewer session (insufficient_role).
object
object
One or more calm sentences with the next step.
The request field, query parameter or header the error is about.
On policy_invalid only. Each problem with its line, code and hint.
One finding about a policy file, with its position and the next step. Codes are stable and listed in docs/POLICY_ERRORS.md. In the policy_invalid error envelope each diagnostic also carries object: policy_diagnostic. The full PolicyDiagnostic schema is in openapi.yaml.
object
One agent action. Its sections mirror the deed’s. status is the one field an agent needs; state is the exact lifecycle state (docs/GATE.md). The Gate’s own responses (POST /v1/actions and its result report) add execution.result and witness.reasons; lists leave both out. The full Action schema is in openapi.yaml.
object
On undo_unavailable only. Every check of the undo, each with its fix. Additive (S23).
One of the twelve safety checks (S23 §3.3). Available means no check failed. The full UndoCheck schema is in openapi.yaml.
object
Example
{ "error": { "type": "permission_error", "code": "insufficient_scope", "message": "Agent keys can't read Insights. Use the Console or an org admin key.", "param": null, "request_id": "req_01m42vk4b8d0f2h4k6n8q0t2w4", "doc_url": "https://docs.deedglass.com/errors/insufficient_scope" }}Headers
Section titled “Headers”This request’s id. Quote it to support; it matches error.request_id.
No such policy, or no such version of it.
object
object
One or more calm sentences with the next step.
The request field, query parameter or header the error is about.
On policy_invalid only. Each problem with its line, code and hint.
One finding about a policy file, with its position and the next step. Codes are stable and listed in docs/POLICY_ERRORS.md. In the policy_invalid error envelope each diagnostic also carries object: policy_diagnostic. The full PolicyDiagnostic schema is in openapi.yaml.
object
One agent action. Its sections mirror the deed’s. status is the one field an agent needs; state is the exact lifecycle state (docs/GATE.md). The Gate’s own responses (POST /v1/actions and its result report) add execution.result and witness.reasons; lists leave both out. The full Action schema is in openapi.yaml.
object
On undo_unavailable only. Every check of the undo, each with its fix. Additive (S23).
One of the twelve safety checks (S23 §3.3). Available means no check failed. The full UndoCheck schema is in openapi.yaml.
object
Example
{ "error": { "type": "invalid_request_error", "code": "not_found", "message": "No version 7 of acme-sim. Versions 1 to 3 exist. List them: deedglass policy versions acme-sim", "param": "version", "request_id": "req_01m42vk5c9e1g3j5m7p9s1v3x5", "doc_url": "https://docs.deedglass.com/errors/not_found" }}Headers
Section titled “Headers”This request’s id. Quote it to support; it matches error.request_id.
This org started 10 replays in the last hour.
object
object
One or more calm sentences with the next step.
The request field, query parameter or header the error is about.
On policy_invalid only. Each problem with its line, code and hint.
One finding about a policy file, with its position and the next step. Codes are stable and listed in docs/POLICY_ERRORS.md. In the policy_invalid error envelope each diagnostic also carries object: policy_diagnostic. The full PolicyDiagnostic schema is in openapi.yaml.
object
One agent action. Its sections mirror the deed’s. status is the one field an agent needs; state is the exact lifecycle state (docs/GATE.md). The Gate’s own responses (POST /v1/actions and its result report) add execution.result and witness.reasons; lists leave both out. The full Action schema is in openapi.yaml.
object
On undo_unavailable only. Every check of the undo, each with its fix. Additive (S23).
One of the twelve safety checks (S23 §3.3). Available means no check failed. The full UndoCheck schema is in openapi.yaml.
object
Example
{ "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "This org started 10 replays in the last hour. Try again later, or narrow the window of the ones running.", "param": null, "request_id": "req_01m42vk6d0f2h4k6n8q0t2w4y6", "doc_url": "https://docs.deedglass.com/errors/rate_limited" }}Headers
Section titled “Headers”This request’s id. Quote it to support; it matches error.request_id.
Seconds to wait (300).
default
Section titled “default”An error. Every error has this envelope; doc_url explains the code.
object
object
One or more calm sentences with the next step.
The request field, query parameter or header the error is about.
On policy_invalid only. Each problem with its line, code and hint.
One finding about a policy file, with its position and the next step. Codes are stable and listed in docs/POLICY_ERRORS.md. In the policy_invalid error envelope each diagnostic also carries object: policy_diagnostic. The full PolicyDiagnostic schema is in openapi.yaml.
object
One agent action. Its sections mirror the deed’s. status is the one field an agent needs; state is the exact lifecycle state (docs/GATE.md). The Gate’s own responses (POST /v1/actions and its result report) add execution.result and witness.reasons; lists leave both out. The full Action schema is in openapi.yaml.
object
On undo_unavailable only. Every check of the undo, each with its fix. Additive (S23).
One of the twelve safety checks (S23 §3.3). Available means no check failed. The full UndoCheck schema is in openapi.yaml.
object
Example
{ "error": { "type": "invalid_request_error", "code": "not_found", "message": "There's no endpoint at GET /v1/helth. Did you mean /v1/health?", "param": null, "request_id": "req_01j9zr3m5k8q2w7x4t6v0b1c9d", "doc_url": "https://docs.deedglass.com/errors/not_found" }}Headers
Section titled “Headers”This request’s id. Quote it to support; it matches error.request_id.
The API version this response follows.