API Documentation

Authentication

All API requests require an API key passed in the header:

X-API-Key: your_api_key_here

Register Bot

POST /api/register

Create a new bot account and receive an API key.

Request:

{
  "username": "my-bot",
  "email": "bot@example.com",
  "password": "secure_password"
}

Response:

{
  "message": "Bot registered successfully",
  "user": {
    "id": 2,
    "username": "my-bot",
    "email": "bot@example.com",
    "role": "bot",
    "api_key": "abc123...",
    "created_at": "2024-01-01T00:00:00"
  }
}

Login (Get API Key)

POST /api/login

Get API key for an existing account.

{
  "username": "admin",
  "password": "admin123"
}

List Todos

GET /api/todos

List all todos. Non-admins only see assigned todos.

Query parameters:

status - pending, in_progress, completed
priority - low, medium, high
assigned_to - user ID
created_by - user ID

Get Todo

GET /api/todos/:id

Get a single todo by ID.

Create Todo

POST /api/todos

{
  "title": "Task title",
  "description": "Optional description",
  "deadline": "2024-12-31T23:59:00",
  "priority": "high",
  "status": "pending",
  "assigned_to": 1
}

Only title is required. Deadline uses ISO 8601 format.

Update Todo

PATCH /api/todos/:id

{
  "status": "completed"
}

Non-admins can only update status. Admins can update all fields.

Delete Todo

DELETE /api/todos/:id

Delete a todo. Requires admin or creator access.

List Users

GET /api/users

List all users. Admin only.

Get Current User

GET /api/me

Get info about the authenticated user.

Example: Python Bot

import requests

BASE_URL = "http://localhost:5000"

# Register bot
resp = requests.post(f"{BASE_URL}/api/register", json={
    "username": "my-bot",
    "email": "bot@example.com",
    "password": "secret123"
})
api_key = resp.json()["user"]["api_key"]

# Use API key for all requests
headers = {"X-API-Key": api_key}

# Create a todo
resp = requests.post(f"{BASE_URL}/api/todos", json={
    "title": "Automated task",
    "priority": "high"
}, headers=headers)
print(resp.json())

# List todos
resp = requests.get(f"{BASE_URL}/api/todos", headers=headers)
for todo in resp.json()["todos"]:
    print(f"- {todo['title']} ({todo['status']})")

# Update todo status
todo_id = 1
resp = requests.patch(f"{BASE_URL}/api/todos/{todo_id}", json={
    "status": "completed"
}, headers=headers)

Example: cURL

Register:

curl -X POST http://localhost:5000/api/register \
  -H "Content-Type: application/json" \
  -d '{"username":"bot","email":"bot@test.com","password":"pass123"}'

List todos:

curl http://localhost:5000/api/todos \
  -H "X-API-Key: your_api_key"

Create todo:

curl -X POST http://localhost:5000/api/todos \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"title":"New task","priority":"high"}'

Error Responses

401 Invalid or missing API key

403 Access denied (insufficient permissions)

404 Resource not found

409 Conflict (e.g., username exists)