Task API endpoints

Task endpoints live under /api/tasks and are routed to the task service. All five endpoints require a valid Bearer token from a verified account. If your account has not yet been verified by an admin, you will receive 403 Forbidden on every request to this group. See the authentication guide for details on obtaining and using tokens.

Completed tasks are immutable. Sending a PUT request to a task with status: "completed" returns a 400 error. Update the task’s other fields before marking it as completed, or create a new task.

Create a task

POST /api/tasks Creates a new task owned by the authenticated user.

Headers

Authorization

string

required

Bearer <token> — JWT from a verified account.

Body parameters

title

string

required

Task title. Between 3 and 100 characters.

description

string

Optional description. Maximum 1000 characters.

status

string

default:"pending"

Task status. One of pending, in-progress, or completed.

priority

string

default:"medium"

Task priority. One of low, medium, or high.

dueDate

string

ISO 8601 date string (e.g., 2025-12-31T00:00:00.000Z).

Example

curl --request POST \
  --url http://localhost:5000/api/tasks \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Write integration tests",
    "description": "Cover the auth and task service endpoints.",
    "priority": "high",
    "dueDate": "2025-12-31T00:00:00.000Z"
  }'

{
  "success": true,
  "message": "Task created successfully",
  "data": {
    "_id": "664a1f2e8b1c2d3e4f5a6b7c",
    "title": "Write integration tests",
    "description": "Cover the auth and task service endpoints.",
    "status": "pending",
    "priority": "high",
    "dueDate": "2025-12-31T00:00:00.000Z",
    "isVerifiedByAdmin": false,
    "createdAt": "2025-05-01T10:00:00.000Z",
    "updatedAt": "2025-05-01T10:00:00.000Z"
  }
}

List tasks

GET /api/tasks Returns a paginated, filterable list of tasks owned by the authenticated user.

Headers

Authorization

string

required

Bearer <token> — JWT from a verified account.

Query parameters

status

string

Filter by status. One of pending, in-progress, or completed.

priority

string

Filter by priority. One of low, medium, or high.

page

number

default:"1"

Page number for pagination.

limit

number

default:"10"

Number of tasks per page. Maximum 100.

sortBy

string

default:"createdAt"

Field to sort by. One of createdAt, updatedAt, dueDate, priority, or title.

order

string

default:"desc"

Sort direction. One of asc or desc.

Example

curl --request GET \
  --url 'http://localhost:5000/api/tasks?status=in-progress&priority=high&sortBy=dueDate&order=asc&page=1&limit=5' \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "success": true,
  "message": "Tasks retrieved successfully",
  "data": [
    {
      "_id": "664a1f2e8b1c2d3e4f5a6b7c",
      "title": "Write integration tests",
      "status": "in-progress",
      "priority": "high",
      "dueDate": "2025-12-31T00:00:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 5,
    "totalPages": 1
  }
}

Get a task

GET /api/tasks/:id Returns a single task by ID. The task must belong to the authenticated user.

Headers

Authorization

string

required

Bearer <token> — JWT from a verified account.

Path parameters

string

required

The task’s unique identifier.

Example

curl --request GET \
  --url http://localhost:5000/api/tasks/664a1f2e8b1c2d3e4f5a6b7c \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "success": true,
  "message": "Task retrieved successfully",
  "data": {
    "_id": "664a1f2e8b1c2d3e4f5a6b7c",
    "title": "Write integration tests",
    "description": "Cover the auth and task service endpoints.",
    "status": "in-progress",
    "priority": "high",
    "dueDate": "2025-12-31T00:00:00.000Z",
    "isVerifiedByAdmin": true,
    "createdAt": "2025-05-01T10:00:00.000Z",
    "updatedAt": "2025-05-10T14:23:00.000Z"
  }
}

Update a task

PUT /api/tasks/:id Updates one or more fields on an existing task. All body fields are optional. The task must belong to the authenticated user and must not already be in completed status.

Headers

Authorization

string

required

Bearer <token> — JWT from a verified account.

Path parameters

string

required

The task’s unique identifier.

Body parameters

title

string

Updated task title. Between 3 and 100 characters.

description

string

Updated description. Maximum 1000 characters.

status

string

Updated status. One of pending, in-progress, or completed.

priority

string

Updated priority. One of low, medium, or high.

dueDate

string

Updated due date as an ISO 8601 string.

Example

curl --request PUT \
  --url http://localhost:5000/api/tasks/664a1f2e8b1c2d3e4f5a6b7c \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "completed"
  }'

{
  "success": true,
  "message": "Task updated successfully",
  "data": {
    "_id": "664a1f2e8b1c2d3e4f5a6b7c",
    "title": "Write integration tests",
    "status": "completed",
    "priority": "high",
    "updatedAt": "2025-05-15T09:00:00.000Z"
  }
}

Delete a task

DELETE /api/tasks/:id Permanently deletes a task. The task must belong to the authenticated user.

Headers

Authorization

string

required

Bearer <token> — JWT from a verified account.

Path parameters

string

required

The task’s unique identifier.

Example

curl --request DELETE \
  --url http://localhost:5000/api/tasks/664a1f2e8b1c2d3e4f5a6b7c \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

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

Overview

Endpoints

Task API endpoints

Create a task

Headers

Body parameters

Example

List tasks

Headers

Query parameters

Example

Get a task

Headers

Path parameters

Example

Update a task

Headers

Path parameters

Body parameters

Example

Delete a task

Headers

Path parameters

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Create a task

​Headers

​Body parameters

​Example

​List tasks

​Headers

​Query parameters

​Example

​Get a task

​Headers

​Path parameters

​Example

​Update a task

​Headers

​Path parameters

​Body parameters

​Example

​Delete a task

​Headers

​Path parameters

​Example

Build docs developers (and LLMs) love

Create a task

Headers

Body parameters

Example

List tasks

Headers

Query parameters

Example

Get a task

Headers

Path parameters

Example

Update a task

Headers

Path parameters

Body parameters

Example

Delete a task

Headers

Path parameters

Example