Skip to main content
This quickstart guide will help you get up and running with the ExpireEye Backend API. You’ll set up the server, create a user account, and make your first authenticated API request.

​
Before you begin

Make sure you have completed the Installation guide and have:
  • Python 3.8+ installed
  • MySQL database running
  • All dependencies installed
  • Environment variables configured

​
Quick setup

1

Start the development server

Navigate to your project directory and activate your virtual environment:
cd ExpireEye-backend
source venv/bin/activate  # On Windows: venv\Scripts\activate
Start the FastAPI server with auto-reload enabled:
uvicorn app.main:app --reload
The server will start on http://localhost:8000 with the API accessible at http://localhost:8000/api.
The --reload flag enables hot reloading, which automatically restarts the server when you make code changes. Perfect for development!
2

Verify the server is running

Open a new terminal window and test the health check endpoint:
curl http://localhost:8000/api/status
You should receive:
{
  "status": "OK",
  "message": "Server Is Running"
}
FastAPI automatically generates interactive API documentation. Visit:These interfaces let you test API endpoints directly from your browser without any additional tools.
3

Create a user account

Register a new user using the signup endpoint:
curl -X POST http://localhost:8000/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "password": "secure_password123",
    "dob": "1990-01-15"
  }'
Expected response:
{
  "message": "User created successfully",
  "userId": "1",
  "email": "[email protected]",
  "dob": "1990-01-15",
  "created_at": "2026-03-04T10:30:45.123456"
}
The password must be at least 6 characters long. In production, use strong passwords with mixed case, numbers, and special characters.
4

Authenticate and get an access token

Log in with your credentials to receive a JWT access token:
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secure_password123"
  }'
Expected response:
{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Save the token value - you’ll need it for all authenticated requests. The token is valid for 10 days by default.
Store the token in an environment variable for easier use:
export ACCESS_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
5

Make your first authenticated request

Now you can make authenticated API calls by including the token in the Authorization header.Let’s add a product to your inventory:
curl -X POST http://localhost:8000/api/product/inventory/add \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "productName": "Organic Whole Milk",
    "category": "Dairy"
  }'
Expected response:
{
  "message": "Product added successfully",
  "productId": "550e8400-e29b-41d4-a716-446655440000",
  "productName": "Organic Whole Milk",
  "category": "Dairy"
}
ExpireEye uses JWT (JSON Web Tokens) for authentication:
  1. All protected endpoints require an Authorization header
  2. The header format is: Authorization: Bearer <your_token>
  3. Tokens contain encoded user information (userId, email)
  4. The backend middleware validates tokens on every request
Public endpoints (no authentication required):
  • POST /api/auth/login
  • POST /api/auth/signup
  • GET /api/status
6

Retrieve your product inventory

Fetch the list of products in the global inventory:
curl -X GET http://localhost:8000/api/product/inventory/list \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Expected response:
{
  "products": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Organic Whole Milk",
      "category": "Dairy",
      "barcode": null,
      "created_at": "2026-03-04T10:35:22.123456"
    }
  ],
  "total": 1
}
You can also filter products by name:
curl -X GET "http://localhost:8000/api/product/inventory/list?name=Milk" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

​
What you just learned

Congratulations! You’ve successfully:
  • Started the ExpireEye Backend server
  • Created a user account
  • Authenticated and received a JWT token
  • Made authenticated API requests
  • Added and retrieved products from the inventory

​
Common API patterns

​
Working with user-specific inventory

Add products to your personal inventory with expiry dates: 
curl -X POST http://localhost:8000/api/product/user/add \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "quantity": 2,
    "expiryDate": "2026-03-15",
    "purchaseDate": "2026-03-04"
  }'

​
Getting notifications

The API includes a notification system for expiring products. Access via WebSocket: 
const ws = new WebSocket(`ws://localhost:8000/api/ws/notification?access_token=${token}`);

ws.onmessage = (event) => {
  const notification = JSON.parse(event.data);
  console.log('Product expiring soon:', notification);
};

​
Uploading images for detection

Use the YOLO detection endpoint to identify products from images: 
curl -X POST http://localhost:8000/api/yolo/detect \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@/path/to/product-image.jpg"

​
Next steps

Now that you’re up and running, explore more features:

​
Troubleshooting

This means your access token is missing, invalid, or expired:
  1. Verify you’re including the Authorization header
  2. Check the token format: Authorization: Bearer <token>
  3. Log in again to get a fresh token if yours has expired
  4. Ensure the SECRET_KEY in .env matches what was used to generate the token
If you see database connection errors:
  1. Verify MySQL is running: mysql -u root -p
  2. Check your .env database credentials
  3. Ensure the database exists: SHOW DATABASES;
  4. Run migrations if needed: alembic upgrade head
Missing Python dependencies:
pip install -r requirements.txt
Make sure your virtual environment is activated before installing.
If port 8000 is occupied, specify a different port:
uvicorn app.main:app --reload --port 8001
Then access the API at http://localhost:8001/api
For more detailed troubleshooting, check the terminal output where uvicorn is running. FastAPI provides helpful error messages and stack traces during development.

Build docs developers (and LLMs) love

Get started for freeTalk to us