Projects API

The Projects API provides endpoints for managing projects, project members, and project-related statistics.

Endpoints

List Projects

GET /api/projects

Query Parameters:

• page (number) — default 1
• limit (number) — default 20, max 100
• sort (string) — name, createdAt, updatedAt (default updatedAt)
• order (string) — asc, desc (default desc)
• search (string)
• workspace (string)
• status (string)

Response:

{ "data": [ { "id": "project_123", "name": "Web Application", "description": "Main web application project", "key": "WEB", "status": "active", "visibility": "private", "workspaceId": "workspace_456", "ownerId": "user_789", "owner": {"id": "user_789", "name": "John Doe", "email": "john@example.com", "image": "https://example.com/avatar.jpg"}, "createdAt": "2024-01-01T00:00:00Z", "updatedAt": "2024-01-15T12:00:00Z", "_count": {"tickets": 25, "members": 5} } ], "pagination": {"page": 1, "limit": 20, "total": 3, "totalPages": 1} }

Create Project

POST /api/projects

Request Body:

{ "name": "Mobile App", "description": "iOS and Android mobile application", "key": "MOB", "workspaceId": "workspace_456", "visibility": "private" }

Get Project

GET /api/project/[id]

Update Project

PUT /api/project/[id]

Delete Project

DELETE /api/project/[id]

Get Project Statistics

GET /api/project/[id]/stats

Query Parameters:

• period (string) — week, month, quarter, year (default month)

Get Project Members

GET /api/project/[id]/members

Add Project Member

POST /api/project/[id]/members

Remove Project Member

DELETE /api/project/[id]/members/[userId]

Search Projects

GET /api/project/search

Query Parameters:

• q (string, required) — Search query
• limit (number) — default 20, max 100
• workspace (string)

Data Models

interface Project { id: string; name: string; description?: string; key?: string; status: 'active' | 'archived' | 'deleted'; visibility: 'private' | 'public'; workspaceId?: string; ownerId: string; createdAt: Date; updatedAt: Date } interface ProjectWithDetails extends Project { owner: Pick<User, 'id' | 'name' | 'email' | 'image'>; members?: Pick<User, 'id' | 'name' | 'email' | 'image'>[]; _count: { tickets: number; members: number } } interface ProjectMember { id: string; name?: string; email?: string; image?: string; role: 'owner' | 'admin' | 'member' | 'viewer'; joinedAt: Date } interface ProjectStats { period: 'week' | 'month' | 'quarter' | 'year'; startDate: Date; endDate: Date; tickets: { total: number; open: number; inProgress: number; completed: number; overdue: number }; members: { total: number; active: number }; activity: { ticketsCreated: number; ticketsCompleted: number; comments: number }; progress: { completionRate: number; averageTicketAge: string; velocity: number } }

Error Responses

{"error": {"code": "UNAUTHORIZED", "message": "Authentication required"}}

{"error": {"code": "FORBIDDEN", "message": "Insufficient permissions to access this project"}}

{"error": {"code": "NOT_FOUND", "message": "Project not found"}}

{"error": {"code": "VALIDATION_ERROR", "message": "Invalid input data", "details": {"name": ["Project name is required"], "key": ["Project key must be unique"]}}}

Examples

curl -X POST "https://codimir.com/api/projects" -H "Content-Type: application/json" -H "Cookie: next-auth.session-token=..." -d '{"name":"Mobile App","description":"iOS and Android mobile application","key":"MOB","workspaceId":"workspace_456"}'

curl -X GET "https://codimir.com/api/projects?search=web&page=1&limit=10&sort=updatedAt&order=desc" -H "Cookie: next-auth.session-token=..."

curl -X POST "https://codimir.com/api/project/project_123/members" -H "Content-Type: application/json" -H "Cookie: next-auth.session-token=..." -d '{"userId":"user_102","role":"member"}'