get_workspace

This page answers what get_workspace returns, what it takes, and how it fails.

Purpose

get_workspace returns the workspace exactly as it is stored: every collection and every field, unedited, including warm-query text and pending proposal groups. Secrets appear only as $secret:<key> references, never as values, and minted tokens are left out. It reads the workspace fresh on every call and changes nothing.

Inputs

Input	Type	Meaning
kinds	list of text	Keep only these top-level collections, such as ["WarmQueries", "DataConnections"]. Omit it for the whole workspace.
includeGuides	true or false	Also return each kind's guide, schema and examples. Default false.

Example

{ "kinds": ["DatabaseTables"], "includeGuides": true }

The answer

Part	What it holds
EaC	The workspace as stored, or the collections kinds kept. The workspace's own name and details are always kept
Capabilities	What can be built in this workspace now, below
Secrets	ClearFields: the paths of any credential still stored in clear, which reads as a placeholder. Names only, never a value; empty is the norm
Diagnostics	EaCLoad, LoadedAt, and EmptyKinds for a known collection with no records

Capabilities

Field	What it holds
ActiveKinds	The kinds that are on in this workspace
MenuKinds	The active kinds that have a window in the workspace menu, with its label
Kinds	Per active kind, where its guide, schema and examples are: its prompt id, its schema/<kind> resource and its example resources. With includeGuides: true, also the Guide, Schema and Examples themselves
InactiveKinds	Each kind that is not on yet, once, with its Code, Reason, Remedy and, where there is one, Requires

Requires lists the record kinds the workspace still lacks, in the order they are set up. A kind that needs the private landing zone, in a workspace with no cloud connected yet, reads:

{
  "Kind": "Provenance",
  "Code": "PRIVATE_LANDING_ZONE_REQUIRED",
  "Reason": "This needs a private landing zone, which this workspace does not have yet.",
  "Remedy": "Connect a cloud from Environment → Cloud Connections, then create your private landing zone from Environment → Manage Private CALZ.",
  "Requires": ["Clouds", "CALZ"]
}

With a cloud connected, Requires is ["CALZ"]. The landing zone itself is listed the same way until a cloud is connected: CLOUD_CONNECTION_REQUIRED, with Requires ["Clouds"]. The order is on Environment.

Clouds is on in every workspace, and CALZ once a cloud is connected; both can be proposed like any other kind (see manage_proposals). Until a kind is on or has a stored record, naming it in kinds is refused as unknown, as for any kind.

If the capability list could not be built, Capabilities is left out and Diagnostics.Void is true with a Reason; the EaC is still the workspace as stored.

Errors

• An unknown name in kinds is refused (UNKNOWN_KINDS) with the list of valid names, and nothing is returned.
• If Diagnostics.EaCLoad is not "ok", the answer holds no workspace: the workspace was not read, which is not the same as an empty workspace. "refused" means the read was refused (401 or 403); "error" means it failed. Try again, or check the connection.