API Overview

Overview of all TaskForge API endpoints, authentication, base URLs, and conventions.

Base URL

Environment	Base URL
Production	https://task-forge-gbd6h8gtg8hchve9.chilecentral-01.azurewebsites.net
Local development	http://localhost:5000

All endpoints are prefixed with /api. For example, the login endpoint is available at /api/auth/login.

Authentication

All endpoints except POST /api/auth/register, POST /api/auth/login, and GET /api/health require a valid JWT access token in the Authorization header.

Authorization: Bearer <access_token>

The refresh endpoint (POST /api/auth/refresh) is an exception — it accepts a refresh token instead of an access token.

Tokens are issued by the login endpoint. Access tokens are short-lived; use refresh tokens to obtain new access tokens without re-authenticating.

Request format

All request bodies must be JSON. Set the Content-Type header accordingly.

Content-Type: application/json

Response envelope

All responses follow a consistent envelope structure.

Success:

{
  "success": true,
  "data": { ... },
  "message": "Optional human-readable message"
}

Error:

{
  "success": false,
  "message": "Description of what went wrong"
}

HTTP status codes reflect the outcome: 2xx for success, 4xx for client errors, 5xx for server errors.

Pagination

List endpoints accept the following query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
per_page	integer	20	Results per page
sort_by	string	varies	Field to sort by
sort_order	string	asc	Sort direction: asc or desc

Paginated responses include a pagination object in the response data:

{
  "success": true,
  "data": {
    "items": [ ... ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 150,
      "pages": 8,
      "has_next": true,
      "has_prev": false
    }
  }
}

Endpoint reference

Authentication

Method	Path	Auth required	Description
POST	/api/auth/register	None	Create a new user account
POST	/api/auth/login	None	Authenticate and receive tokens
POST	/api/auth/refresh	Refresh token	Get a new access token
POST	/api/auth/logout	Access token	Revoke a refresh token
GET	/api/auth/me	Access token	Get the authenticated user’s profile
POST	/api/auth/change-password	Access token	Change the authenticated user’s password

Tasks

Method	Path	Auth required	Role	Description
GET	/api/tasks	Access token	Any	List tasks for the current user
GET	/api/tasks/{id}	Access token	Any	Get a specific task
POST	/api/tasks	Access token	Any	Create a new task
PUT	/api/tasks/{id}	Access token	Any	Update a task
DELETE	/api/tasks/{id}	Access token	Any	Delete a task
POST	/api/tasks/{id}/complete	Access token	Any	Mark a task as complete
GET	/api/tasks/statistics	Access token	Any	Get task statistics
GET	/api/tasks/export	Access token	Any	Export tasks

Users

Method	Path	Auth required	Role	Description
GET	/api/users	Access token	Admin	List all users
GET	/api/users/{id}	Access token	Any	Get a specific user
PUT	/api/users/{id}	Access token	Any	Update a user
DELETE	/api/users/{id}	Access token	Admin	Delete a user
POST	/api/users/{id}/activate	Access token	Admin	Activate a user account
POST	/api/users/{id}/deactivate	Access token	Admin	Deactivate a user account

Tags

Method	Path	Auth required	Role	Description
GET	/api/tags	Access token	Any	List all tags
GET	/api/tags/{id}	Access token	Any	Get a specific tag
POST	/api/tags	Access token	Any	Create a new tag
PUT	/api/tags/{id}	Access token	Admin	Update a tag
DELETE	/api/tags/{id}	Access token	Admin	Delete a tag

Health

Method	Path	Auth required	Description
GET	/api/health	None	Check API health status