Skip to content

api.md

Latest commit

 

History

History
663 lines (569 loc) · 10.1 KB

api.md

File metadata and controls

663 lines (569 loc) · 10.1 KB
Raw

ChessMate API Documentation

Table of Contents

Authentication

Register

POST /api/register

Register a new user account.

Request Body:

{
  "username": "string",
  "email": "string",
  "password": "string"
}

Response:

{
  "message": "Registration successful! Please check your email to verify your account.",
  "email": "string"
}

Error Responses:

{
  "error": "This email is already registered. Please use a different email or try logging in.",
  "field": "email"
}
{
  "error": "This username is already taken. Please choose a different username.",
  "field": "username"
}

Email Verification

GET /verify-email/{uidb64}/{token}/

Verify email address. Returns HTML pages for success/error.

Success Response:

  • Renders verification_success.html with login button
  • Redirects to frontend login page

Error Response:

  • Renders verification_error.html with error details
  • Provides link to registration page

Login

POST /api/login

Login with email and password.

Request Body:

{
  "email": "string",
  "password": "string"
}

Response:

{
  "message": "Login successful!",
  "tokens": {
    "access": "string",
    "refresh": "string"
  },
  "user": {
    "username": "string",
    "email": "string"
  }
}

Error Responses:

{
  "error": "Please verify your email before logging in."
}
{
  "error": "Invalid email or password."
}

Logout

POST /api/logout

Logout and blacklist the refresh token.

Request Body:

{
  "refresh_token": "string"
}

Response:

{
  "message": "Logout successful!"
}

Request Password Reset

POST /api/auth/password-reset

Request a password reset link.

Request Body:

{
  "email": "string"
}

Response:

{
  "message": "Password reset link has been sent to your email."
}

Error Response:

{
  "error": "Email is required."
}

Reset Password

POST /api/auth/password-reset/confirm

Reset password using the token from the email link.

Request Body:

{
  "uid": "string",
  "token": "string",
  "new_password": "string"
}

Response:

{
  "message": "Password has been reset successfully."
}

Error Responses:

{
  "error": "Invalid or expired reset link."
}
{
  "error": "All fields are required."
}

Games

Fetch Games

POST /api/games/fetch

Fetch games from Chess.com or Lichess.

Request Headers:

Authorization: Bearer <access_token>

Request Body:

{
  "platform": "chess.com | lichess",
  "username": "string",
  "game_mode": "all | bullet | blitz | rapid | classical",
  "num_games": "integer"
}

Response:

{
  "message": "Successfully fetched and saved games!",
  "games_saved": "integer",
  "credits_deducted": "integer",
  "credits_remaining": "integer",
  "games": [
    {
      "id": "integer",
      "platform": "string",
      "white": "string",
      "black": "string",
      "opponent": "string",
      "result": "string",
      "date_played": "datetime",
      "opening_name": "string",
      "game_id": "string"
    }
  ]
}

Get User Games

GET /api/games/user

Get list of games for the authenticated user.

Request Headers:

Authorization: Bearer <access_token>

Query Parameters:

platform: all | chess.com | lichess (optional)

Response:

{
  "games": [
    {
      "id": "integer",
      "white": "string",
      "black": "string",
      "result": "string",
      "date_played": "datetime",
      "platform": "string",
      "analysis": "object | null"
    }
  ]
}

Analysis

Analyze Game

GET/POST /api/analysis/{game_id}

Analyze a specific game.

Request Headers:

Authorization: Bearer <access_token>

Request Body (POST only):

{
  "depth": "integer (optional, default: 20)",
  "use_ai": "boolean (optional, default: true)"
}

Response:

{
  "message": "Analysis completed successfully!",
  "analysis": {
    "moves": [
      {
        "move_number": "integer",
        "move": "string",
        "score": "float",
        "is_mistake": "boolean",
        "is_blunder": "boolean",
        "time_spent": "float"
      }
    ]
  },
  "feedback": {
    "opening": {
      "accuracy": "float",
      "played_moves": ["string"],
      "suggestions": ["string"]
    },
    "tactics": {
      "missed_opportunities": ["string"],
      "suggestions": ["string"]
    },
    "mistakes": "integer",
    "blunders": "integer",
    "inaccuracies": "integer",
    "time_management": {
      "time_pressure_moves": ["integer"],
      "suggestions": ["string"]
    },
    "strengths": [
      {
        "area": "string",
        "description": "string"
      }
    ],
    "improvement_areas": [
      {
        "area": "string",
        "description": "string"
      }
    ],
    "ai_suggestions": "string | object"
  },
  "credits_remaining": "integer"
}

Batch Analysis

POST /api/analysis/batch

Analyze multiple games.

Request Headers:

Authorization: Bearer <access_token>

Request Body:

{
  "num_games": "integer",
  "use_ai": "boolean (optional, default: true)",
  "depth": "integer (optional, default: 20)"
}

Response:

{
  "message": "Batch analysis completed!",
  "results": {
    "individual_games": {
      "game_id": {
        "blunders": "integer",
        "mistakes": "integer",
        "inaccuracies": "integer",
        "opening": {
          "accuracy": "float",
          "played_moves": ["string"]
        },
        "time_management": {
          "time_pressure_moves": ["integer"]
        }
      }
    },
    "overall_stats": {
      "total_games": "integer",
      "wins": "integer",
      "losses": "integer",
      "draws": "integer",
      "average_accuracy": "float",
      "common_mistakes": {
        "blunders": "float",
        "mistakes": "float",
        "inaccuracies": "float",
        "time_pressure": "float"
      },
      "improvement_areas": [
        {
          "area": "string",
          "description": "string"
        }
      ],
      "strengths": [
        {
          "area": "string",
          "description": "string"
        }
      ]
    },
    "dynamic_feedback": "string | object"
  }
}

Dashboard

Get Dashboard Data

GET /api/dashboard

Get user-specific games and statistics for the dashboard.

Request Headers:

Authorization: Bearer <access_token>

Response:

{
  "total_games": "integer",
  "analyzed_games": "integer",
  "unanalyzed_games": "integer",
  "statistics": {
    "wins": "integer",
    "losses": "integer",
    "draws": "integer",
    "win_rate": "float"
  },
  "recent_games": [
    {
      "id": "integer",
      "platform": "string",
      "white": "string",
      "black": "string",
      "opponent": "string",
      "result": "string",
      "date_played": "datetime",
      "opening_name": "string",
      "analysis": "object | null"
    }
  ]
}

Credits

Get Credits

GET /api/credits

Get current credit balance.

Request Headers:

Authorization: Bearer <access_token>

Response:

{
  "credits": "integer"
}

Purchase Credits

POST /api/credits/purchase

Create a checkout session for credit purchase.

Request Headers:

Authorization: Bearer <access_token>

Request Body:

{
  "package_id": "string"
}

Response:

{
  "success": true,
  "checkout_url": "string",
  "session_id": "string"
}

Confirm Purchase

POST /api/credits/confirm

Confirm credit purchase and add credits.

Request Headers:

Authorization: Bearer <access_token>

Request Body:

{
  "session_id": "string"
}

Response:

{
  "success": true,
  "credits": "integer",
  "added_credits": "integer"
}

User Management

Get Profile

GET /api/profile

Get the authenticated user's profile information.

Request Headers:

Authorization: Bearer <access_token>

Response:

{
  "username": "string",
  "email": "string",
  "rating": "integer",
  "credits": "integer",
  "preferences": {
    "emailNotifications": "boolean",
    "darkMode": "boolean",
    "autoAnalyze": "boolean"
  },
  "created_at": "datetime",
  "games_analyzed": "integer"
}

Update Profile

PATCH /api/profile

Update the authenticated user's profile information.

Request Headers:

Authorization: Bearer <access_token>

Request Body:

{
  "username": "string (optional)",
  "preferences": {
    "emailNotifications": "boolean (optional)",
    "darkMode": "boolean (optional)",
    "autoAnalyze": "boolean (optional)"
  }
}

Response:

{
  "message": "Profile updated successfully.",
  "username": "string",
  "preferences": {
    "emailNotifications": "boolean",
    "darkMode": "boolean",
    "autoAnalyze": "boolean"
  }
}

Error Responses:

{
  "error": "Username already taken."
}

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": "Error message describing the issue"
}

401 Unauthorized

{
  "error": "Authentication credentials were not provided"
}

403 Forbidden

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

404 Not Found

{
  "error": "Requested resource not found"
}

500 Internal Server Error

{
  "error": "Internal server error occurred",
  "details": "Optional error details"
}

Rate Limiting

Most endpoints are rate-limited to prevent abuse. The current limits are:

  • Authentication endpoints: 5 requests per minute
  • Game fetching: 10 requests per minute
  • Analysis endpoints: 3 requests per minute
  • Credit operations: 5 requests per minute

When rate limit is exceeded, you'll receive a 429 Too Many Requests response:

{
  "error": "Too many requests. Please try again later."
}