# createHostedQuickstart `POST /apis/cra.diagrid.io/v1beta1/projects/{ProjectId}/hosted-quickstarts` Start a hosted quickstart session. One per organization at a time; the caller becomes its owner, taken from `x-diagrid-user-email`, and a request without that header is refused. ## Request ### Path parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `ProjectId` | string | Yes | Unique identifier of the project. | ### Request body The journey and contract version to run. `application/json` 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) - `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) — 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) ## Responses ### 202 — Session accepted and provisioning. No body: the caller names the session itself in `metadata.name`, and reads it back with a describe. ### 400 — Refused, with a machine-readable reason. `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`. ### 409 — Another session holds the organization's lock (`session_lock_held`). `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`. ### 503 — Not available yet — `region_not_ready`, `feature_not_ready`, or no selectable contract version. `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.