Skip to main content
Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

​
Goal

Integrate the version 1 read contract while preserving identity, access checks and source availability.

​
Prerequisites

  • An authenticated session or API token with the existing route permissions.
  • A backend release that includes operation activity. No dedicated SDK wrapper or new CLI command is introduced by this phase.

​
Workflow

1
GET the operation-activity collection for the selected resource.
2
Render current separately from history.items and deduplicate by id.
3
Refresh current state using the same IDs; follow an opaque history.next_cursor only when history is complete.
4
GET an exact activity ID when inspecting a retained record or following an authorized parent reference.

​
Read routes

All paths below are relative to /api/v1. Append /{activityID} to any collection for an exact read. Use the database route that matches its ownership context.

​
Collection response

The normal StackShift response envelope contains data.contract_version: 1, scope, observed_at, current, current_complete, history, availability and unresolved_references.
  • id is source_kind:source_record_UUID. Retain it across polling, reconnection and navigation. Build and deployment attempt IDs are distinct.
  • Each item includes resource/environment references, operation title/type, normalized status, original source.status, terminal evidence, current step, initiator, channel, executor, available timestamps, parents, related_resources, tasks and authorized read links.
  • Normalized states are queued, running, waiting, completed, failed, cancelled, rolled_back or unknown. Unknown terminal evidence is null; never convert it into success.
  • An environment marked resource_current describes the resource now, not a proven historical environment. Absent timestamps remain null.
  • history contains items, limit, complete, has_more and next_cursor. Current records are returned separately on each page.

​
Pagination and exact inspection

Collections accept limit from 1 to 100, default 25, and an opaque cursor. History is ordered by creation time descending, then canonical ID descending. Preserve fractional timestamp precision when ordering client-side. The cursor is bound to the viewer and selected resource; do not edit it or reuse it in another scope. A cursor bounds history creation time, not operation state or future access. Current operations can finish between reads. Refreshes can move records between current and history. Reauthorize retained records through exact reads when refreshing a previously loaded history window. Percent-encode the activity ID once in the path, for example build%3A50000000-0000-4000-8000-000000000001. Exact reads accept no pagination query. Existing activity, release, event and log routes remain compatible.

​
Incomplete sources and errors

  • availability.sources identifies each source, its role, and available, unavailable or not_applicable state. Inspect availability even after HTTP 200.
  • An unavailable operation source sets current_complete and history.complete false. History has_more and next_cursor are null, preventing false empty history or unsafe advancement.
  • Unavailable relationship or task enrichment can make availability.complete false while operation history remains complete. Do not infer that missing relationships never existed.
  • If every applicable operation source fails, the collection returns HTTP 503 with shaped partial data. A current-source limit is reported explicitly instead of silently hiding truncation.
  • Invalid query parameters, cursors or malformed activity IDs return 400. Missing or inaccessible resources/records return 404; authentication failures return 401 and existing token-scope restrictions can return 403. Authority/source infrastructure failures return 503.

​
Permissions and private tasks

The selected resource and every returned child resource are independently authorized. Application ownership does not grant access to a restricted service or database. Objective activity requires independent task access; resource access alone does not expose private tasks. Responses contain safe operational facts, not conversation text, prompts, secrets, raw controller payloads or billing details. These GET routes do not reconcile controllers, run a model or consume AI credits. Use the returned authorized links for detailed readers; do not manufacture routes from display labels.

​
Expected result

Consumers show current state, stable history and incomplete-source feedback without executing work.

Resource activity

Follow builds, deployments, releases and database operations from the resource you are working on.

Agent activity API

Read safe resource-scoped agent actions, approval capabilities and recorded authorization evidence.

Raw customer API command

Call an existing customer API path with bounded inputs, safe retries, downloads, and path restrictions.