workspaces

Get a workspace

One workspace by handle. Workspace metadata uses discover, the same permission as the list. Reading artifacts, exports, or roster identities inside the workspace still requires read. 404 and 403 are distinguishable here: an absent or deleted workspace is 404, while an existing but undiscoverable workspace is 403.

include=artifact_counts attaches this workspace's artifact_count and its per-kind artifact_count_by_kind breakdown, taken under the same discover the row itself was read at, so it is served even to a caller who has not joined. It counts what POST /aggregate counts, so the number does not change on joining.

include=permissions attaches the caller's advisory can_* capability matrix. Advisory only — a UI gates controls on it; it never authorizes a request.

get/registry/v1/workspaces/{workspace_id}

Request

  • Base URL: https://api.atlan.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.atlan.com/registry/v1/workspaces/{workspace_id}
  • Auth: HTTP bearer

Path parameters

workspace_idstring required

Workspace handle (workspace_…) or the workspace's kebab-case name. The two grammars are disjoint, so no disambiguation is needed. A name is mutable — a display_name edit re-derives it — so a client that stores an address should store the handle, which every response echoes.

Query parameters

includestring

Opt-in embeds, comma-separated. artifact_counts embeds the workspace's artifact volume by kind and in total; permissions embeds the caller's advisory can_* capability matrix.

Headers

X-Atlan-Consistency-Tokenstring nullable

Optional read-your-own-writes token. Echo the X-Atlan-Consistency-Token a recent write returned, and this read is pinned to at least that revision so it sees your own change instead of a stale replica. Omit it for the fastest read. An unrecognised token is ignored and the read still succeeds.

Response

OK

artifact_countinteger nullable

How many artifacts this workspace holds, and only when include=artifact_counts asked for it — then on every row of the page, 0 included.

The discover-band count the pre-Postgres stack served unconditionally and the cutover dropped: it is the affordance that lets someone decide whether a workspace is worth joining, and its absence made every unjoined row read "0 skills". The inverse of member_count's absent-rather-than-zero rule, and deliberately so — a roster size is unknowable at discover, an artifact count is not, because it names nobody (registry_tenancy::workspace::artifact_counts).

artifact_count_by_kindobject nullable

The per-kind breakdown of [Self::artifact_count], which it sums to. Attached and absent with it, always — two fields, one embed, so a client never sees a total it cannot explain.

A kind with no artifacts here is absent rather than 0: the map is what the workspace holds, not the kind registry. A BTreeMap, so the key order is stable across responses.

created_atstring required

Value of the created_at field.

created_bystring required

Value of the created_by field.

descriptionstring nullable

Human-readable description.

display_namestring required

Human-readable name.

idstring required

Stable identifier of this resource.

kindstring required

Domain discriminator for this resource.

member_countinteger nullable

Roster size, and only when include=member_count asked for it.

Absent rather than 0 when unrequested, so a client cannot read a missing embed as an empty workspace. Also absent for a workspace the caller can discover but not read: the count is taken under a Read receipt on the membership rows while this list runs under Discover, so a headcount is never a thing discovery alone reveals (registry_tenancy::workspace::member_counts).

namestring required

Stable machine-readable name.

org_wideboolean required

Whether this workspace sits in the account's shared tree, and so is org-discoverable and self-joinable.

Derived from the tree root, never stored, so a reparent moves it with the row. Not a published field upstream — it is this stack's convenience — but it has to be right, and it was not: the previous derivation was root_workspace_id != id || kind == OrgDefault, which is true for every non-root workspace, including every child of a personal tree. A workspace inside someone's private space rendered as org-wide.

parent_idstring nullable

None for a singleton, which is a tree root.

permissionsGatewayCapabilityMatrix

The caller's advisory can_* capability matrix on a resource.

Advisory only: it reflects what the caller may do, and is for a UI to gate controls on. It never authorizes a request — the platform decides that independently on every call.

Deliberately an open map rather than a typed struct. The authoritative permission tables are internal to the platform core, and lifting them into the SDK would put an authorization decision surface into every extension. An extension reads this matrix; it never derives one.

root_workspace_idstring required

Stable identifier of the related root workspace resource.

updated_atstring required

Value of the updated_at field.

updated_bystring required

Value of the updated_by field.

visibilitystring required

public or private — how open this shared-tree workspace is: whether the account can list it and self-join it. Meaningful only when org_wide is true; a personal-tree workspace is always private. Set on create (inherits the parent when omitted) and changed by PATCH /workspaces/{id}/visibility.

workspace_statusstring required

The lifecycle state.

workspace_status, not status: it is the published spelling, and it is the name the filter grammar already uses (registry_model::workspace::Entity's Field is workspace_status). Serving status while accepting filter[workspace_status] meant a client read a field it could not filter on.

Changes

No recorded changes to this operation across all 1 revision of this API.