231 lines
4.9 KiB
Markdown
231 lines
4.9 KiB
Markdown
# 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.
|