Workspaces and collaboration API

A workspace is the primary collaboration and authorization boundary in Usable. Resolve the correct workspace and the caller's access before reading or changing fragments, collections, files, or settings.

Use GET /api/docs for exact schemas and route authentication in the deployed environment.

Workspace lifecycle

Released workspace routes include:

Example creation intent:

{
  "name": "Engineering knowledge",
  "description": "Maintained engineering standards and runbooks",
  "visibility": "private"
}

Treat archive/delete as a high-impact operation. Refetch the workspace and its dependent resources after completion.

Resolve the workspace first

Do not select a workspace by display name alone. Names are not durable identifiers.

A safe integration:

1. Lists accessible workspaces.
2. Matches a configured workspace ID.
3. Confirms name and visibility for operator clarity.
4. Checks the required role or token permission.
5. Performs the data-plane operation.
6. Records the stable ID, not a dashboard URL.

Never let a model or untrusted user switch workspace scope without authorization.

Public discovery and subscriptions

Public workspace routes include:

GET  /api/workspaces/discover
POST /api/workspaces/{id}/subscribe
POST /api/workspaces/{id}/unsubscribe

Discovery does not grant access to private workspace data. Subscription provides read-style access where configured and does not grant fragment creation, file upload, membership management, or settings changes.

Members and invitations

Released collaboration routes include:

The public invitation route accepts collaborator, contributor, and viewer roles where configured. Owner is not an invitation value on that route.

Apply least privilege, verify email and target workspace, and require human confirmation before removing members or broadening roles.

See Workspace members and invitations.

Fragment types

Fragment creation requires a valid fragment type ID from the target workspace. Resolve it before importing:

curl "https://usable.dev/api/workspaces/<workspace-id>/fragment-types" \
  -H "Authorization: Bearer <personal-access-token>"

Released type routes support list, create, get, update, and delete beneath /api/workspaces/{id}/fragment-types.

Do not reuse a type ID from another workspace or assume every workspace has the same custom types.

Workspace placement

POST /api/workspaces accepts optional hostedZoneId for released Hosted Zone placement. If omitted, creation remains Cloud-first. If present, the caller, organization tier, hosted zone, and placement status must satisfy the current contract.

Creation can return status: "processing" and placement metadata. Store the workspace ID and verify final state.

Cloud data-plane routes can return HOSTED_ZONE_REQUIRED when the workspace is Leaf-backed. Route private data to the released Leaf endpoint using the authorized token handoff; never silently fall back to Cloud.

Permissions before operations

Before changing workspace data, check:

• token permission and expiry;
• user's current workspace role;
• resource workspace ownership;
• route support for bearer versus browser-session auth;
• organization or tier gates;
• Hosted Zone placement.

A workspace ID supplied by a client is untrusted input.

Common failures

Workspace is listed but update returns 403

Read access does not imply settings or owner access. Check role and token scope.

Fragment type is rejected

Fetch types from the exact target workspace. The ID may belong elsewhere or have been removed.

Subscribe succeeds but writes fail

Subscription is intentionally read-style access.

Cloud route returns HOSTED_ZONE_REQUIRED

Use the workspace's released Hosted Zone routing information. Do not copy private payloads into a Cloud workspace as an automatic workaround.

Related pages

• Workspace roles and permissions
• Workspace members and invitations
• Fragments and search API
• Workspaces