Skip to main content
Fetch Workspace
Returns a single Workspace, filtered by the caller’s reach-visibility — a caller never sees a node their authority doesn’t reach. A caller with no user — anonymous, or a service key that names nobody — always gets 404.

Path Parameters

string
required
The workspace UUID.

Query Parameters

string
Include flags, as a comma-separated value or repeated params. The only value is memberCount: it adds the workspace’s direct member count as memberCount on the object. Matching ignores case; an unknown value returns 400 workspace/invalid-query.
string
Service keys only — the user to act as. Enforced: visibility resolves against the named user, so a key acting as someone with no relation to this workspace gets the same 404 that user would. Omit it and the key gets exactly the anonymous view: 404. actingUserId: "" or null is a 400, an attempt to name someone that names no one. A user token always acts as its own user and must not send it, and neither may a request with no credentials (400 workspace/acting-user-not-allowed). See Acting on behalf of a user.

Response

Returns the Workspace object, with reasons.
{ type, viaWorkspaceId? }[]
The caller’s full standing on the workspace, one entry per grant: owner, member, ancestor-owner (with the ancestor they own as viaWorkspaceId) and reach-holder (with the ancestor whose capability reaches here). The same entries, in the same order, as the authority read. A workspace is returned only when the caller has at least one, so it is never empty.

Error Responses

The workspace does not exist, or the caller (or the user named by actingUserId) has no relation to it. Always returned to an anonymous request and to a service key that names nobody.
Every path id on the workspaces bundle is checked for UUID shape before the route runs, so a malformed one is a plain 400 rather than a 500 from the database.
An include value outside memberCount. Matching ignores case.
A user token, or a request with no credentials, sent actingUserId, even naming its own user. Only a service key names the user it acts as; a user token always acts as its own user.
A GET takes every field, actingUserId included, in the query string, so any request body is refused: a JSON object with keys, a non-empty array, or a non-JSON payload such as multipart (then params is omitted). An absent body and {} pass.
Returned when a service key names an actingUserId that isn’t a user in this project.
See also: useFetchWorkspace