# ColaFlow API Endpoints Summary

**Base URL**: `http://localhost:5167`

**API Documentation**: `http://localhost:5167/scalar/v1` (Scalar UI)

**Last Updated**: 2025-11-05 (Day 16)

---

## ProjectManagement API Endpoints

### Projects (5 endpoints)

| Method | Endpoint | Description | Auth | Response |
|--------|----------|-------------|------|----------|
| GET | /api/v1/Projects | List all projects for current tenant | Required | 200 OK |
| GET | /api/v1/Projects/{id} | Get project by ID | Required | 200 OK |
| POST | /api/v1/Projects | Create new project | Required | 201 Created |
| PUT | /api/v1/Projects/{id} | Update project | Required | 200 OK |
| DELETE | /api/v1/Projects/{id} | Delete project | Required | 204 No Content |

### Epics (6 endpoints)

| Method | Endpoint | Description | Auth | Response |
|--------|----------|-------------|------|----------|
| GET | /api/v1/projects/{projectId}/epics | List epics for a project | Required | 200 OK |
| GET | /api/v1/epics/{id} | Get epic by ID | Required | 200 OK |
| POST | /api/v1/projects/{projectId}/epics | Create epic (nested) | Required | 201 Created |
| POST | /api/v1/epics | Create epic (independent) | Required | 201 Created |
| PUT | /api/v1/epics/{id} | Update epic | Required | 200 OK |

### Stories (9 endpoints)

| Method | Endpoint | Description | Auth | Response |
|--------|----------|-------------|------|----------|
| GET | /api/v1/stories/{id} | Get story by ID | Required | 200 OK |
| GET | /api/v1/epics/{epicId}/stories | List stories for an epic | Required | 200 OK |
| GET | /api/v1/projects/{projectId}/stories | List stories for a project | Required | 200 OK |
| POST | /api/v1/epics/{epicId}/stories | Create story (nested) | Required | 201 Created |
| POST | /api/v1/stories | Create story (independent) | Required | 201 Created |
| PUT | /api/v1/stories/{id} | Update story | Required | 200 OK |
| PUT | /api/v1/stories/{id}/assign | Assign story | Required | 200 OK |
| DELETE | /api/v1/stories/{id} | Delete story | Required | 204 No Content |

### Tasks (11 endpoints)

| Method | Endpoint | Description | Auth | Response |
|--------|----------|-------------|------|----------|
| GET | /api/v1/tasks/{id} | Get task by ID | Required | 200 OK |
| GET | /api/v1/stories/{storyId}/tasks | List tasks for a story | Required | 200 OK |
| GET | /api/v1/projects/{projectId}/tasks | List tasks for a project (with filters) | Required | 200 OK |
| POST | /api/v1/stories/{storyId}/tasks | Create task (nested) | Required | 201 Created |
| POST | /api/v1/tasks | Create task (independent) | Required | 201 Created |
| PUT | /api/v1/tasks/{id} | Update task | Required | 200 OK |
| PUT | /api/v1/tasks/{id}/status | Update task status | Required | 200 OK |
| PUT | /api/v1/tasks/{id}/assign | Assign task | Required | 200 OK |
| DELETE | /api/v1/tasks/{id} | Delete task | Required | 204 No Content |

**Total ProjectManagement Endpoints**: **31**

---

## Authentication API Endpoints

### Auth (9 endpoints)

| Method | Endpoint | Description | Auth | Response |
|--------|----------|-------------|------|----------|
| POST | /api/Auth/login | User login | No | 200 OK |
| GET | /api/Auth/me | Get current user | Required | 200 OK |
| POST | /api/Auth/refresh | Refresh access token | No | 200 OK |
| POST | /api/Auth/logout | Logout current session | Required | 200 OK |
| POST | /api/Auth/logout-all | Logout all sessions | Required | 200 OK |
| POST | /api/Auth/verify-email | Verify email address | No | 200 OK |
| POST | /api/Auth/resend-verification | Resend verification email | No | 200 OK |
| POST | /api/Auth/forgot-password | Request password reset | No | 200 OK |
| POST | /api/Auth/reset-password | Reset password | No | 200 OK |
| POST | /api/Auth/invitations/accept | Accept tenant invitation | No | 200 OK |

---

## Identity & Tenant Management API Endpoints

### Tenants (3 endpoints)

| Method | Endpoint | Description | Auth | Response |
|--------|----------|-------------|------|----------|
| POST | /api/Tenants/register | Register new tenant | No | 200 OK |
| GET | /api/Tenants/{slug} | Get tenant by slug | No | 200 OK |
| GET | /api/Tenants/check-slug/{slug} | Check if slug is available | No | 200 OK |

### Tenant Invitations (3 endpoints)

| Method | Endpoint | Description | Auth | Response |
|--------|----------|-------------|------|----------|
| POST | /api/tenants/{tenantId}/invitations | Invite user to tenant | Required | 200 OK |
| GET | /api/tenants/{tenantId}/invitations | List tenant invitations | Required | 200 OK |
| DELETE | /api/tenants/{tenantId}/invitations/{invitationId} | Revoke invitation | Required | 200 OK |

### Tenant Users (5 endpoints)

| Method | Endpoint | Description | Auth | Response |
|--------|----------|-------------|------|----------|
| GET | /api/tenants/{tenantId}/users | List tenant users (with pagination) | Required | 200 OK |
| POST | /api/tenants/{tenantId}/users/{userId}/role | Assign role to user | Required | 200 OK |
| PUT | /api/tenants/{tenantId}/users/{userId}/role | Update user role | Required | 200 OK |
| DELETE | /api/tenants/{tenantId}/users/{userId} | Remove user from tenant | Required | 200 OK |
| GET | /api/tenants/{tenantId}/users/../roles | List available roles | Required | 200 OK |

**Total Identity Endpoints**: **20**

---

## SignalR Hub Endpoints (Real-time)

### Hubs (2 WebSocket connections)

| Endpoint | Description | Auth |
|----------|-------------|------|
| /hubs/project | Project updates (real-time) | Required |
| /hubs/notification | User notifications (real-time) | Required |

### SignalR Test Endpoints (5 endpoints)

| Method | Endpoint | Description | Auth | Response |
|--------|----------|-------------|------|----------|
| POST | /api/SignalRTest/test-user-notification | Test user notification | Required | 200 OK |
| POST | /api/SignalRTest/test-tenant-notification | Test tenant notification | Required | 200 OK |
| POST | /api/SignalRTest/test-project-update | Test project update | Required | 200 OK |
| POST | /api/SignalRTest/test-issue-status-change | Test issue status change | Required | 200 OK |
| GET | /api/SignalRTest/connection-info | Get connection info | Required | 200 OK |

**Total Real-time Endpoints**: **7**

---

## Grand Total

| Category | Endpoint Count |
|----------|----------------|
| **ProjectManagement** | 31 |
| **Authentication** | 10 |
| **Identity & Tenants** | 20 |
| **Real-time (SignalR)** | 7 |
| **TOTAL** | **68 endpoints** |

---

## Key API Groups for Frontend

### Essential for Day 18 Frontend Development:

1. **Authentication** (Priority: CRITICAL)
   - POST /api/Auth/login
   - GET /api/Auth/me
   - POST /api/Auth/refresh
   - POST /api/Auth/logout

2. **Projects** (Priority: HIGH)
   - GET /api/v1/Projects
   - GET /api/v1/Projects/{id}
   - POST /api/v1/Projects
   - PUT /api/v1/Projects/{id}
   - DELETE /api/v1/Projects/{id}

3. **Epics** (Priority: HIGH)
   - GET /api/v1/projects/{projectId}/epics
   - POST /api/v1/projects/{projectId}/epics
   - PUT /api/v1/epics/{id}

4. **Stories** (Priority: HIGH)
   - GET /api/v1/epics/{epicId}/stories
   - POST /api/v1/epics/{epicId}/stories
   - PUT /api/v1/stories/{id}
   - PUT /api/v1/stories/{id}/assign

5. **Tasks** (Priority: HIGH)
   - GET /api/v1/stories/{storyId}/tasks
   - GET /api/v1/projects/{projectId}/tasks (with filters)
   - POST /api/v1/stories/{storyId}/tasks
   - PUT /api/v1/tasks/{id}/status
   - PUT /api/v1/tasks/{id}/assign

6. **Tenants** (Priority: MEDIUM)
   - POST /api/Tenants/register
   - GET /api/tenants/{tenantId}/users

7. **Real-time** (Priority: MEDIUM - Phase 2)
   - /hubs/project (WebSocket)
   - /hubs/notification (WebSocket)

---

## Authentication Flow

```
1. POST /api/Tenants/register           → Register tenant + admin user
2. POST /api/Auth/login                 → Get JWT access token + refresh token
3. Use "Authorization: Bearer <token>"  → For all subsequent API calls
4. POST /api/Auth/refresh               → Refresh expired access token
5. POST /api/Auth/logout                → Logout and invalidate refresh token
```

---

## Typical Frontend Workflow

### Creating a Project with Epics and Stories:

```
1. GET /api/v1/Projects                     → List existing projects
2. POST /api/v1/Projects                    → Create new project
3. POST /api/v1/projects/{id}/epics         → Create epic under project
4. POST /api/v1/epics/{epicId}/stories      → Create story under epic
5. POST /api/v1/stories/{storyId}/tasks     → Create task under story
6. PUT /api/v1/tasks/{id}/assign            → Assign task to user
7. PUT /api/v1/tasks/{id}/status            → Update task status (Kanban board)
```

---

## API Design Patterns

### 1. Nested Resources (RESTful)
- **Nested**: POST /api/v1/projects/{projectId}/epics
- **Independent**: POST /api/v1/epics

Both patterns are supported for flexibility.

### 2. Action-based Endpoints
- PUT /api/v1/tasks/{id}/assign
- PUT /api/v1/tasks/{id}/status

Specific actions use dedicated endpoints for clarity.

### 3. Query Parameters for Filtering
- GET /api/v1/projects/{projectId}/tasks?status=InProgress&assigneeId={userId}

---

## Multi-Tenant Security Notes

All ProjectManagement endpoints enforce tenant isolation:

- The `tenantId` is extracted from JWT token
- **DO NOT** send `tenantId` in request bodies
- 404 responses prevent information leakage
- Cross-tenant access is impossible

**Verified by 7 integration tests.**

---

## Response Format

### Success Response (Example: GET Project)

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "ColaFlow Development",
  "key": "COLA",
  "description": "Main development project",
  "status": "Active",
  "ownerId": "user-guid",
  "createdAt": "2025-11-01T10:00:00Z",
  "updatedAt": "2025-11-05T15:30:00Z",
  "epics": []
}
```

### Error Response (RFC 7807)

```json
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Project with ID 'xxx' not found",
  "instance": "/api/v1/Projects/xxx"
}
```

---

## Frontend Development Checklist

- [ ] Set up API client with JWT authentication
- [ ] Generate TypeScript types from OpenAPI spec
- [ ] Implement authentication flow (login, refresh, logout)
- [ ] Create React Query hooks for Projects API
- [ ] Create React Query hooks for Epics API
- [ ] Create React Query hooks for Stories API
- [ ] Create React Query hooks for Tasks API
- [ ] Implement error handling for ProblemDetails responses
- [ ] Set up WebSocket connection for SignalR (Phase 2)
- [ ] Add loading states and error boundaries

---

## Quick Links

- **Scalar UI**: http://localhost:5167/scalar/v1
- **OpenAPI JSON**: http://localhost:5167/openapi/v1.json
- **API Reference**: `ProjectManagement-API-Reference.md`
- **Backend Tests**: 7/7 Integration Tests Passing

---

**Status**: Production Ready (95%)

**Generated**: 2025-11-05 (Day 16)

**Backend Team**: Ready to support frontend integration