API_ENDPOINTS.md

# API Endpoints Reference

Complete reference for all API endpoints in the Enterprise Delivery & Workforce Intelligence API.

**Base URL (Hugging Face):** `https://rudraaaa76-jira-api.hf.space`  
**Base URL (Local):** `http://localhost:8000`

**Authentication:** All endpoints (except `/auth/login`) require Bearer token authentication.

---

## Table of Contents

1. [Authentication Endpoints](#authentication-endpoints)
2. [Jira Data Endpoints](#jira-data-endpoints)
3. [Intelligence & Analytics Endpoints](#intelligence--analytics-endpoints)

---

## Authentication Endpoints

### POST /auth/login
**Description:** Authenticate with Jira credentials and receive JWT token  
**Authentication:** None required  
**Request Body:**
```json
{
  "jira_email": "rudraparmar1309@gmail.com",
  "jira_api_token": "your_jira_api_token",
  "jira_server_url": "https://rudraparmar1309-1770450259652.atlassian.net"
}
```
**Response:**
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 1800
}
```

### GET /auth/me
**Description:** Get current authenticated user information  
**Authentication:** Required  
**Response:**
```json
{
  "jira_email": "rudraparmar1309@gmail.com",
  "jira_server_url": "https://rudraparmar1309-1770450259652.atlassian.net",
  "authenticated": true
}
```

---

## Jira Data Endpoints

### Projects

#### GET /jira/projects
**Description:** Get all Jira projects  
**Authentication:** Required  
**Response:** Array of project objects
```json
[
  {
    "project_key": "PROJ",
    "project_name": "Project Name",
    "project_id": "10000",
    "lead": "User Name",
    "description": "Project description"
  }
]
```

#### GET /jira/projects/{project_key}/issues
**Description:** Get all issues for a specific project  
**Authentication:** Required  
**Path Parameters:**
- `project_key` (string) - Project key (e.g., "PROJ")

**Query Parameters:**
- `max_results` (integer, optional) - Maximum number of results (1-1000, default: 100)
- `start_date` (string, optional) - Filter from date (ISO format: YYYY-MM-DD)
- `end_date` (string, optional) - Filter to date (ISO format: YYYY-MM-DD)

**Example:** `/jira/projects/PROJ/issues?max_results=50&start_date=2026-01-01`

#### GET /jira/projects/{project_key}/team-members
**Description:** Get all team members for a project  
**Authentication:** Required  
**Path Parameters:**
- `project_key` (string) - Project key

**Response:** Array of team member objects

#### GET /jira/projects/{project_key}/worklogs
**Description:** Get worklogs for a project  
**Authentication:** Required  
**Path Parameters:**
- `project_key` (string) - Project key

**Query Parameters:**
- `start_date` (string, optional) - Start date (ISO format)
- `end_date` (string, optional) - End date (ISO format)

### Boards

#### GET /jira/boards
**Description:** Get all Jira boards  
**Authentication:** Required  
**Response:** Array of board objects
```json
[
  {
    "id": 1,
    "name": "Board Name",
    "type": "scrum",
    "self": "https://..."
  }
]
```

#### GET /jira/boards/{board_id}/sprints
**Description:** Get all sprints for a board  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Response:** Array of sprint objects

#### GET /jira/boards/{board_id}/active-sprint
**Description:** Get the currently active sprint for a board  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Response:** Sprint object or null

#### GET /jira/boards/{board_id}/configuration
**Description:** Get board configuration including columns and settings  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

#### GET /jira/boards/{board_id}/backlog
**Description:** Get backlog issues for a board  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Query Parameters:**
- `max_results` (integer, optional) - Maximum results (1-500, default: 100)

### Sprints

#### GET /jira/sprints/{sprint_id}/issues
**Description:** Get all issues in a specific sprint  
**Authentication:** Required  
**Path Parameters:**
- `sprint_id` (integer) - Sprint ID

**Response:** Array of issue objects

### Issues

#### GET /jira/issues/{issue_key}
**Description:** Get a specific issue by key  
**Authentication:** Required  
**Path Parameters:**
- `issue_key` (string) - Issue key (e.g., "PROJ-123")

**Response:** Issue object

#### GET /jira/issues/{issue_key}/transitions
**Description:** Get available transitions for an issue  
**Authentication:** Required  
**Path Parameters:**
- `issue_key` (string) - Issue key

**Response:** Array of transition objects

#### POST /jira/issues/{issue_key}/transition
**Description:** Move an issue to a different status  
**Authentication:** Required  
**Path Parameters:**
- `issue_key` (string) - Issue key

**Query Parameters:**
- `transition_name` (string, required) - Name of transition to execute

**Response:**
```json
{
  "success": true,
  "message": "Issue PROJ-123 transitioned to Done"
}
```

### Kanban Boards

#### GET /jira/kanban/boards
**Description:** Get all Kanban boards with column configurations  
**Authentication:** Required  
**Response:** Array of Kanban board objects with columns

#### GET /jira/kanban/boards/{board_id}
**Description:** Get a specific Kanban board by ID  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Response:** Kanban board object with columns

#### GET /jira/kanban/boards/{board_id}/issues
**Description:** Get issues for a Kanban board grouped by columns  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Response:** Array of column objects with their issues

---

## Intelligence & Analytics Endpoints

### Delivery Metrics

#### GET /intelligence/delivery-health/{project_key}
**Description:** Get delivery health metrics for a project or sprint  
**Authentication:** Required  
**Path Parameters:**
- `project_key` (string) - Project key

**Query Parameters:**
- `board_id` (integer, optional) - Board ID for sprint context
- `sprint_id` (integer, optional) - Specific sprint ID
- `start_date` (string, optional) - Start date (ISO format)
- `end_date` (string, optional) - End date (ISO format)

**Response:**
```json
{
  "velocity": 45.5,
  "completion_rate": 87.5,
  "avg_cycle_time_days": 3.2,
  "sprint_health_score": 8.5,
  "total_issues": 120,
  "completed_issues": 105,
  "in_progress_issues": 10,
  "blocked_issues": 5
}
```

### Productivity Metrics

#### GET /intelligence/productivity/{project_key}
**Description:** Get productivity metrics for all team members  
**Authentication:** Required  
**Path Parameters:**
- `project_key` (string) - Project key

**Query Parameters:**
- `start_date` (string, optional) - Start date (default: 14 days ago)
- `end_date` (string, optional) - End date (default: today)

**Response:** Array of productivity metrics per team member
```json
[
  {
    "team_member_id": "user123",
    "team_member_name": "John Doe",
    "issues_completed": 12,
    "story_points_completed": 34,
    "avg_completion_time_days": 2.5,
    "work_hours_logged": 80,
    "productivity_score": 8.7
  }
]
```

### Cost Efficiency

#### GET /intelligence/cost-efficiency/{project_key}
**Description:** Get cost efficiency metrics for a project  
**Authentication:** Required  
**Path Parameters:**
- `project_key` (string) - Project key

**Query Parameters:**
- `start_date` (string, optional) - Start date (default: 14 days ago)
- `end_date` (string, optional) - End date (default: today)
- `avg_hourly_rate` (float, optional) - Average hourly rate (default: 75.0)

**Response:**
```json
{
  "total_hours_logged": 520,
  "total_cost": 39000,
  "cost_per_issue": 325,
  "cost_per_story_point": 162.5,
  "efficiency_score": 7.8,
  "issues_delivered": 120,
  "story_points_delivered": 240
}
```

### Risk Management

#### GET /intelligence/risk-alerts/{project_key}
**Description:** Get risk alerts for a project  
**Authentication:** Required  
**Path Parameters:**
- `project_key` (string) - Project key

**Query Parameters:**
- `board_id` (integer, optional) - Board ID
- `sprint_id` (integer, optional) - Sprint ID
- `start_date` (string, optional) - Start date (default: 14 days ago)
- `end_date` (string, optional) - End date (default: today)

**Response:** Array of risk alert objects
```json
[
  {
    "alert_type": "delivery_risk",
    "severity": "high",
    "title": "Sprint at Risk",
    "description": "Sprint completion rate below 70%",
    "affected_items": ["Sprint 42"],
    "recommendation": "Review sprint scope and consider moving items to backlog"
  }
]
```

### Insights & Recommendations

#### GET /intelligence/insights/{project_key}
**Description:** Get AI-generated insights and recommendations  
**Authentication:** Required  
**Path Parameters:**
- `project_key` (string) - Project key

**Query Parameters:**
- `board_id` (integer, optional) - Board ID
- `sprint_id` (integer, optional) - Sprint ID
- `start_date` (string, optional) - Start date (default: 14 days ago)
- `end_date` (string, optional) - End date (default: today)

**Response:** Array of insight objects
```json
[
  {
    "category": "productivity",
    "priority": "high",
    "title": "Optimize Team Allocation",
    "description": "3 team members are over-allocated",
    "impact": "Could improve delivery by 15%",
    "action_items": ["Redistribute workload", "Review capacity planning"]
  }
]
```

### Dashboard

#### GET /intelligence/dashboard/{project_key}
**Description:** Get comprehensive dashboard data with all metrics  
**Authentication:** Required  
**Path Parameters:**
- `project_key` (string) - Project key

**Query Parameters:**
- `board_id` (integer, optional) - Board ID
- `sprint_id` (integer, optional) - Sprint ID
- `start_date` (string, optional) - Start date
- `end_date` (string, optional) - End date

**Response:** Combined object with all metrics
```json
{
  "delivery_health": {...},
  "productivity_metrics": [...],
  "cost_efficiency": {...},
  "risk_alerts": [...],
  "insights": [...],
  "period": {
    "start": "2026-01-24",
    "end": "2026-02-07"
  }
}
```

### Kanban Intelligence

#### GET /intelligence/kanban/flow-metrics/{board_id}
**Description:** Get Kanban flow efficiency metrics  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Query Parameters:**
- `start_date` (string, optional) - Start date (default: 30 days ago)
- `end_date` (string, optional) - End date (default: today)

**Response:**
```json
{
  "board_id": 123,
  "board_name": "Development Board",
  "cycle_time_avg_days": 4.5,
  "lead_time_avg_days": 7.2,
  "throughput": 25,
  "wip_avg": 15,
  "flow_efficiency": 62.5,
  "blocked_items_count": 3
}
```

#### GET /intelligence/kanban/column-analysis/{board_id}
**Description:** Get detailed analysis of each Kanban column  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Response:** Array of column analysis objects
```json
[
  {
    "column_name": "In Progress",
    "current_wip": 8,
    "avg_time_in_column_days": 2.3,
    "bottleneck_score": 6.5,
    "issue_count": 8,
    "recommended_wip_limit": 5
  }
]
```

#### GET /intelligence/kanban/wip-recommendations/{board_id}
**Description:** Get WIP limit recommendations for columns  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Query Parameters:**
- `start_date` (string, optional) - Start date (default: 30 days ago)
- `end_date` (string, optional) - End date (default: today)

**Response:** Array of WIP recommendation objects
```json
[
  {
    "column_name": "In Progress",
    "current_wip": 8,
    "current_limit": null,
    "recommended_limit": 5,
    "reason": "High average cycle time and bottleneck detected",
    "expected_improvement": "Reduce cycle time by 25%"
  }
]
```

#### GET /intelligence/kanban/insights/{board_id}
**Description:** Get Kanban-specific insights and recommendations  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Query Parameters:**
- `start_date` (string, optional) - Start date (default: 30 days ago)
- `end_date` (string, optional) - End date (default: today)

**Response:** Array of Kanban insight objects

#### GET /intelligence/kanban/dashboard/{board_id}
**Description:** Get comprehensive Kanban dashboard with all metrics  
**Authentication:** Required  
**Path Parameters:**
- `board_id` (integer) - Board ID

**Query Parameters:**
- `start_date` (string, optional) - Start date (default: 30 days ago)
- `end_date` (string, optional) - End date (default: today)

**Response:** Combined Kanban metrics object
```json
{
  "flow_metrics": {...},
  "column_analysis": [...],
  "wip_recommendations": [...],
  "insights": [...],
  "period": {
    "start": "2026-01-08",
    "end": "2026-02-07"
  }
}
```

---

## General Endpoints

### GET /
**Description:** API root endpoint - returns API information  
**Authentication:** None required  
**Response:**
```json
{
  "message": "Enterprise Delivery & Workforce Intelligence API",
  "version": "1.0.0",
  "status": "operational",
  "endpoints": {
    "jira": "/jira",
    "intelligence": "/intelligence",
    "docs": "/docs",
    "redoc": "/redoc"
  }
}
```

### GET /health
**Description:** Health check endpoint  
**Authentication:** None required  
**Response:**
```json
{
  "status": "healthy",
  "timestamp": "2026-02-07T00:00:00Z"
}
```

### GET /docs
**Description:** Interactive Swagger UI documentation  
**Authentication:** None required (but needed to test endpoints)  
**Browser:** Opens interactive API documentation

### GET /redoc
**Description:** Alternative ReDoc API documentation  
**Authentication:** None required  
**Browser:** Opens ReDoc documentation

---

## Summary

**Total Endpoints:** 31

- **Authentication:** 2 endpoints
- **Jira Data:** 17 endpoints
- **Intelligence:** 10 endpoints
- **General:** 4 endpoints

**Authentication Method:** Bearer Token (JWT)  
**Token Expiration:** 30 minutes  
**Content Type:** application/json