# createHostedQuickstartOperation

`POST /apis/cra.diagrid.io/v1beta1/projects/{ProjectId}/hosted-quickstarts/{HostedQuickstartId}/operations`

Run one step of the session's contract. The owner only.
The request must carry the session `statusVersion` the caller was acting on. That is what makes two tabs, or a retry racing a runner report, resolve safely rather than both proceeding from different pictures of the same session.
Idempotent on the operation name: replaying a name already recorded returns the existing operation rather than starting a second run of the step. A name belonging to a DIFFERENT session in the same project is refused instead, since a replay is only a replay within one session.

## Request

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `ProjectId` | string | Yes | Unique identifier of the project. |
| `HostedQuickstartId` | string | Yes | Name of the hosted quickstart. |

### Request body

The step to run, and the status version it was chosen against.

`application/json`

One attempt at one step of a session's contract. Created by the console when the user presses Run, and reported on by the runner until it reaches a terminal phase.

- `apiVersion` (string)
- `kind` (string)
- `metadata` (object)
  - `name` (string)
  - `uid` (string)
  - `resourceVersion` (integer)
  - `createdAt` (string)
  - `updatedAt` (string)
  - `deletedAt` (string)
  - `labels` (object<string, string>)
  - `annotations` (object)
- `spec` (object) — Required.
  - `stepId` (string) — Required. The step to run, which must exist in the session's PINNED contract version. A step this binary does not recognise is refused with 422 and `reason: reload_required`, because retrying cannot help.
  - `sessionUid` (string) — The session this operation belongs to. Operations are namespaced by project and a project can outlive several sessions, so a replayed idempotency key is only a replay within one session.
  - `observedStatusVersion` (integer (int64)) — Required. The session `statusVersion` the caller was acting on. A stale value is refused with 409 and the current session snapshot, so the caller can re-render and retry.
  - `appIdName` (string) — Optional name for the App ID the identity step creates. Supplied by the user rather than chosen by the control plane.
- `status` (object)
  - `phase` (string) — One of: `accepted`, `running`, `succeeded`, `failed`, `unknown`.
  - `message` (string) — Why a step failed, when the runner could say.

## Responses

### 201 — Accepted; the step is in flight.

`application/json`

One attempt at one step of a session's contract. Created by the console when the user presses Run, and reported on by the runner until it reaches a terminal phase.

- `apiVersion` (string)
- `kind` (string)
- `metadata` (object)
  - `name` (string)
  - `uid` (string)
  - `resourceVersion` (integer)
  - `createdAt` (string)
  - `updatedAt` (string)
  - `deletedAt` (string)
  - `labels` (object<string, string>)
  - `annotations` (object)
- `spec` (object) — Required.
  - `stepId` (string) — Required. The step to run, which must exist in the session's PINNED contract version. A step this binary does not recognise is refused with 422 and `reason: reload_required`, because retrying cannot help.
  - `sessionUid` (string) — The session this operation belongs to. Operations are namespaced by project and a project can outlive several sessions, so a replayed idempotency key is only a replay within one session.
  - `observedStatusVersion` (integer (int64)) — Required. The session `statusVersion` the caller was acting on. A stale value is refused with 409 and the current session snapshot, so the caller can re-render and retry.
  - `appIdName` (string) — Optional name for the App ID the identity step creates. Supplied by the user rather than chosen by the control plane.
- `status` (object)
  - `phase` (string) — One of: `accepted`, `running`, `succeeded`, `failed`, `unknown`.
  - `message` (string) — Why a step failed, when the runner could say.

### 403 — Not the session's owner.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 404 — No such session.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 409 — `observedStatusVersion` is stale, or the operation name is taken by another session. The stale case carries the current session so the caller can re-render and retry.

`application/json`

The 409 answering an operation create whose `observedStatusVersion` is stale — two tabs, or a retry racing a runner report. Distinguished from the other 409 (the organization lock) by carrying a `session` and no `reason`. The snapshot is the point: the caller re-renders from it and retries with the version it now holds, rather than being told only that it lost.

- `error` (string)
- `session` (object) — Required. A hosted quickstart run (RFC 0034). One session per organization at a time, owned by the user who created it, holding the runner it provisions and the per-step state the console renders.
  - `apiVersion` (string)
  - `kind` (string)
  - `metadata` (object)
    - `name` (string)
    - `uid` (string)
    - `resourceVersion` (integer)
    - `createdAt` (string)
    - `updatedAt` (string)
    - `deletedAt` (string)
    - `labels` (object<string, string>)
    - `annotations` (object)
    - `statusVersion` (integer (int64)) — Read-only. Monotonic version of the session's status. A stale value in an operation create is refused with 409, so two tabs cannot act on different pictures of the same session.
  - `spec` (object) — Required.
    - `projectId` (string) — Read-only. The project the session and its resources live in. Server-set from the request path; a value in the body is ignored.
    - `journey` (string) — Required. Which guided journey this session runs.
    - `quickstartPath` (string) — Required. The sample in catalyst-quickstarts this session runs — a PATH within that repository, not a display name.
    - `manifestVersion` (string) — Required. The execution contract version this session is pinned to, for its whole life. A session runs the contract it agreed to at creation, never a later edit of it.
    - `owner` (string) — Read-only. Email of the user who created the session, taken from `x-diagrid-user-email` on create. Checked against the caller on delete, `:resume`, `:heartbeat` and operation create.
  - `status` (object)
    - `state` (string) — Suspended is reached by the user lease expiring; the session is resumable from it via `:resume`. One of: `Provisioning`, `Active`, `Suspended`, `Failed`, `Deleting`.
    - `runnerAppId` (string) — The App ID the runner registers as.
    - `workflowInstanceId` (string) — The durable workflow instance the session's clean run uses, once one exists. That run is allowed to finish, so the reader sees a graph read as ordinary before anything is crashed.
    - `crashWorkflowInstanceId` (string) — The durable workflow instance the session's crashed run uses, once one exists. A second instance rather than a re-run of the first: the crash step starts it and kills the worker part way through it, and the recover step attaches to this one. Written in the same update as `workflowInstanceId`, so a session carries both or neither.
    - `activeOperationId` (string) — The operation currently in flight, if any. Only a non-terminal operation occupies it; an index left pointing at a finished one would block suspension for the session's life.
    - `resources` (object<string, object>) — The resources this session created, keyed by the contract's role id (`app` is the sample App ID). The console reads the App ID's name from here rather than from a field of its own, because the contract can name more roles than the console renders.
      - `kind` (string)
      - `name` (string)
      - `uid` (string)
    - `deleteResources` (boolean) — Whether ending this session also deletes the resources in `resources`. Set when the owner's own delete asks for it, and always set when a session is cancelled by an administrator or ended for inactivity. False means they stay in the project.
    - `runner` (object) — What the runner container itself last reported. Absent until it has reported, which is what holds a session in Provisioning rather than activating it unverified.
      - `ready` (boolean) — The runner's own readiness at the moment it reported: whether it would accept an operation. Not the same as the runner App ID's regional readiness, which provisioning checks separately.
      - `executionManifestHash` (string) — The contract hash embedded in the runner image. Provisioning fails closed when it does not match the hash the control plane expects for the pinned version.
      - `streamEpoch` (string) — Identifies the runner's current event stream. A client resuming with a cursor from a previous epoch must refetch rather than resume, because sequence numbers do not carry across epochs.
    - `userLeaseExpires` (string (date-time)) — When the session suspends itself unless `:heartbeat` renews it.
    - `suspendedAt` (string (date-time))
    - `steps` (object[]) — Per-step state, keyed by the contract's step ids.
      - `stepId` (string) — Required.
      - `phase` (string) — Required. `unknown` is a step recorded as running that is not safe to repeat; the runner does not guess. One of: `accepted`, `running`, `succeeded`, `failed`, `unknown`.
      - `operationId` (string)
      - `message` (string)

### 422 — The step id is not in the session's pinned contract (`reason: reload_required`). This client is behind the control plane, so a retry with a fresh status version cannot help — only a reload can.

`application/json`

A refusal carrying a machine-readable code, so a client can name the specific remedy rather than printing a generic failure. The code arrives on whichever status its guard chose — 400 for a bad request, 409 for the organization lock, 503 for something not ready yet — so it is the presence of `reason`, not the status, that identifies a refusal. Only `error` and `reason` cross the control-plane boundary; anything else in the upstream body is dropped rather than relayed.

- `error` (string) — A sentence for the user.
- `reason` (string) — Required. `session_lock_held` — another session holds the organization's lock; an admin can cancel it. `project_not_empty` — a sandbox needs an empty project. `region_not_public` — the project's region cannot host a sandbox. `region_not_ready` / `feature_not_ready` — not yet available; only patience helps. `feature_not_enabled` — switched off for the organization. `quota_exceeded` — the region has no room. `contract_not_selectable` — no selectable contract version, which is the state every environment but OneBox is in. `reload_required` — the step id is absent from the session's pinned contract, so this client is behind the control plane. One of: `session_lock_held`, `project_not_empty`, `region_not_public`, `region_not_ready`, `feature_not_enabled`, `feature_not_ready`, `quota_exceeded`, `contract_not_selectable`, `reload_required`.

### default — Unexpected error.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.