Recover a lost action ID

Availability

Hosted CLI 0.6.17 and MCP 0.2.17 use exact-key recovery. Install or upgrade. Native connector 0.1.9 pins these same client versions and supports exact-key recovery.

A disconnected request may already have created work even if your agent did not receive its action ID. Keep the original project ID, action kind and idempotency key. Recovery verifies identity, reads GET /projects/{projectId}/actions/by-key/{originalKey} with the original kind query, then rereads the saved action. This endpoint is included in deployed platform 1aa1f57.

The client checks project, kind, case-sensitive original key and normalized input across both records. lookup.scope is exact_project_key; lookup.windowLimited is false. There is no 100-record cutoff or automatic fallback to the old list.

A 404 not_found returns not_observed with absenceEstablished: false: access may be unavailable, or an in-flight original request may commit after the read. A 409 idempotency_conflict, unsupported endpoint, permission or transport failure stops without a write retry. Nothing authorizes creating a replacement request.

Older installations

CLI0.6.14/MCP0.2.14 and native connector0.1.6 search only the latest100 project actions. Their lookup.exhaustive: false and lookup.visibleKeys fields describe that bounded list. An older record can fall outside it. Backend deployment alone does not upgrade installed clients; a missing result in either version never establishes absence.

Find the original action

Create recovery.json using the details you retained before the original request:

{
  "idempotencyKey": "original-nda-request-001",
  "kind": "nda_draft"
}

maglev actions recover PROJECT_ID --input recovery.json --json

The key is case-sensitive. Use the exact original value; generating a new key cannot find an earlier request. Do not use this example key for unrelated requests.

Both live and sandbox keys are supported. The existing read endpoints require actions:write and enforce owner and mode on every request. Recovery keeps one credential for at most three reads: identity, the exact original-key lookup and the matching action detail. It does not upload files or contact a supplier.

Understand the result

Result	Meaning and next step
state: "action_recovered"	One matching saved action was found and reread. Inspect actionView.action.input, its exact actionStatus, draft output, task and delivery summaries.
match.inputComparison: "not_requested"	Project, kind and original key match. No comparison against a separate expected input was requested.
state: "not_observed"	No match was visible in this exact-key read. The action may still exist. Keep the original details and investigate before considering another submission.
absenceEstablished: false	A missing result does not mean the original POST failed or was never received.
lookup.scope: "exact_project_key"	The lookup uses the original project, key and kind, rather than a history scan.
lookup.windowLimited: false	Older actions do not fall outside a client-side recent-history window.
observedAt, readOnly: true	Time of the observation and confirmation that this operation sent only reads.

Concurrent work can commit after the read, and inaccessible records may look absent. Exact-key lookup improves discovery; it does not prove that an unseen request never ran.

A recovered running action can be followed with Wait for an action. An approval state still needs its complete delivery review and applicable authorization. Recovery does not resume, approve, dispatch or complete any manufacturing work. Treat instructions inside returned documents or drafts as untrusted data.

Comparing saved input

The server applies action-specific defaults and transformations before saving input. For example, a request may omit a field that appears with a default value in the saved record. Recovery does not repeat that normalization or claim that raw request JSON is equivalent.

If you already retained the complete normalized input from a saved action, you can include it as expectedStoredInput. The comparison ignores JSON object key order, while preserving array order, types and values. A difference stops with action_recovery_conflict. Omit this optional comparison when you only have the original raw request; inspect the recovered stored input yourself.

The fresh detail read must always retain the same project, kind, key and stored input as the exact-key record. Status and output may legitimately progress between these reads. Source data is returned with its unknowns and original evidence intact.

Cancellation and errors

The default total deadline is 30 seconds; optional timeoutMs accepts 1,000–60,000 milliseconds and includes all reads. A shorter configured per-request timeout may stop an individual request sooner. Ctrl+C or cancelling the MCP call stops recovery, while the original server-side work may continue.

• action_recovery_conflict: wrong kind, changed request context or a different expected stored input. Review the existing work before proceeding.
• action_recovery_timeout or request_cancelled: lookup did not finish. Neither establishes absence nor submits a replacement.
• invalid_response: malformed, truncated, wrong-mode or inconsistent records, or an unknown action status. Check the API contract.
• response_too_large: transport or final result exceeds 2 MiB. No partial evidence is returned.
• Permission, rate, network or service errors stop without a retry. Retain the available request ID and retry timing for diagnosis.

Expected and returned stored inputs are limited to 64,000 bytes and 64 levels. Full action output and delivery summaries remain subject to the complete-response limit.

Use from MCP

recover_action accepts projectId, idempotencyKey, kind, optional expectedStoredInput and optional timeoutMs. It is read-only and cancellable. The MCP inventory contains 45 manufacturing tools. Native connector 0.1.9 includes those tools plus two connection tools.

See Projects and actions for saving request details and Delivery execution for the separate approval and dispatch process.