# TaskFlow API Documentation

## Base URL

```
Development: http://localhost:3000/api/v1
Production:  https://api.taskflow.example.com/api/v1
```

## Authentication

All endpoints except `/users/register` and `/users/login` require a Bearer token in the `Authorization` header:

```
Authorization: Bearer <token>
```

## Endpoints

### Users

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| POST | `/users/register` | Register new user | No |
| POST | `/users/login` | Login and get token | No |
| GET | `/users/me` | Get current user profile | Yes |
| PUT | `/users/me` | Update current user profile | Yes |
| GET | `/users` | List all users | Admin/Manager |

#### POST /users/register

```json
// Request
{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "securePass123",
  "displayName": "John Doe"
}

// Response 201
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "johndoe",
  "email": "john@example.com",
  "displayName": "John Doe",
  "role": "member",
  "createdAt": "2026-06-12T10:00:00Z"
}
```

#### POST /users/login

```json
// Request
{
  "email": "john@example.com",
  "password": "securePass123"
}

// Response 200
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "email": "john@example.com",
    "role": "member"
  }
}
```

### Tasks

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/tasks` | List tasks (paginated) | Yes |
| GET | `/tasks/:id` | Get task detail | Yes |
| POST | `/tasks` | Create task | Yes |
| PUT | `/tasks/:id` | Update task | Yes |
| DELETE | `/tasks/:id` | Delete task | Yes |
| POST | `/tasks/:id/comments` | Add comment to task | Yes |

#### GET /tasks

Query parameters:
- `page` (default: 1)
- `limit` (default: 20, max: 100)
- `status` - filter by status: `todo`, `in_progress`, `in_review`, `done`
- `priority` - filter by priority: `low`, `medium`, `high`, `urgent`
- `projectId` - filter by project
- `assigneeId` - filter by assignee
- `sortBy` - sort field: `createdAt`, `updatedAt`, `dueDate`, `priority`
- `sortOrder` - sort direction: `asc`, `desc`

```json
// Response 200
{
  "items": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "title": "Implement user dashboard",
      "description": "Create the main dashboard view",
      "status": "in_progress",
      "priority": "high",
      "assignee": { "id": "...", "username": "johndoe", "displayName": "John Doe" },
      "creator": { "id": "...", "username": "admin", "displayName": "Admin" },
      "tags": [{ "name": "frontend", "color": "#42b883" }],
      "dueDate": "2026-06-20T00:00:00Z",
      "estimatedHours": 16,
      "actualHours": 8,
      "createdAt": "2026-06-10T08:00:00Z",
      "updatedAt": "2026-06-12T09:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "totalPages": 3
}
```

#### POST /tasks

```json
// Request
{
  "title": "Fix login redirect bug",
  "description": "Users are not redirected after login on mobile browsers",
  "priority": "high",
  "projectId": "770e8400-e29b-41d4-a716-446655440002",
  "assigneeId": "550e8400-e29b-41d4-a716-446655440000",
  "dueDate": "2026-06-15T00:00:00Z",
  "estimatedHours": 4,
  "tags": ["bug", "mobile"]
}

// Response 201
{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "title": "Fix login redirect bug",
  "status": "todo",
  "priority": "high",
  ...
}
```

### Projects

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | `/projects` | List projects | Yes |
| GET | `/projects/:id` | Get project detail | Yes |
| POST | `/projects` | Create project | Admin/Manager |
| PUT | `/projects/:id` | Update project | Admin/Manager |
| DELETE | `/projects/:id` | Delete project | Admin |

## Error Responses

All errors follow this format:

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

Common error codes:
- `AUTH_MISSING_TOKEN` (401)
- `AUTH_INVALID_TOKEN` (401)
- `AUTH_FORBIDDEN` (403)
- `VALIDATION_ERROR` (400)
- `NOT_FOUND` (404)
- `CONFLICT` (409)
- `INTERNAL_ERROR` (500)