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 the workspaces you’re a member of as a list response:

{
  "items": [
    { "id": "ws_abc123", "name": "Production", "slug": "production" }
  ],
  "total": 1,
  "limit": 200,
  "offset": 0,
  "has_more": false
}

The default page size is 200.

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"

Returns a list response with workspaces in items. The default page size is 200.

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"

Returns a list response with invites in items.

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`	Page size (default 50, max 200)
`offset`	Rows to skip

The response is a list response with users in items and the number of matching users in total.

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

​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