---
title: "Stack update and rollback readiness for an AI observer"
method: GET
path: "/api/stacks/{stackName}/observation/readiness"
tags: ["Observation"]
---

# Stack update and rollback readiness for an AI observer

`GET /api/stacks/{stackName}/observation/readiness`

## Request

- Base URL: `https://localhost:1852`
- URL: `https://localhost:1852/api/stacks/{stackName}/observation/readiness`
- Auth: HTTP bearer

Returns one stack's canonical update and rollback readiness verdicts,
projected for an Observe Only token. Each verdict slot carries the verdict,
the id of its strongest reason, and when it was computed; the free-text
description behind the verdict is withheld. `unavailableReason` is set to
`summary_truncated` or `domain_error` only when both slots are null. This is
one of the five paths an Observe Only token may reach. Requires `stack:read`
permission for the named stack.

## Path parameters

- `stackName` string, required

## Headers

- `x-node-id` integer

## Response `200`

Readiness verdicts wrapped in the observation envelope.

- object
  - `schemaVersion` 1, required
  - `generatedAt` integer, required: Epoch ms of the evidence behind the answer.
  - `data` ObservationStackReadinessData, required
    - `stack` string, required
    - `update` object, nullable, required: The canonical update readiness verdict, or null when it was never evaluated.
      - `verdict` 'ready' | 'ready_with_warnings' | 'review_required' | 'blocked' | 'unknown'
      - `topReasonId` string, nullable
      - `hasUpdate` boolean
      - `computedAt` integer
    - `rollback` object, nullable, required: The canonical rollback readiness verdict, or null when it was never evaluated.
      - `overall` 'ready' | 'partial' | 'not_ready'
      - `topReasonId` string, nullable
      - `computedAt` integer
    - `unavailableReason` 'summary_truncated' | 'domain_error', nullable, required: Set only when both `update` and `rollback` are null.

## Other responses

- `400`: Invalid stack name, or `capability_unavailable` when a targeted remote does not advertise `agent-observation-v1`.
- `401`: Authentication required. Provide a valid Bearer token. On a remote node, a 401 that carries an `x-sencho-proxy: 1` response header came from the node rejecting the API token stored for it on the hub, not from the caller's own token.
- `403`: Insufficient permissions or license tier.
- `404`: The stack does not exist on the node (`STACK_NOT_FOUND`).
- `500`: Internal server error.
- `503`: The targeted remote node is down or did not give a usable answer to the capability check (`node_unreachable`). A disconnected Pilot tunnel or a node with no API URL or token configured also answers 503, without a code. A Distributed API Proxy node that answers the check but rejects the API token stored for it answers 401 without a code, not 503.

## Changes

- **2026-11-01** `bef9c9739469`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/studio-saelix/apis/sencho-api/changes/api/stacks/:stackName/observation/readiness/get.md)

---

[API](https://skmtc.dev/studio-saelix/apis/sencho-api.md) - [All operations](https://skmtc.dev/studio-saelix/apis/sencho-api/llms.txt) - [OpenAPI document](https://skmtc.dev/studio-saelix/apis/sencho-api/revisions/bb1a37e1ed3b?raw)