API Reference

The LinguaAI API is a RESTful HTTP API built with FastAPI. All endpoints are served under the /api prefix.

Base URL

http://<host>:8000

During local development the host is typically 127.0.0.1 or the LAN IP configured in frontend/lib/services/api_config.dart.

Interactive Documentation

FastAPI automatically generates interactive documentation:

  • Swagger UI — http://<host>:8000/docs

  • ReDoc — http://<host>:8000/redoc

  • OpenAPI JSON — http://<host>:8000/openapi.json

Authentication

Protected endpoints require a JWT access token sent as a Bearer token in the Authorization header:

GET /api/auth/me HTTP/1.1
Authorization: Bearer <access_token>

Tokens are obtained from the login, signup, or Google OAuth endpoints and expire after 24 hours. Use POST /api/auth/refresh to obtain a new token before expiry.

Response Format

All responses use application/json.

Successful response example:

{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "full_name": "Jane Doe",
    "avatar_url": null,
    "provider": "email",
    "proficiency_level": "Intermediate",
    "goals": ["Education"],
    "focus_areas": ["Reading", "Writing"],
    "created_at": "2026-03-06T12:00:00Z"
  }
}

Error response example:

{
  "detail": "Invalid email or password"
}

HTTP Status Codes

Code

Meaning

200

Request succeeded

201

Resource created (e.g. new user on signup)

400

Bad request — invalid input or business logic error

401

Unauthorised — missing, expired, or invalid token

422

Validation error — request body failed Pydantic validation

500

Internal server error

General Endpoints

Method

Path

Description

GET

/

Returns the root HTML welcome page

GET

/health

Database connectivity health check

Available Modules