likwid/docs/reference/api.md

# API Reference

Likwid exposes a REST API for all functionality.

## Base URL

```
http://localhost:3000/api
```

## Authentication

Most endpoints require a JWT token:

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/api/...
```

### Login

```http
POST /api/auth/login
Content-Type: application/json

{
  "username": "user",
  "password": "password"
}
```

Response:
```json
{
  "token": "eyJ...",
  "user": {
    "id": "uuid",
    "username": "user",
    "display_name": "User Name"
  }
}
```

### Register

```http
POST /api/auth/register
Content-Type: application/json

{
  "username": "newuser",
  "email": "user@example.com",
  "password": "password",
  "display_name": "New User"
}
```

## Communities

### List Communities

```http
GET /api/communities
```

### Get Community

```http
GET /api/communities/{id}
```

### Create Community

```http
POST /api/communities
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "name": "My Community",
  "slug": "my-community",
  "description": "Description here"
}
```

### Join Community

```http
POST /api/communities/{id}/join
Authorization: Bearer TOKEN
```

### Leave Community

```http
POST /api/communities/{id}/leave
Authorization: Bearer TOKEN
```

## Proposals

### List Proposals

```http
GET /api/communities/{id}/proposals
```

### Get Proposal

```http
GET /api/proposals/{id}
```

### Create Proposal

```http
POST /api/communities/{id}/proposals
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "title": "Proposal Title",
  "description": "Full description",
  "voting_method": "approval",
  "options": [
    {"label": "Option A", "description": "..."},
    {"label": "Option B", "description": "..."}
  ]
}
```

### Vote

```http
POST /api/proposals/{id}/vote
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "option_ids": ["uuid1", "uuid2"]
}
```

### Vote (Ranked)

```http
POST /api/proposals/{id}/vote/ranked
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "rankings": [
    {"option_id": "uuid1", "rank": 1},
    {"option_id": "uuid2", "rank": 2}
  ]
}
```

### Vote (Quadratic)

```http
POST /api/proposals/{id}/vote/quadratic
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "allocations": {
    "uuid1": 5,
    "uuid2": 3
  }
}
```

## Delegations

### List Delegations

```http
GET /api/delegations
Authorization: Bearer TOKEN
```

### Create Delegation

```http
POST /api/delegations
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "delegate_id": "user-uuid",
  "community_id": "community-uuid",
  "scope": "topic",
  "topic_id": "topic-uuid"
}
```

### Revoke Delegation

```http
DELETE /api/delegations/{id}
Authorization: Bearer TOKEN
```

## Users

### Get Current User

```http
GET /api/users/me
Authorization: Bearer TOKEN
```

### Update Profile

```http
PUT /api/users/me
Authorization: Bearer TOKEN
Content-Type: application/json

{
  "display_name": "New Name",
  "bio": "Updated bio"
}
```

## Demo Endpoints

### Demo Status

```http
GET /api/demo/status
```

### Reset Demo (Admin)

```http
POST /api/demo/reset
Authorization: Bearer TOKEN
```

## Error Responses

```json
{
  "error": "Error message",
  "code": "ERROR_CODE"
}
```

Common status codes:
- `400` - Bad request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not found
- `422` - Validation error
- `500` - Server error