📡 API Reference

Base URL

http://localhost:8000/api

All API requests require authentication unless otherwise specified. Include your token in the Authorization header.

Authentication Endpoints

Register User

Create a new user account.

POST /api/auth/register

Request Body:

Field	Type	Required	Description
username	string	Yes	Unique username
email	string	Yes	User email address
password	string	Yes	User password (min 8 characters)
first_name	string	No	User's first name
last_name	string	No	User's last name

Example:

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "securePassword123",
  "first_name": "John",
  "last_name": "Doe"
}

{
  "id": 1,
  "username": "johndoe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}

Authenticate and receive a token.

POST /api/auth/login

Request Body:

Field	Type	Required	Description
username	string	Yes	User's username
password	string	Yes	User's password

Example:

{
  "username": "johndoe",
  "password": "securePassword123"
}

{
  "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b",
  "user": {
    "id": 1,
    "username": "johndoe",
    "email": "john@example.com"
  }
}

Task Endpoints

List Tasks

Get all tasks for the authenticated user.

GET /api/tasks

Headers:

Authorization: Token {your_token}

Query Parameters:

Parameter	Type	Description
completed	boolean	Filter by completion status
search	string	Search in title and description
ordering	string	Sort by field (e.g., `-created_at`)

Response:

[
  {
    "id": 1,
    "title": "Complete project documentation",
    "description": "Write comprehensive API docs",
    "completed": false,
    "priority": "high",
    "due_date": "2025-11-15",
    "created_at": "2025-11-12T10:00:00Z",
    "updated_at": "2025-11-12T10:00:00Z",
    "user": 1
  },
  {
    "id": 2,
    "title": "Review pull requests",
    "description": "Check pending PRs",
    "completed": true,
    "priority": "medium",
    "due_date": null,
    "created_at": "2025-11-11T09:00:00Z",
    "updated_at": "2025-11-12T08:30:00Z",
    "user": 1
  }
]

Get Task

Retrieve a specific task by ID.

GET /api/tasks/{id}

Response:

{
  "id": 1,
  "title": "Complete project documentation",
  "description": "Write comprehensive API docs",
  "completed": false,
  "priority": "high",
  "due_date": "2025-11-15",
  "created_at": "2025-11-12T10:00:00Z",
  "updated_at": "2025-11-12T10:00:00Z",
  "user": 1
}

Create Task

Create a new task.

POST /api/tasks

Request Body:

Field	Type	Required	Description
title	string	Yes	Task title
description	string	No	Task description
completed	boolean	No	Completion status (default: false)
priority	string	No	Priority: low, medium, high
due_date	string	No	Due date (ISO 8601 format)

Example:

{
  "title": "Implement user authentication",
  "description": "Add JWT authentication to the API",
  "priority": "high",
  "due_date": "2025-11-20"
}

{
  "id": 3,
  "title": "Implement user authentication",
  "description": "Add JWT authentication to the API",
  "completed": false,
  "priority": "high",
  "due_date": "2025-11-20",
  "created_at": "2025-11-12T11:00:00Z",
  "updated_at": "2025-11-12T11:00:00Z",
  "user": 1
}

Update Task

Update an existing task.

PUT /api/tasks/{id}
PATCH /api/tasks/{id}

Use PUT for full updates (all fields required) or PATCH for partial updates (only changed fields).

Request Body (PATCH):

{
  "completed": true,
  "priority": "low"
}

Response:

{
  "id": 1,
  "title": "Complete project documentation",
  "description": "Write comprehensive API docs",
  "completed": true,
  "priority": "low",
  "due_date": "2025-11-15",
  "created_at": "2025-11-12T10:00:00Z",
  "updated_at": "2025-11-12T14:30:00Z",
  "user": 1
}

Delete Task

Delete a task.

DELETE /api/tasks/{id}

Response:

204 No Content

User Endpoints

Get Current User

Get the authenticated user's profile.

GET /api/users/me

Response:

{
  "id": 1,
  "username": "johndoe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "date_joined": "2025-11-01T10:00:00Z"
}

Update User Profile

Update the authenticated user's profile.

PATCH /api/users/me

Request Body:

{
  "first_name": "Jonathan",
  "email": "jonathan@example.com"
}

Error Responses

All endpoints may return the following error responses:

400 Bad Request

Invalid request data.

{
  "error": "Invalid data",
  "details": {
    "title": ["This field is required."]
  }
}

401 Unauthorized

Missing or invalid authentication.

{
  "detail": "Authentication credentials were not provided."
}

403 Forbidden

Insufficient permissions.

{
  "detail": "You do not have permission to perform this action."
}

404 Not Found

Resource not found.

{
  "detail": "Not found."
}

500 Internal Server Error

Server error.

{
  "error": "Internal server error",
  "message": "An unexpected error occurred."
}

Rate Limiting

API rate limiting is not currently implemented. Consider adding rate limiting for production use.

Pagination

List endpoints support pagination:

Query Parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
page_size	integer	20	Items per page

Example:

GET /api/tasks?page=2&page_size=10

Response:

{
  "count": 45,
  "next": "http://localhost:8000/api/tasks?page=3",
  "previous": "http://localhost:8000/api/tasks?page=1",
  "results": [...]
}

Next Steps

Check out Examples for complete integration examples
Learn about Authentication best practices

📡 API Reference

On this page