Skip to main content
Get TaskForge API running locally and make your first authenticated request.

​
Prerequisites

  • Python 3.11+
  • Git
  • curl or any HTTP client (Postman, HTTPie, etc.)

​
Local setup

1

Clone the repository

git clone https://github.com/YamiDarknezz/task-forge-api.git
cd task-forge-api
2

Create a virtual environment

python -m venv venv
source venv/bin/activate
3

Install dependencies

pip install -r requirements.txt
4

Configure environment variables

cp .env.example .env
Open .env and set at minimum:
.env
FLASK_APP=run.py
FLASK_ENV=development
SECRET_KEY=change-me-in-production
JWT_SECRET_KEY=change-me-jwt-in-production
For local development you don’t need to configure Azure SQL. When the AZURE_SQL_* variables are absent, the API automatically falls back to a local SQLite database.
5

Initialize the database

flask init-db
This creates the SQLite database and seeds the default roles (admin and user).
6

Start the API

python run.py
The API is now running at http://localhost:5000. The interactive Swagger UI is available at http://localhost:5000/api/docs.
Visit http://localhost:5000/api/docs to explore and test all endpoints interactively in your browser.
7

Register a user

curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "[email protected]",
    "password": "Password123!",
    "first_name": "Test",
    "last_name": "User"
  }'
Response:
{
  "success": true,
  "data": {
    "id": 1,
    "username": "testuser",
    "email": "[email protected]",
    "first_name": "Test",
    "last_name": "User",
    "is_active": true,
    "role": { "id": 2, "name": "user" },
    "created_at": "2024-01-01T00:00:00"
  },
  "message": "Usuario registrado con exito"
}
8

Login and get tokens

curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "Password123!"
  }'
Response:
{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "testuser",
      "email": "[email protected]",
      "role": { "name": "user" }
    }
  },
  "message": "Inicio de sesion exitoso"
}
Save the access_token — you’ll use it in the Authorization header for all subsequent requests.
9

Create your first task

Replace YOUR_ACCESS_TOKEN with the token from the previous step:
curl -X POST http://localhost:5000/api/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "title": "My first task",
    "description": "Created via the TaskForge API",
    "priority": "high",
    "status": "in_progress",
    "due_date": "2024-12-31T23:59:59"
  }'
Response:
{
  "success": true,
  "data": {
    "id": 1,
    "title": "My first task",
    "description": "Created via the TaskForge API",
    "status": "in_progress",
    "priority": "high",
    "due_date": "2024-12-31T23:59:59",
    "tags": [],
    "created_at": "2024-01-01T00:00:00"
  },
  "message": "Tarea creada con exito"
}

​
Docker alternative

If you prefer Docker, you can skip the Python setup entirely: 
cp .env.example .env
docker-compose up --build
The API will be available at http://localhost:5000 once the container starts. See the Docker guide for details.

​
Next steps

Authentication

Learn about JWT tokens, refresh flow, and RBAC roles.

API Reference

Full documentation for all 26 endpoints.

Configuration

Configure the API for different environments.

Deployment

Deploy to Azure App Service with CI/CD.

Build docs developers (and LLMs) love

Get started for freeTalk to us