# API Reference

Base URL: `http://localhost:3000/api/v1`

---

## Users

| Method | Path | Description |
|--------|------|-------------|
| GET | `/users` | List all users |
| POST | `/users` | Create a user |
| GET | `/users/{id}` | Get a user |
| PUT | `/users/{id}` | Update a user (display_name, avatar_url, bio) |
| DELETE | `/users/{id}` | Soft-delete a user |

**POST /users — body**
```json
{
  "email": "user@example.com",
  "password_hash": "...",
  "username": "jane",
  "display_name": "Jane",
  "avatar_url": null,
  "bio": null,
  "email_verified": false
}
```

---

## Auth Tokens

| Method | Path | Description |
|--------|------|-------------|
| GET | `/users/{id}/auth-tokens` | List tokens for a user |
| POST | `/auth-tokens` | Create a token |
| DELETE | `/auth-tokens/{id}` | Revoke a token |

**POST /auth-tokens — body**
```json
{
  "user_id": "uuid",
  "kind": "refresh_token",
  "expires_at": "2026-09-01T00:00:00Z"
}
```
`kind`: `password_reset` | `email_verification` | `refresh_token`

**POST /auth-tokens — response** includes `token` (raw value) and `record`.

---

## Workspaces

| Method | Path | Description |
|--------|------|-------------|
| GET | `/workspaces` | List all workspaces |
| POST | `/workspaces` | Create a workspace |
| GET | `/workspaces/{id}` | Get a workspace |
| PUT | `/workspaces/{id}` | Update a workspace (name, slug) |
| DELETE | `/workspaces/{id}` | Soft-delete a workspace |

**POST /workspaces — body**
```json
{
  "name": "Acme",
  "slug": "acme",
  "owner_id": "uuid"
}
```

---

## Workspace Members

| Method | Path | Description |
|--------|------|-------------|
| GET | `/workspaces/{id}/members` | List members |
| POST | `/workspaces/{id}/members` | Add a member |
| PUT | `/workspaces/{workspace_id}/members/{user_id}` | Update role / display name |
| DELETE | `/workspaces/{workspace_id}/members/{user_id}` | Remove a member |

**POST body**
```json
{
  "user_id": "uuid",
  "role": "member",
  "display_name": null,
  "avatar_url": null
}
```
`role`: `owner` | `admin` | `member`

---

## Workspace Invitations

| Method | Path | Description |
|--------|------|-------------|
| GET | `/workspaces/{id}/invitations` | List invitations |
| POST | `/workspaces/{id}/invitations` | Create an invitation |
| DELETE | `/invitations/{id}` | Delete an invitation |

**POST body**
```json
{
  "created_by": "uuid",
  "max_uses": 10,
  "expires_at": "2026-09-01T00:00:00Z"
}
```
`max_uses` and `expires_at` are optional. The invite `token` is generated server-side.

---

## Conversations

| Method | Path | Description |
|--------|------|-------------|
| GET | `/conversations` | List conversations (`?workspace_id=uuid`) |
| POST | `/conversations` | Create a conversation |
| GET | `/conversations/{id}` | Get a conversation |
| PUT | `/conversations/{id}` | Update a conversation (name, is_public) |
| DELETE | `/conversations/{id}` | Soft-delete a conversation |

**POST body**
```json
{
  "workspace_id": "uuid",
  "kind": "channel",
  "name": "general",
  "is_public": true,
  "created_by": "uuid"
}
```
`kind`: `dm` | `group` | `channel`
`workspace_id` is optional (null for DMs).

---

## Conversation Members

| Method | Path | Description |
|--------|------|-------------|
| GET | `/conversations/{id}/members` | List members |
| POST | `/conversations/{id}/members` | Add a member |
| DELETE | `/conversations/{conversation_id}/members/{user_id}` | Remove a member |

**POST body**
```json
{
  "user_id": "uuid"
}
```

---

## Messages

| Method | Path | Description |
|--------|------|-------------|
| GET | `/conversations/{id}/messages` | List messages (chronological) |
| POST | `/messages` | Send a message |
| GET | `/messages/{id}` | Get a message |
| PUT | `/messages/{id}` | Edit a message (content) |
| DELETE | `/messages/{id}` | Soft-delete a message |

**POST body**
```json
{
  "conversation_id": "uuid",
  "user_id": "uuid",
  "content": "Hello!"
}
```

---

## Attachments

| Method | Path | Description |
|--------|------|-------------|
| GET | `/messages/{id}/attachments` | List attachments for a message |
| POST | `/attachments` | Create an attachment |
| DELETE | `/attachments/{id}` | Delete an attachment |

**POST body**
```json
{
  "message_id": "uuid",
  "url": "https://...",
  "filename": "file.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 102400
}
```

---

## Reactions

| Method | Path | Description |
|--------|------|-------------|
| GET | `/messages/{id}/reactions` | List reactions for a message |
| POST | `/reactions` | Add a reaction |
| DELETE | `/reactions/{id}` | Remove a reaction |

**POST body**
```json
{
  "message_id": "uuid",
  "user_id": "uuid",
  "emoji": "👍"
}
```

---

## Response conventions

| Status | Meaning |
|--------|---------|
| 200 | OK |
| 201 | Created |
| 204 | Deleted (no body) |
| 404 | Not found |
| 500 | Internal server error (body: error string) |

Soft-deleted resources (`users`, `workspaces`, `conversations`, `messages`) are excluded from all list/get responses.