API Reference - anubissbe/ProjectHub-Mcp GitHub Wiki

📡 API Reference

ProjectHub-MCP provides a comprehensive RESTful API for integration with external systems and custom applications. This reference covers all available endpoints, authentication, and usage examples.

🔐 Authentication

JWT Token Authentication

All API requests require a valid JWT token in the Authorization header.

# Login to obtain token
curl -X POST http://localhost:3008/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "admin123"
  }'

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-123",
    "email": "[email protected]",
    "first_name": "Admin",
    "last_name": "User",
    "role": "admin"
  }
}

Using the Token

Include the JWT token in all subsequent requests:

curl -X GET http://localhost:3008/api/projects \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

🌐 Base URL

  • Production: http://192.168.1.24:3008/api
  • Development: http://localhost:3008/api

📊 Response Format

All API responses follow a consistent format:

{
  "success": true,
  "data": {...},
  "message": "Operation completed successfully",
  "timestamp": "2025-07-03T19:30:00Z"
}

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  },
  "timestamp": "2025-07-03T19:30:00Z"
}

🔑 Authentication Endpoints

POST /auth/login

Authenticate user and receive JWT token.

Request Body:

{
  "email": "[email protected]",
  "password": "password123"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "user-123",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "role": "developer"
    }
  }
}

POST /auth/logout

Invalidate current JWT token.

Headers: Authorization: Bearer <token>

Response:

{
  "success": true,
  "message": "Logged out successfully"
}

GET /auth/me

Get current user information.

Headers: Authorization: Bearer <token>

Response:

{
  "success": true,
  "data": {
    "id": "user-123",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "role": "developer",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

📁 Project Endpoints

GET /projects

Retrieve all projects accessible to the user.

Query Parameters:

  • status (optional): Filter by status (planning, active, paused, completed, cancelled)
  • limit (optional): Limit number of results (default: 50)
  • offset (optional): Skip number of results (default: 0)

Example:

curl -X GET "http://localhost:3008/api/projects?status=active&limit=10" \
  -H "Authorization: Bearer <token>"

Response:

{
  "success": true,
  "data": [
    {
      "id": "proj-123",
      "name": "Website Redesign",
      "description": "Complete website overhaul",
      "status": "active",
      "progress": 65,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-07-03T15:30:00Z",
      "task_count": 24
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

POST /projects

Create a new project.

Request Body:

{
  "name": "New Project",
  "description": "Project description",
  "status": "planning"
}

Response:

{
  "success": true,
  "data": {
    "id": "proj-456",
    "name": "New Project",
    "description": "Project description",
    "status": "planning",
    "progress": 0,
    "created_at": "2025-07-03T19:30:00Z",
    "updated_at": "2025-07-03T19:30:00Z",
    "task_count": 0
  }
}

GET /projects/:id

Get specific project details.

Response:

{
  "success": true,
  "data": {
    "id": "proj-123",
    "name": "Website Redesign",
    "description": "Complete website overhaul",
    "status": "active",
    "progress": 65,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-07-03T15:30:00Z",
    "tasks": [
      {
        "id": "task-789",
        "title": "Design Homepage",
        "status": "completed",
        "priority": "high"
      }
    ]
  }
}

PUT /projects/:id

Update project details.

Request Body:

{
  "name": "Updated Project Name",
  "description": "Updated description",
  "status": "active"
}

DELETE /projects/:id

Delete a project and all associated tasks.

Response:

{
  "success": true,
  "message": "Project deleted successfully"
}

✅ Task Endpoints

GET /tasks

Retrieve tasks with optional filtering.

Query Parameters:

  • project_id (optional): Filter by project
  • status (optional): Filter by status
  • priority (optional): Filter by priority
  • assigned_to (optional): Filter by assignee

Example:

curl -X GET "http://localhost:3008/api/tasks?project_id=proj-123&status=in_progress" \
  -H "Authorization: Bearer <token>"

POST /tasks

Create a new task.

Request Body:

{
  "title": "Implement user authentication",
  "description": "Add JWT-based authentication system",
  "project_id": "proj-123",
  "status": "pending",
  "priority": "high",
  "assigned_to": "user-456"
}

PUT /tasks/:id

Update task details.

Request Body:

{
  "title": "Updated task title",
  "status": "completed",
  "priority": "medium"
}

DELETE /tasks/:id

Delete a task.

👥 User Management Endpoints (Admin Only)

GET /users

Retrieve all users (Admin only).

Response:

{
  "success": true,
  "data": [
    {
      "id": "user-123",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "role": "developer",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

POST /users

Create a new user (Admin only).

Request Body:

{
  "email": "[email protected]",
  "password": "secure123",
  "first_name": "Jane",
  "last_name": "Smith",
  "role": "developer"
}

PUT /users/:id

Update user details (Admin only).

DELETE /users/:id

Delete a user (Admin only).

📊 Analytics Endpoints

GET /analytics

Get comprehensive analytics data.

Response:

{
  "success": true,
  "data": {
    "projectStats": {
      "total": 15,
      "active": 8,
      "completed": 7
    },
    "taskStats": {
      "total": 156,
      "completed": 98,
      "in_progress": 32,
      "pending": 26
    },
    "teamPerformance": {
      "avgCompletionTime": "2.5 days",
      "completionRate": 87,
      "productivityScore": 92
    }
  }
}

GET /analytics/projects/:id

Get analytics for a specific project.

GET /analytics/team

Get team performance metrics.

🔗 Webhook Endpoints

GET /webhooks

Retrieve configured webhooks.

Response:

{
  "success": true,
  "data": [
    {
      "id": "hook-123",
      "name": "Slack Integration",
      "url": "https://hooks.slack.com/services/...",
      "events": ["task.completed", "project.updated"],
      "active": true,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

POST /webhooks

Create a new webhook.

Request Body:

{
  "name": "Slack Integration",
  "url": "https://hooks.slack.com/services/...",
  "events": ["task.completed", "project.updated"],
  "active": true
}

PUT /webhooks/:id

Update webhook configuration.

DELETE /webhooks/:id

Delete a webhook.

POST /webhooks/:id/test

Test webhook delivery.

🔍 Search Endpoints

GET /search

Global search across projects, tasks, and users.

Query Parameters:

  • q (required): Search query
  • type (optional): Search type (projects, tasks, users, all)
  • limit (optional): Limit results

Example:

curl -X GET "http://localhost:3008/api/search?q=authentication&type=tasks" \
  -H "Authorization: Bearer <token>"

🏥 Health and Status

GET /health

Check API health status.

Response:

{
  "status": "ok",
  "timestamp": "2025-07-03T19:30:00Z",
  "service": "projecthub-backend-complete",
  "version": "4.7.1",
  "database": "connected",
  "uptime": "2d 15h 30m"
}

📚 Error Codes

Code Status Description
AUTH_REQUIRED 401 Authentication required
AUTH_INVALID 401 Invalid or expired token
FORBIDDEN 403 Insufficient permissions
NOT_FOUND 404 Resource not found
VALIDATION_ERROR 400 Invalid request data
SERVER_ERROR 500 Internal server error
RATE_LIMITED 429 Too many requests

🔄 Rate Limiting

The API implements rate limiting to ensure fair usage:

  • Standard Users: 100 requests per minute
  • Premium Users: 500 requests per minute
  • Admin Users: 1000 requests per minute

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1625097600

📋 SDK and Examples

JavaScript/Node.js

const ProjectHubAPI = require('projecthub-api-client');

const client = new ProjectHubAPI({
  baseURL: 'http://localhost:3008/api',
  token: 'your-jwt-token'
});

// Get all projects
const projects = await client.projects.list();

// Create a task
const task = await client.tasks.create({
  title: 'New task',
  project_id: 'proj-123',
  priority: 'high'
});

Python

import requests

class ProjectHubAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    
    def get_projects(self):
        response = requests.get(
            f'{self.base_url}/projects',
            headers=self.headers
        )
        return response.json()

# Usage
api = ProjectHubAPI('http://localhost:3008/api', 'your-token')
projects = api.get_projects()

cURL Examples

# Get all projects
curl -X GET "http://localhost:3008/api/projects" \
  -H "Authorization: Bearer <token>"

# Create a task
curl -X POST "http://localhost:3008/api/tasks" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New task",
    "project_id": "proj-123",
    "priority": "high"
  }'

# Update project status
curl -X PUT "http://localhost:3008/api/projects/proj-123" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'

🔔 Webhooks

Webhook Events

ProjectHub-MCP can send webhooks for various events:

  • project.created
  • project.updated
  • project.completed
  • task.created
  • task.updated
  • task.completed
  • user.invited
  • user.joined

Webhook Payload Example

{
  "event": "task.completed",
  "timestamp": "2025-07-03T19:30:00Z",
  "data": {
    "task": {
      "id": "task-789",
      "title": "Implement authentication",
      "project_id": "proj-123",
      "completed_by": "user-456"
    },
    "project": {
      "id": "proj-123",
      "name": "Website Redesign"
    }
  }
}

🔧 API Testing

Postman Collection

Import our Postman collection for easy API testing:

# Download collection
curl -o projecthub-api.json \
  https://raw.githubusercontent.com/anubissbe/ProjectHub-Mcp/main/docs/api/postman-collection.json

Interactive API Documentation

Access interactive API docs at:

🆘 Need Help?

Last Updated: July 3, 2025 • Version: 4.7.1

⚠️ **GitHub.com Fallback** ⚠️