These docs are a work in progress and may not be fully up to date. Some pages may contain internal notes for our team.
Skip to Content

API — Workspaces

Workspace CRUD and member management. Workspace routes require auth:api, auth_session, audit, and subscription_tier:free middleware. The tier gate means only users on Free tier and above can access workspace endpoints — lower-tier accounts return 403.

💡 Tip: All users have one implicit default workspace. The workspace gate controls whether a user can list, create, or switch between multiple workspaces — not whether they can use the app at all.

Endpoints

GET /workspaces

List workspaces the authenticated user is a member of.

Response 200: Array of workspace objects { id, name, created_at, updated_at }.

GET /workspaces/{id}

Get a single workspace.

Response 200: Workspace object with member count.

POST /workspaces

Create a new workspace.

Body: { name }

Response 201: Created workspace.

⚠️ Warning: Plan limits on workspace count are enforced here. If the user has reached their plan’s workspace limit, the response is 403 with a plan upgrade message.

PUT /workspaces/{id}

Rename a workspace.

Body: { name }

Response 200: Updated workspace.

DELETE /workspaces/{id}

Delete a workspace. All resources (finders, locations, tags) belonging to the workspace are also deleted.

Response 204

⚠️ Warning: Workspace deletion is irreversible and cascades to all child resources. The dashboard requires an explicit confirmation step before calling this endpoint.

Member and invite management

Workspace invites are sent via the invite endpoint (requires role:admin):

  • POST /invite/send — send an invite email with a registration link (/register/{token})

Member management (adding/removing members from an existing workspace) is handled at the workspace level. 🔴 [NEEDS CLARIFICATION: Confirm whether a dedicated workspace member removal endpoint exists in routes/api.php, or whether member removal is only done via account deletion.]

Admin variants

Under role:admin + /admin/workspaces:

  • GET /admin/workspaces — list all workspaces across all users
  • POST /admin/workspaces, PUT /admin/workspaces/{workspace}, DELETE /admin/workspaces/{workspace} — admin CRUD
Concepts