> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tell.rs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Create, list, and manage workspaces via the API.

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](/api/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.

```bash theme={null}
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:

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

## List your workspaces

```bash theme={null}
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)

```bash theme={null}
curl https://your-tell-server/api/v1/admin/workspaces \
  -H "Authorization: Bearer $TOKEN"
```

### Get workspace details

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

### Update workspace name

```bash theme={null}
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)

```bash theme={null}
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

```bash theme={null}
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

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

### Cancel an invite

```bash theme={null}
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:

```bash theme={null}
# 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.

```bash theme={null}
# 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:

```json theme={null}
{
  "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](/running-tell/workspaces) — operational guide for workspace management
* [Roles & Permissions](/running-tell/roles) — what each role can do
* [Authentication](/api/authentication) — tokens and login flow