workspaces

Create a workspace

Mint a child workspace under a parent the caller may write in. parent_id defaults to the account's org_default root. name is the kebab-case machine handle and is also the marketplace plugin slug. A later rename changes that slug and orphans existing installs. Reach follows the tree the workspace lands in: the shared tree is org-discoverable, a personal tree is not.

post/registry/v1/workspaces

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
  • Auth: HTTP bearer

Headers

Content-Encoding'base64' | 'gzip, base64'

Codings applied to the request body, outermost last. Send base64, or gzip, base64 to compress first; the body is decoded before it is read and Content-Type still names the inner media type. Omit for an unencoded body.

Request body

descriptionstring nullable

Human-readable description.

display_namestring nullable

Optional; defaults to name.

namestring required

The kebab-case machine handle, at most 40 characters. Required — it is the marketplace plugin slug, so the caller chooses its initial value rather than receiving one minted from prose. A later PATCH may rename it.

parent_idstring nullable

Omitted nests at the account's org_default root.

visibilitystring nullable

public or private. Omitted inherits the parent's visibility — a child of a public parent defaults public, a child of a private parent defaults private. An explicit value more open than the parent is a 422: a child is never more open than its parent.

Response

Created

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.