Workspaces - Tell

Workspaces isolate your data — each workspace gets its own database, API keys, and team members. Use these endpoints to create and manage workspaces programmatically. All workspace endpoints require a JWT token in the Authorization header. See Authentication for details.

Create a workspace

Any authenticated user with Editor or higher role can create a workspace. You become the admin of the new workspace automatically.

curl -X POST https://your-tell-server/api/v1/user/workspaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "slug": "production"}'

The slug must be 1-50 characters, alphanumeric and hyphens only, and unique across all workspaces. Returns:

{
  "id": "ws_abc123",
  "name": "Production",
  "slug": "production",
  "created_at": "2025-03-15T10:00:00Z",
  "updated_at": "2025-03-15T10:00:00Z"
}

List your workspaces

curl https://your-tell-server/api/v1/user/workspaces \
  -H "Authorization: Bearer $TOKEN"

Returns all workspaces you’re a member of.

Admin endpoints

Workspace admins and platform users have access to additional management endpoints. These require the X-Workspace-ID header.

List all workspaces (Platform only)

curl https://your-tell-server/api/v1/admin/workspaces \
  -H "Authorization: Bearer $TOKEN"

Get workspace details

curl https://your-tell-server/api/v1/admin/workspaces/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

Update workspace name

curl -X PUT https://your-tell-server/api/v1/admin/workspaces/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Analytics"}'

Delete workspace (Platform only)

curl -X DELETE https://your-tell-server/api/v1/admin/workspaces/{id} \
  -H "Authorization: Bearer $TOKEN"

This permanently deletes the workspace and all its data. Platform role required.

Invitations

Admins can invite users to a workspace by email. Invitations are assigned a role and expire after 7 days.

Invite a user

curl -X POST https://your-tell-server/api/v1/admin/workspace/invites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "teammate@example.com", "workspace_id": "ws_abc123", "role": "editor"}'

The response includes an invite_url you can share with the invited user.

List pending invites

curl "https://your-tell-server/api/v1/admin/workspace/invites?workspace_id=ws_abc123&status=pending" \
  -H "Authorization: Bearer $TOKEN"

Cancel an invite

curl -X DELETE "https://your-tell-server/api/v1/admin/workspace/invites/{invite-id}?workspace_id=ws_abc123" \
  -H "Authorization: Bearer $TOKEN"

Accept an invite (no auth required)

Invited users visit the invite URL to verify and accept:

# Verify the invite
curl https://your-tell-server/api/v1/invites/{token}

# Accept it
curl -X POST https://your-tell-server/api/v1/invites/{token}/accept \
  -H "Content-Type: application/json" \
  -d '{"email": "teammate@example.com", "password": "their-password"}'

New users are created automatically when accepting an invite.

User management

Admins can manage users in their workspace. You can’t assign a role higher than your own.

# List users
curl "https://your-tell-server/api/v1/admin/users?limit=50" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

# Create a user
curl -X POST https://your-tell-server/api/v1/admin/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "password": "secure-password", "role": "editor"}'

# Update a user's role
curl -X PUT https://your-tell-server/api/v1/admin/users/{user-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

# Delete a user
curl -X DELETE https://your-tell-server/api/v1/admin/users/{user-id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: ws_abc123"

User list filters

Parameter	Description
`email`	Filter by email (partial match)
`role`	Filter by role
`limit`	Max results (default 100)
`offset`	Pagination offset

Error responses

All endpoints return consistent error JSON:

{
  "error": "VALIDATION_ERROR",
  "message": "Slug already taken"
}

Code	Status	Meaning
`UNAUTHORIZED`	401	Missing or invalid token
`FORBIDDEN`	403	Insufficient role
`NOT_FOUND`	404	Workspace doesn’t exist
`CONFLICT`	409	Slug already taken
`VALIDATION_ERROR`	422	Invalid input

What’s next

Workspaces & Teams — operational guide for workspace management
Roles & Permissions — what each role can do
Authentication — tokens and login flow

API Reference

Documentation Index

​Create a workspace

​List your workspaces

​Admin endpoints

​List all workspaces (Platform only)

​Get workspace details

​Update workspace name

​Delete workspace (Platform only)

​Invitations

​Invite a user

​List pending invites

​Cancel an invite

​Accept an invite (no auth required)

​User management

​User list filters

​Error responses

​What’s next