Bithaka API Documentation

Welcome to the pre-production version of our documentation. Please note that these materials are still under review and may contain errors or missing information.

Important: All API endpoints require an API key for authentication. If you haven't received your test API key, please contact the project manager.

If you notice any issues or have suggestions, we'd love to hear from you! Please contact us at [email protected]

Thank you for helping us improve!

Base URL

Contact the project manager for the base URL.

Authentication Header

All requests must include your API key in the header (contact the project manager for your API key):

X-API-Key: your_api_key_here

Authentication

Social Authentication

Google

Method: POST
Endpoint: /api/auth/google/
Content-Type: application/json
Request Body:

{
    "idToken": "google-id-token-from-sdk"
}

Register

Method: POST
Endpoint: /api/auth/register/
Content-Type: application/json
Request Body:

{
    "email": "[email protected]",
    "first_name": "Test",
    "last_name": "Test",
    "password": "securepass123",
    "password_confirm": "securepass123",
    "phone_number": "1234567890",
    "address": "123 Test St",
    "postal_code": "12345"
}

Login

Method: POST
Endpoint: /api/auth/login/
Content-Type: application/json
Request Body:

{
    "email": "[email protected]",
    "password": "securepass123"
}

Logout

Method: POST
Endpoint: /api/auth/logout/
Authorization: Bearer Token, X-API-Key
Request Body:

{
    "refresh_token": ""
}

Logout All

Method: POST
Endpoint: /api/auth/logout-all/
Authorization: Bearer Token, X-API-Key

Token Refresh

Method: POST
Endpoint: /api/auth/token/refresh/
Content-Type: application/json
Request Body:

{
    "refresh": "your_refresh_token_here"
}

Email Verification

Verify Email

Method: POST
Endpoint: /api/auth/email/verify/
Content-Type: application/json
Request Body:

{
    "token": "verification_token_here"
}

Resend Verification Email

Method: POST
Endpoint: /api/auth/email/resend/
Authorization: Bearer Token

Password Management

Change Password

Method: POST
Endpoint: /api/auth/password/change/
Authorization: Bearer Token, X-API-Key
Content-Type: application/json
Request Body:

{
    "old_password": "current_password",
    "new_password": "new_password",
    "new_password_confirm": "new_password"
}

Request Password Reset

Method: POST
Endpoint: /api/auth/password/reset/request/
Content-Type: application/json
Request Body:

{
    "email": "[email protected]"
}

Reset Password

Method: POST
Endpoint: /api/auth/password/reset/confirm/
Content-Type: application/json
Request Body:

{
    "token": "reset_token_here",
    "new_password": "new_password",
    "new_password_confirm": "new_password"
}

Profile Management

Get My Profile

Method: GET
Endpoint: /api/profile/me/
Authorization: Bearer Token, X-API-Key

Update Profile

Method: PUT
Endpoint: /api/profile/me/
Authorization: Bearer Token, X-API-Key
Content-Type: application/json
Request Body:

{
    "first_name": "Updated",
    "last_name": "samir",
    "phone_number": "9876543210",
    "bio": "Updated bio",
    "address": "456 New St",
    "postal_code": "54321"
}

Profile Picture Management

Upload Profile Picture

Method: POST
Endpoint: /api/profile/me/picture/
Authorization: Bearer Token, X-API-Key
Content-Type: multipart/form-data
Form Data:
- picture: [file]

Get Profile Picture

Method: GET
Endpoint: /api/profile/me/picture/
Authorization: Bearer Token

Delete Profile Picture

Method: DELETE
Endpoint: /api/profile/me/picture/
Authorization: Bearer Token, X-API-Key

Get User Profile By ID

Method: GET
Endpoint: /api/profile/users/{user_id}/
Authorization: Bearer Token, X-API-Key

Update Profile Settings

Method: PATCH
Endpoint: /api/profile/me/settings/
Authorization: Bearer Token, X-API-Key
Content-Type: application/json
Request Body:

{
    "settings": {
        "notification_preferences": {},
        "ui_preferences": {},
        "language": "ar"
    }
}

Delete Account

Method: DELETE
Endpoint: /api/profile/me/delete/
Authorization: Bearer Token, X-API-Key
Content-Type: application/json
Request Body:

{
    "password": "securepass123",
    "confirmation": "securepass123"
}

Subscription Management

Get Current Subscription

Method: GET
Endpoint: /api/subscriptions/current/
Authorization: Bearer Token, X-API-Key

Change Subscription

Method: POST
Endpoint: /api/subscriptions/change/
Authorization: Bearer Token, X-API-Key
Content-Type: application/json
Request Body:

{
    "subscription_type": "TERM"
}

Cancel Subscription

Method: POST
Endpoint: /api/subscriptions/cancel/{user_id}/
Authorization: Bearer Token, X-API-Key

Get Subscription Status

Method: GET
Endpoint: /api/subscriptions/status/
Authorization: Bearer Token, X-API-Key

RAG (Retrieval-Augmented Generation)

RAG Query

Method: POST
Endpoint: /api/rag/query/
Authorization: Bearer Token, X-API-Key
Content-Type: application/json
Request Body:

{
    "query": "What is addition?",
    "grade": "1"
}

Payment Management

Initiate Payment

Initiates a new payment for a subscription upgrade.

Endpoint

POST /api/payment/initiate/

Authentication

Required
Bearer Token Authentication

Request Body

{
    "subscription_type": string  // Required: "TERM" | "SEMESTER" | "YEAR"
}

Response

Success Response (200 OK)

{
    "status": "success",
    "payment_id": "uuid-string",
    "subscription_details": {
        "id": "uuid-string",
        "type": "string",
        "amount": "string",
        "currency": "string"
    },
    "redirect_url": "string"  // URL to payment gateway
}

Error Responses

Bad Request (400)

{
    "status": "error",
    "message": "Subscription type is required"
}

{
    "status": "error",
    "message": "Invalid subscription type. Must be TERM, SEMESTER, or YEAR"
}

Server Error (500)

{
    "status": "error",
    "message": "string",
    "details": "An unexpected error occurred during payment initiation"
}

Example Usage

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subscription_type": "TERM"}' \
  https://api.example.com/api/payment/initiate/

Check Payment Status

Retrieves the current status of a payment.

Endpoint

GET /api/payment/status/{payment_id}/

Authentication

Required
Bearer Token Authentication

URL Parameters

payment_id: UUID of the payment (required)

Response

Success Response (200 OK)

{
    "status": "success",
    "payment_details": {
        "payment_id": "uuid-string",
        "order_id": "string",
        "amount": "string",
        "status": "string",
        "created_at": "datetime"
    },
    "user_details": {
        "user_id": "uuid-string",
        "email": "string",
        "name": "string"
    },
    "subscription_details": {
        "id": "uuid-string",
        "type": "string",
        "start_date": "datetime",
        "end_date": "datetime",
        "status": "string"
    },
    "payment_status": {
        "is_successful": boolean,
        "status": "string",
        "message": "string"
    },
    "response_data": {}  // Additional payment gateway response data
}

Error Responses

Bad Request (400)

{
    "status": "error",
    "message": "Invalid payment ID format"
}

Not Found (404)

{
    "status": "error",
    "message": "Payment not found"
}

Server Error (500)

{
    "status": "error",
    "message": "string",
    "details": "An unexpected error occurred while checking payment status"
}

Example Usage

curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.example.com/api/payment/status/123e4567-e89b-12d3-a456-426614174000/

Notes

Payment statuses include: "PENDING", "SUCCESS", "FAILED"
Subscription types and their durations:
- TERM: 120 days (4 months)
- SEMESTER: 180 days (6 months)
- YEAR: 365 days (1 year)
A successful payment automatically activates the new subscription
Any existing active subscription will be cancelled when a new subscription is activated

Advanced