Brain/command-center/API_EXAMPLES.md

# API Usage Examples

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

## Authentication
Currently no authentication required (internal tool). Bearer token support planned for Phase 2.

---

## Projects API

### 1. Create a Project

```bash
curl -X POST http://localhost:3000/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Persona Portal v2.0",
    "description": "Redesign and relaunch the persona publishing platform",
    "color_hex": "#3498db",
    "icon_name": "rocket"
  }'
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Persona Portal v2.0",
    "description": "Redesign and relaunch the persona publishing platform",
    "status": "active",
    "color_hex": "#3498db",
    "icon_name": "rocket",
    "owner_id": 1,
    "created_at": "2026-04-13T15:42:00.000Z",
    "updated_at": "2026-04-13T15:42:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

---

### 2. List Projects

```bash
# Get all active projects
curl http://localhost:3000/api/v1/projects

# Filter by status with pagination
curl "http://localhost:3000/api/v1/projects?status=active&limit=25&offset=0"

# Get archived projects
curl "http://localhost:3000/api/v1/projects?status=archived"
```

**Response:**
```json
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Persona Portal v2.0",
      "description": "...",
      "status": "active",
      "color_hex": "#3498db",
      "icon_name": "rocket",
      "owner_id": 1,
      "task_count": 12,
      "completed_count": 3,
      "overdue_count": 1,
      "created_at": "2026-04-13T15:42:00.000Z",
      "updated_at": "2026-04-13T15:42:00.000Z"
    },
    {
      "id": 2,
      "name": "Command Center MVP",
      "description": "Build the core task management system",
      "status": "active",
      "color_hex": "#e74c3c",
      "icon_name": "deploy",
      "owner_id": 1,
      "task_count": 8,
      "completed_count": 5,
      "overdue_count": 0,
      "created_at": "2026-04-13T16:00:00.000Z",
      "updated_at": "2026-04-13T16:00:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 50,
    "offset": 0,
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

---

### 3. Get Project Detail

```bash
curl http://localhost:3000/api/v1/projects/1
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Persona Portal v2.0",
    "description": "Redesign and relaunch the persona publishing platform",
    "status": "active",
    "color_hex": "#3498db",
    "icon_name": "rocket",
    "owner_id": 1,
    "created_at": "2026-04-13T15:42:00.000Z",
    "updated_at": "2026-04-13T15:42:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

---

### 4. Update Project

```bash
curl -X PUT http://localhost:3000/api/v1/projects/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Persona Portal v2.1",
    "status": "paused",
    "color_hex": "#e74c3c"
  }'
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Persona Portal v2.1",
    "description": "Redesign and relaunch the persona publishing platform",
    "status": "paused",
    "color_hex": "#e74c3c",
    "icon_name": "rocket",
    "owner_id": 1,
    "created_at": "2026-04-13T15:42:00.000Z",
    "updated_at": "2026-04-13T15:45:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-13T15:45:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

---

### 5. Delete Project

```bash
curl -X DELETE http://localhost:3000/api/v1/projects/1
```

**Response:** `204 No Content` (empty body)

---

## Tasks API

### 6. Create a Task

```bash
curl -X POST http://localhost:3000/api/v1/projects/1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Design new UI components",
    "description": "Create reusable button, card, and modal components",
    "status": "backlog",
    "due_date": "2026-04-20",
    "assignee_id": 2
  }'
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "id": 42,
    "project_id": 1,
    "title": "Design new UI components",
    "description": "Create reusable button, card, and modal components",
    "status": "backlog",
    "position": 5,
    "due_date": "2026-04-20",
    "assignee_id": 2,
    "created_by": 1,
    "created_at": "2026-04-13T15:42:00.000Z",
    "updated_at": "2026-04-13T15:42:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

Note: Task is added at the end of the project (position = max_position + 1)

---

### 7. List Tasks

```bash
# Get all tasks in a project
curl http://localhost:3000/api/v1/projects/1/tasks

# Filter by status
curl "http://localhost:3000/api/v1/projects/1/tasks?status=in_progress"

# Sort by due date
curl "http://localhost:3000/api/v1/projects/1/tasks?sort=due_date"

# Combine filters
curl "http://localhost:3000/api/v1/projects/1/tasks?status=backlog&sort=due_date&limit=100"
```

**Response:**
```json
{
  "status": "success",
  "data": [
    {
      "id": 42,
      "project_id": 1,
      "title": "Design new UI components",
      "description": "Create reusable button, card, and modal components",
      "status": "backlog",
      "position": 0,
      "due_date": "2026-04-20",
      "assignee_id": 2,
      "created_by": 1,
      "created_at": "2026-04-13T15:42:00.000Z",
      "updated_at": "2026-04-13T15:42:00.000Z"
    },
    {
      "id": 43,
      "project_id": 1,
      "title": "Implement API endpoints",
      "description": null,
      "status": "backlog",
      "position": 1,
      "due_date": null,
      "assignee_id": 1,
      "created_by": 1,
      "created_at": "2026-04-13T15:50:00.000Z",
      "updated_at": "2026-04-13T15:50:00.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "limit": 200,
    "offset": 0,
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

---

### 8. Get Task Detail

```bash
curl http://localhost:3000/api/v1/projects/1/tasks/42
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "id": 42,
    "project_id": 1,
    "title": "Design new UI components",
    "description": "Create reusable button, card, and modal components",
    "status": "backlog",
    "position": 0,
    "due_date": "2026-04-20",
    "assignee_id": 2,
    "created_by": 1,
    "created_at": "2026-04-13T15:42:00.000Z",
    "updated_at": "2026-04-13T15:42:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

---

### 9. Update Task

```bash
# Update just the status
curl -X PUT http://localhost:3000/api/v1/projects/1/tasks/42 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress"
  }'

# Update with reordering
curl -X PUT http://localhost:3000/api/v1/projects/1/tasks/42 \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "position": 2
  }'

# Full update
curl -X PUT http://localhost:3000/api/v1/projects/1/tasks/42 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated title",
    "description": "Updated description",
    "status": "done",
    "due_date": "2026-04-25",
    "assignee_id": 1,
    "position": 0
  }'
```

**Response (with reordering at position 2):**
```json
{
  "status": "success",
  "data": {
    "id": 42,
    "project_id": 1,
    "title": "Design new UI components",
    "description": "Create reusable button, card, and modal components",
    "status": "in_progress",
    "position": 2,
    "due_date": "2026-04-20",
    "assignee_id": 2,
    "created_by": 1,
    "created_at": "2026-04-13T15:42:00.000Z",
    "updated_at": "2026-04-13T15:55:00.000Z"
  },
  "meta": {
    "timestamp": "2026-04-13T15:55:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

---

### 10. Delete Task

```bash
curl -X DELETE http://localhost:3000/api/v1/projects/1/tasks/42
```

**Response:** `204 No Content` (empty body)

---

### 11. Bulk Reorder Tasks

```bash
curl -X POST http://localhost:3000/api/v1/projects/1/tasks/reorder \
  -H "Content-Type: application/json" \
  -d '{
    "order": [43, 44, 45, 42, 46]
  }'
```

**Response:**
```json
{
  "status": "success",
  "data": {
    "updated_count": 5
  },
  "meta": {
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

---

## Error Examples

### Validation Error (400)

```bash
curl -X POST http://localhost:3000/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{
    "name": ""
  }'
```

**Response:**
```json
{
  "status": "error",
  "error": {
    "code": "BAD_REQUEST",
    "message": "Validation failed",
    "details": [
      {
        "field": "name",
        "message": "Project name is required"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

### Not Found (404)

```bash
curl http://localhost:3000/api/v1/projects/999
```

**Response:**
```json
{
  "status": "error",
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Project not found"
  },
  "meta": {
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

### Conflict (409)

```bash
curl -X PUT http://localhost:3000/api/v1/projects/1/tasks/42 \
  -H "Content-Type: application/json" \
  -d '{
    "position": 100
  }'
```

**Response:**
```json
{
  "status": "error",
  "error": {
    "code": "CONFLICT",
    "message": "Position must be between 0 and 4"
  },
  "meta": {
    "timestamp": "2026-04-13T15:42:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

---

## Testing with Different Tools

### Using HTTPie

```bash
# List projects
http http://localhost:3000/api/v1/projects

# Create project
http POST http://localhost:3000/api/v1/projects \
  name="Test Project" \
  description="A test" \
  color_hex="#3498db"
```

### Using Postman

1. Import this collection: (Postman collection JSON available on request)
2. Set environment variable: `base_url = http://localhost:3000`
3. Run requests from "Projects" and "Tasks" folders

### Using VS Code REST Client

Create a `.http` file:

```http
### List Projects
GET http://localhost:3000/api/v1/projects

### Create Project
POST http://localhost:3000/api/v1/projects
Content-Type: application/json

{
  "name": "Test Project",
  "description": "A test project",
  "color_hex": "#3498db"
}
```

---

## Status Filters

**Projects**:
- `active` — Currently in progress
- `archived` — Completed or no longer relevant
- `paused` — Temporarily on hold

**Tasks**:
- `backlog` — Not yet started
- `in_progress` — Currently being worked on
- `done` — Completed
- `blocked` — Waiting on something

---

## Sort Options

- `position` — By task position (default)
- `due_date` — By due date (earliest first)
- `created_at` — By creation date
- `-updated_at` — By last updated (most recent first)

---

**Built by Talos for TekDek Command Center**