PDeck API Reference for MVP

This document outlines the core APIs that should be implemented for the Minimum Viable Product (MVP) of PDeck. These endpoints cover the essential functionalities required for the basic operation of the task management and prioritization system.

Base URL

All API requests should be prefixed with:

https://api.pdeck.com/v1

Authentication

All API endpoints require authentication. Use Bearer token authentication by including an Authorization header in your requests:

Authorization: Bearer <your_access_token>

Endpoints

User Management

Register User

• POST /users/register
• Body:

  {
    "email": "user@example.com",
    "password": "securepassword",
    "name": "John Doe"
  }
• Response: User object with token

Login

• POST /users/login
• Body:

  {
    "email": "user@example.com",
    "password": "securepassword"
  }
• Response: User object with token

Task Management

Create Task

• POST /tasks
• Body:

  {
    "title": "Complete project proposal",
    "description": "Draft and finalize the project proposal for client X",
    "dueDate": "2023-07-15T00:00:00Z",
    "priority": 1
  }
• Response: Created task object

Get All Tasks

• GET /tasks
• Query Parameters:
  • sort: (optional) Sort order (e.g., "priority", "dueDate")
  • filter: (optional) Filter criteria (e.g., "high", "medium", "low")
• Response: Array of task objects

Get Task by ID

• GET /tasks/{taskId}
• Response: Task object

Update Task

• PUT /tasks/{taskId}
• Body: Task object with fields to update
• Response: Updated task object

Delete Task

• DELETE /tasks/{taskId}
• Response: Success message

Update Task Priority

• PATCH /tasks/{taskId}/priority
• Body:

  {
    "priority": 2
  }
• Response: Updated task object

Task Prioritization

Get Prioritized Task List

• GET /tasks/prioritized
• Response: Array of prioritized task objects

Trigger Reprioritization

• POST /tasks/reprioritize
• Response: Success message

External Integrations

List Available Integrations

• GET /integrations
• Response: Array of available integration objects

Add Integration

• POST /integrations/{integrationType}
• Body: Integration-specific authentication data
• Response: Created integration object

Remove Integration

• DELETE /integrations/{integrationId}
• Response: Success message

Trigger Integration Sync

• POST /integrations/{integrationId}/sync
• Response: Sync status object

User Preferences

Get User Preferences

• GET /users/preferences
• Response: User preferences object

Update User Preferences

• PUT /users/preferences
• Body: User preferences object
• Response: Updated user preferences object

Error Handling

All endpoints should return appropriate HTTP status codes and error messages in case of failures. A typical error response should look like:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource could not be found."
  }
}

Rate Limiting

API requests are rate-limited to 100 requests per minute per user. The response headers will include:

• X-RateLimit-Limit: The number of allowed requests in the current period
• X-RateLimit-Remaining: The number of remaining requests in the current period

Pagination

For endpoints that return arrays (e.g., /tasks), use cursor-based pagination with the following query parameters:

• limit: Number of items to return (default: 20, max: 100)
• cursor: Cursor for the next page of results

The response will include a next_cursor field if there are more results available.

Webhooks

For real-time updates, PDeck will send webhooks to registered endpoints. Implement an endpoint in your application to receive these updates:

• POST https://your-app.com/pdeck-webhook
• Body: Event object containing the type of update and relevant data

Register your webhook URL in the PDeck dashboard after implementation.