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

# Workspace Session API

> Session-authenticated workspace collaboration endpoints used by the dashboard

# Workspace Session API

These endpoints are under `/api` (session cookie auth), not `/api/v1` (API token auth).

<Note>
  Use these routes from authenticated dashboard clients with `credentials: "include"`.
</Note>

## Create Workspace (Session)

```
POST /api/workspaces
```

Creates a workspace for the logged-in user with server-side plan enforcement.

### Request Body

```json theme={null}
{
  "name": "Design System",
  "description": "Main product workspace",
  "include_in_organization": true
}
```

### Notes

* `include_in_organization` is optional (default `false`).
* If `include_in_organization=true`, caller must have Organizations feature access and at least one organization.
* Owner membership is created automatically.

## List Workspace Members

```
GET /api/workspaces/{workspaceId}/members
```

Returns current members and profile info.

### Response (200)

```json theme={null}
{
  "members": [
    {
      "id": "membership-id",
      "workspace_id": "workspace-id",
      "user_id": "user-id",
      "role": "owner",
      "user_email": "owner@company.com",
      "user_name": "Owner Name"
    }
  ],
  "invitations": []
}
```

`invitations` is kept as an empty array for backward compatibility.

## Add/Update Member Immediately

```
POST /api/workspaces/{workspaceId}/members
```

Adds a member directly (no pending invitation, no email flow).

### Request Body

```json theme={null}
{
  "email": "member@company.com",
  "role": "editor"
}
```

### Behavior

* Requires workspace permission to manage members.
* Email must match an existing profile account.
* If user is already a member, role is updated.
* Plan limits are enforced on add.

### Responses

* `201` member added
* `200` role updated
* `404` user email not found
* `403` permission or plan limit blocked

## Deprecated Invitation Link Endpoints

Legacy invitation-link endpoints are deprecated and return `410 Gone`:

* `POST /api/workspaces/invitations/accept`
* `GET /api/workspaces/invitations/verify`
* `DELETE /api/workspaces/invitations/{id}`

### Deprecated Response

```json theme={null}
{
  "error": "Workspace invitation links are deprecated. Members are now added instantly from workspace settings."
}
```

## Downgrade Status (Session)

```
GET /api/subscription/downgrade-status
```

Returns post-downgrade overage state used by the global warning banner.

### Response (200)

```json theme={null}
{
  "plan_type": "PRO",
  "has_overages": true,
  "overages": [
    { "type": "workspaces", "current": 4, "limit": 3 }
  ],
  "enforcement": {
    "can_create_workspace": false,
    "can_invite_members": true,
    "can_access_organizations": false
  }
}
```