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

# Resource operation review HTTP contract

Use these owner-only endpoints to inspect cloud resource operations whose outcome may be uncertain. They are available when the lifecycle service is configured. Every lookup is tenant-scoped. An acknowledgement records a review decision; it is not proof that a cloud resource is absent or that cleanup succeeded.

Examples use an owner token in `HEXAGON_API_TOKEN` and the control-plane origin without `/v1` in `HEXAGON_API_URL`. Resource identifiers belong in private recovery records, not public reports. Missing authentication returns 401; an application token returns `403 owner_token_required`.

## List operations

`GET /v1/resource-operations` returns **200**, `{operations:[...],next_offset:number|null}`. Query parameters are integer `limit` (1–100, default 50) and nonnegative integer `offset` (default 0). Results sort by `updated_at DESC, id ASC`. Concurrent updates can move rows between pages; this is not a stable audit snapshot. The endpoint lists all operation states, not just unknown operations.

```sh theme={null}
curl --fail-with-body --silent --show-error --get \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  --data-urlencode 'limit=50' --data-urlencode 'offset=0' \
  "$HEXAGON_API_URL/v1/resource-operations"
```

| Returned field | Meaning |
| - | - |
| `id`, `session_id` | Operation and owning Session IDs |
| `kind`, `state` | Resource operation kind/state; not the Run state |
| `provider_resource_id` | Recorded remote resource ID, if known |
| `attempt_count` | Recorded attempt count; not a license to repeat a mutation |
| `review_state` | Independent review status, such as automatic/needs\_review/acknowledged |
| `last_checked_at`, `next_check_at` | Inspection/scheduling timestamps, possibly null |
| `created_at`, `updated_at` | Record timestamps |
| `reason`, `failure` | Selected diagnostic fields from operation detail, possibly null |
| `provider_operation_id`, `provider_build_id` | Provider-side operation/build receipt, if recorded |
| `provider`, `session_state` | Joined provider and current Session state; list response only |

The projection omits raw operation detail and credentials. Optional Provider identifiers are not guaranteed to exist after a lost creation response.

## Inspect one operation

`GET /v1/resource-operations/{id}` returns **200** with the operation fields above, excluding the list-only provider/session\_state, and adds `reviews`. The reviews array contains at most the latest 50 entries ordered by creation time descending; each has `id`, `action`, `note`, `created_at`. There is no review-history pagination parameter.

```sh theme={null}
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" \
  "$HEXAGON_API_URL/v1/resource-operations/$HEXAGON_OPERATION_ID"
```

Missing/foreign operation returns `404 resource_operation_not_found`. Inspect the Session separately when using this detail response; do not expect the two joined list fields to be present.

## Record a review or request reconciliation

`POST /v1/resource-operations/{id}/review` accepts a strict body:

| Field | Constraint |
| - | - |
| `action` | Required acknowledge, reopen or reconcile |
| `note` | Optional string, trimmed, at most 2000 characters; default empty |

Only an operation whose state is **unknown** accepts a review. The error name `resource_operation_not_pending` does not mean that a state named pending is eligible.

| Action | Committed change | Immediate cloud work |
| - | - | - |
| acknowledge | Appends review; sets review\_state=acknowledged and clears next\_check\_at | None |
| reopen | Appends review; sets review\_state=automatic and next\_check\_at=now | None; makes it eligible for automatic reconciliation |
| reconcile | Same review/scheduling update as reopen | Invokes the applicable Session lifecycle operation after the review transaction commits |

The following requests reopening, not confirmed cleanup:

```sh theme={null}
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $HEXAGON_API_TOKEN" -H 'Content-Type: application/json' \
  --data '{"action":"reopen","note":"Review the existing operation and its recorded provider identifiers."}' \
  "$HEXAGON_API_URL/v1/resource-operations/$HEXAGON_OPERATION_ID/review"
```

Choose acknowledge only when intentionally acknowledging the unresolved case. To request active reconciliation, use action reconcile with a note describing the investigation. Lifecycle dispatch follows this precedence:

1. Session closing or operation kind delete → close the Session.
2. Kind checkpoint → pause the Session at Sandbox scope.
3. Kind restore → resume the Session.
4. Otherwise → call the Session provisioning reconciliation path.

This is a Session-level operation, not a generic read-only Provider lookup. It may perform the lifecycle work authorized by that path. It must retain the original operation/resource identity rather than blindly creating replacement resources. In particular, do not assume an arbitrary new operation kind has its own dedicated dispatch branch.

Success returns **200** with the current detail object. A caught domain `ExecutionError` during immediate reconciliation also returns **200**, adding `reconciliation_error` with its code. Thus HTTP 200 alone does not prove resolution. Check operation state, review\_state, reconciliation\_error, Session state and available Provider evidence. Unexpected non-domain exceptions propagate through normal server error handling, even though the review transaction may already have committed.

Malformed bodies return `400 invalid_request`; unknown/foreign operation returns 404; any operation not currently unknown returns `409 resource_operation_not_pending`. There is no Idempotency-Key support: repeating an accepted review can append another review record while the operation remains unknown. If the response is lost, read the latest reviews and state before deciding whether another action is necessary.

Acknowledgement does not change unknown into completed/deleted, and reopening does not guarantee an automatic attempt has already run. Keep unresolved IDs until actual cleanup can be confirmed. See [reconciliation procedure](https://docs.hexagon.autos/en/operate/reconciliation.md) for investigation and Provider checks.

Sources: [operation queries/review dispatch](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/operations.ts), [route parameters](https://github.com/NexusFox88/docs/blob/main/resources/apps/control-plane/server.ts), [lifecycle reconciliation](https://github.com/NexusFox88/docs/blob/main/resources/modules/sandboxes/lifecycle.ts). Source and schema review do not establish fresh cloud recovery acceptance.

## Follow one unresolved operation through review

Assume an operation starts with `state: unknown`, `review_state: automatic` and no reviews. The following sequence describes review records; it does not assert any Provider outcome:

| Request | Recorded result | What remains unresolved |
| - | - | - |
| acknowledge | First review appended, review\_state acknowledged, next\_check\_at cleared | Operation state remains unknown; no lifecycle callback runs |
| acknowledge again | Another review appended, still acknowledged | Even the same Idempotency-Key header does not deduplicate this action |
| reopen | Another review appended, automatic scheduling restored | No synchronous lifecycle callback runs; the worker may act later |
| reconcile | Another review commits before the selected lifecycle callback | Callback completion alone does not guarantee that state changed from unknown |

`attempt_count` tracks lifecycle attempts and is not a review count. Acknowledge/reopen do not themselves increment it. The latest 50 reviews are a bounded history, so absence of an older note from the detail response does not prove that no such review was ever recorded. Keep your own private operation/action intent and distinguish it from a receipt.

## Handle the response without automatic replay

| Response | Client interpretation | Next step |
| - | - | - |
| `200`, state still unknown | Review was accepted, outcome remains uncertain | Inspect current operation/Session and Provider evidence; retain identifiers |
| `200` with reconciliation\_error | Review committed; immediate lifecycle work reported a domain error | Display that error and inspect state; do not classify the operation as resolved |
| `409 resource_operation_not_pending` | Current operation state is not eligible for review | Read the operation again; do not invent a new operation or retry a different action blindly |
| `500 internal_error` | The request failed, but a preceding review transaction may have committed | Read reviews and current state before another mutation |
| Lost response | No confirmed response, regardless of whether the server committed | Recover the same operation's records; never infer no resource or no review from a transport failure |

The SDK raises on non-success HTTP responses, but a `200` with `reconciliation_error` is a normal returned object. Inspect that field and `state` after the SDK call. See the [application recovery procedure](https://docs.hexagon.autos/en/operate/reconciliation.md) for the operational decision path.

The [route/transaction review](https://github.com/NexusFox88/docs/blob/main/resources/testing/evidence/2026-11-20-resource-review-http-contract-review.json) passed 30 current-source handler checks with real PostgreSQL in an isolated schema, including eight controlled lifecycle dispatches. It verified pagination/projections, tenant/role rejection, review eligibility, duplicate review behavior, commit-before-dispatch ordering, dispatch precedence, error responses and the 50-review limit. Lifecycle callbacks were stubs; these results do not claim a successful cloud reconciliation. The temporary schema was removed.

Next: [HTTP inventory](https://docs.hexagon.autos/en/reference/http.md), [Session lifecycle](https://docs.hexagon.autos/en/reference/sessions.md).


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