REST API Documentation

# Task Manager API v2.0

**RESTful API Reference**

Base URL: `https://api.taskmanager.com/v2`

---

## Authentication

All API requests require authentication via Bearer token.

\`\`\`bash
Authorization: Bearer YOUR_API_TOKEN
\`\`\`

**Get your API token:** Dashboard → Settings → API Keys

---

## Endpoints

### Tasks

#### List all tasks

\`\`\`http
GET /tasks
\`\`\`

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status (todo, in_progress, done) |
| `priority` | string | No | Filter by priority (low, medium, high) |
| `limit` | integer | No | Results per page (default: 20, max: 100) |
| `offset` | integer | No | Pagination offset (default: 0) |

**Example Request:**

\`\`\`bash
curl -X GET "https://api.taskmanager.com/v2/tasks?status=todo&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
\`\`\`

**Response (200 OK):**

\`\`\`json
{
  "data": [
    {
      "id": "task_12345",
      "title": "Implement user authentication",
      "description": "Add JWT-based auth system",
      "status": "in_progress",
      "priority": "high",
      "due_date": "2024-11-15",
      "assignee": {
        "id": "user_789",
        "name": "Sarah Chen",
        "email": "sarah@example.com"
      },
      "tags": ["backend", "security"],
      "created_at": "2024-11-01T10:00:00Z",
      "updated_at": "2024-11-02T14:30:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "limit": 10,
    "offset": 0
  }
}
\`\`\`

#### Create a task

\`\`\`http
POST /tasks
\`\`\`

**Request Body:**

\`\`\`json
{
  "title": "Task title (required)",
  "description": "Task description (optional)",
  "status": "todo (optional, default: todo)",
  "priority": "medium (optional, default: medium)",
  "due_date": "2024-12-31 (optional, ISO 8601)",
  "assignee_id": "user_789 (optional)",
  "tags": ["tag1", "tag2"] (optional)
}
\`\`\`

**Response (201 Created):**

\`\`\`json
{
  "id": "task_67890",
  "title": "New task",
  "status": "todo",
  ...
}
\`\`\`

#### Update a task

\`\`\`http
PATCH /tasks/{task_id}
\`\`\`

**Request Body:** Same fields as Create (all optional)

**Response (200 OK):** Updated task object

#### Delete a task

\`\`\`http
DELETE /tasks/{task_id}
\`\`\`

**Response (204 No Content)**

---

### Users

#### Get current user

\`\`\`http
GET /users/me
\`\`\`

**Response:**

\`\`\`json
{
  "id": "user_123",
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "created_at": "2024-01-01T00:00:00Z"
}
\`\`\`

---

## Error Responses

| Code | Description |
|------|-------------|
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid/missing API token |
| 403 | Forbidden - Insufficient permissions |
| 404 | Not Found - Resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |

**Error Response Format:**

\`\`\`json
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Task title is required",
    "details": {
      "field": "title",
      "constraint": "required"
    }
  }
}
\`\`\`

---

## Rate Limiting

- **Limit:** 1000 requests per hour per API token
- **Headers:**
  - `X-RateLimit-Limit: 1000`
  - `X-RateLimit-Remaining: 850`
  - `X-RateLimit-Reset: 1699027200`

---

## Webhooks

Configure webhooks to receive real-time updates.

**Events:**
- `task.created`
- `task.updated`
- `task.deleted`
- `task.completed`

**Payload Example:**

\`\`\`json
{
  "event": "task.created",
  "timestamp": "2024-11-02T15:00:00Z",
  "data": { ...task object... }
}
\`\`\`

---

## SDKs

**JavaScript/TypeScript:**
\`\`\`bash
npm install @taskmanager/sdk
\`\`\`

**Python:**
\`\`\`bash
pip install taskmanager-sdk
\`\`\`

**Usage Example:**

\`\`\`javascript
import TaskManager from '@taskmanager/sdk'

const client = new TaskManager({ apiToken: 'YOUR_TOKEN' })

const tasks = await client.tasks.list({ status: 'todo' })
const task = await client.tasks.create({ title: 'New task' })
\`\`\`

---

**Need help?** Contact support@taskmanager.com