Skip to main content
Fetch Mutual Workspaces
Returns a paginated list of the workspaces that both the caller and another user are in — their workspaces in common. Requires an authenticated user. Each row carries reasons: the caller’s standing on it.

Path Parameters

string
required
The other user’s Sublay ID. Mutual workspaces are computed between this user and the caller. An ID that matches no user returns an empty page. Your own ID returns your own workspaces, as List Workspaces would.

Query Parameters

string
What “in a workspace” means, for both users:
  • reachable (the default): each user can open the workspace, by any reason — owner, member, owner of an ancestor, or a capability that reaches down from an ancestor.
  • direct: each user owns the workspace or has a member row on it.
Left out or sent empty: reachable. Values match exactly. null and undefined are refused with 400 workspace/unsupported-param (see Saying “no value”); any other value returns 400 workspace/invalid-query.
string
The order, by creation time: desc (the default) newest first, asc oldest first, which lists every parent before its children. Rows created at the same moment are ordered by id in the same direction, so pages neither repeat nor skip a row.Left out or sent empty: desc. Case is ignored (DESC works). null and undefined are refused with 400 workspace/unsupported-param; any other value returns 400 workspace/invalid-query.
number
Page number. Defaults to 1.
number
Results per page. Defaults to 20.
string
Include flags, as a comma-separated value or repeated params. The only value is memberCount: it adds each workspace’s direct member count as memberCount. Matching ignores case; an unknown value returns 400 workspace/invalid-query.
string
Service key only, and required with one: the user this request acts as, whose workspaces are compared with the user in the path and whose reasons each row carries. A user token always acts as its own user and must not send it (400 workspace/acting-user-not-allowed).

Response

Workspace[]
The workspaces both users are in (Workspace). Each row’s reasons is the caller’s standing on it, the same entries the authority read returns; the other user’s standing isn’t included.
object
Standard pagination metadata (page, pageSize, totalPages, totalItems, hasMore).

Error Responses

Returned when userId isn’t a valid UUID. Checked before sign-in and the endpoint’s other checks.
A service key sent no actingUserId.
null and undefined as the value of relation or sortDir are rejected with code workspace/unsupported-param, naming the values to use instead. To use a default, leave the parameter out.
Returned with code workspace/invalid-query for an unknown include, relation or sortDir value, or a query parameter this route doesn’t declare (parentWorkspaceId included).
A user token 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.
Returned when a service key names an actingUserId that isn’t a user in this project.
See also: useFetchMutualWorkspaces