API Documentation - AI-Powered PDF Analysis Platform

Version: 1.0.0 Base URL: http://localhost:8000 API Documentation: http://localhost:8000/docs (Swagger UI) Alternative Docs: http://localhost:8000/redoc (ReDoc)

---

Table of Contents

1. Authentication
2. Users
3. Documents
4. Organizations
5. Error Handling
6. Rate Limiting

---

Authentication

All API requests (except registration and login) require authentication using JWT Bearer tokens.

Register a New User

Endpoint: POST /api/v1/auth/register

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "full_name": "John Doe",
  "organization_name": "Acme Corp" // Optional
}

Response (201 Created):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "79c3d962-21db-4c3a-964d-3daf30046cbf",
    "email": "user@example.com",
    "full_name": "John Doe",
    "organization_id": null,
    "organization_name": null,
    "role": "user",
    "tier": "free",
    "is_active": true,
    "is_verified": false,
    "created_at": "2025-11-02T01:42:38.093034",
    "last_login": null
  }
}

Password Requirements:

• Minimum 8 characters
• At least one uppercase letter
• At least one lowercase letter
• At least one digit

Login

Endpoint: POST /api/v1/auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "SecurePass123"
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": { /* user object */ }
}

Token Expiry:

• Access Token: 30 minutes
• Refresh Token: 7 days

Refresh Access Token

Endpoint: POST /api/v1/auth/refresh

Request Body:

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Logout

Endpoint: POST /api/v1/auth/logout

Headers:

Authorization: Bearer <access_token>

Response (200 OK):

{
  "message": "Successfully logged out. Please delete tokens on client side."
}

---

Users

Get Current User Profile

Endpoint: GET /api/v1/users/me

Headers:

Authorization: Bearer <access_token>

Response (200 OK):

{
  "id": "79c3d962-21db-4c3a-964d-3daf30046cbf",
  "email": "user@example.com",
  "full_name": "John Doe",
  "organization_id": null,
  "organization_name": null,
  "role": "user",
  "tier": "free",
  "anthropic_api_key": null,
  "is_active": true,
  "is_verified": true,
  "preferences": {},
  "last_login": "2025-11-02T03:01:26.421263",
  "created_at": "2025-11-02T01:42:38.093034"
}

Update User Profile

Endpoint: PUT /api/v1/users/me

Headers:

Authorization: Bearer <access_token>

Request Body:

{
  "full_name": "John Doe Updated"
}

Response (200 OK):

{
  "id": "79c3d962-21db-4c3a-964d-3daf30046cbf",
  "email": "user@example.com",
  "full_name": "John Doe Updated",
  /* ...other fields... */
}

Update Anthropic API Key

Endpoint: PUT /api/v1/users/me/api-key

Headers:

Authorization: Bearer <access_token>

Request Body:

{
  "anthropic_api_key": "sk-ant-api03-xxxxxxxxxxxxx"
}

Response (200 OK):

{
  "message": "API key updated successfully",
  "masked_key": "sk-ant-api...xxxx"
}

Delete API Key

Endpoint: DELETE /api/v1/users/me/api-key

Headers:

Authorization: Bearer <access_token>

Response (200 OK):

{
  "message": "API key deleted successfully"
}

Get User Statistics

Endpoint: GET /api/v1/users/me/stats

Headers:

Authorization: Bearer <access_token>

Response (200 OK):

{
  "documents_total": 42,
  "documents_processing": 3,
  "documents_completed": 38,
  "documents_failed": 1,
  "storage_used_bytes": 104857600
}

Delete User Account

Endpoint: DELETE /api/v1/users/me

Headers:

Authorization: Bearer <access_token>

Response (204 No Content)

⚠️ Warning: This is a soft delete. Account will be marked inactive and personal data anonymized.

---

Documents

Upload Document

Endpoint: POST /api/v1/documents/upload

Headers:

Authorization: Bearer <access_token>
Content-Type: multipart/form-data

Request Body (Form Data):

file: <PDF file> (max 50MB)

cURL Example:

curl -X POST "http://localhost:8000/api/v1/documents/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@document.pdf"

Response (201 Created):

{
  "id": "b04eb5ba-51b9-4dba-b2e4-a8dab580e6b6",
  "filename": "document.pdf",
  "file_size": 1048576,
  "status": "uploaded",
  "uploaded_at": "2025-11-02T03:10:37.069564",
  "processed_at": null,
  "error_message": null,
  "page_count": null,
  "has_tables": false,
  "user_id": "79c3d962-21db-4c3a-964d-3daf30046cbf"
}

File Requirements:

• Format: PDF only
• Max size: 50MB
• Accepted MIME types: application/pdf

List Documents

Endpoint: GET /api/v1/documents

Headers:

Authorization: Bearer <access_token>

Query Parameters:

• status (optional): Filter by status (uploaded, processing, completed, failed)
• limit (optional, default: 100): Number of results
• offset (optional, default: 0): Pagination offset

Example Request:

GET /api/v1/documents?status=completed&limit=20&offset=0

Response (200 OK):

[
  {
    "id": "b04eb5ba-51b9-4dba-b2e4-a8dab580e6b6",
    "filename": "report.pdf",
    "file_size": 1048576,
    "status": "completed",
    "uploaded_at": "2025-11-02T03:10:37.069564",
    "processed_at": "2025-11-02T03:12:15.123456",
    "error_message": null,
    "page_count": 25,
    "has_tables": true,
    "user_id": "79c3d962-21db-4c3a-964d-3daf30046cbf"
  }
]

Get Document Details

Endpoint: GET /api/v1/documents/{document_id}

Headers:

Authorization: Bearer <access_token>

Response (200 OK):

{
  "id": "b04eb5ba-51b9-4dba-b2e4-a8dab580e6b6",
  "filename": "report.pdf",
  "file_size": 1048576,
  "status": "completed",
  "uploaded_at": "2025-11-02T03:10:37.069564",
  "processed_at": "2025-11-02T03:12:15.123456",
  "error_message": null,
  "page_count": 25,
  "has_tables": true,
  "user_id": "79c3d962-21db-4c3a-964d-3daf30046cbf"
}

Delete Document

Endpoint: DELETE /api/v1/documents/{document_id}

Headers:

Authorization: Bearer <access_token>

Response (204 No Content)

⚠️ Note: This is a soft delete. Document record remains in database with deleted_at timestamp.

---

Organizations

Get Organization Details

Endpoint: GET /api/v1/organizations/me

Headers:

Authorization: Bearer <access_token>

Response (200 OK):

{
  "id": "79c3d962-21db-4c3a-964d-3daf30046cbf",
  "name": "Test User's Workspace",
  "tier": "free",
  "settings": {},
  "member_count": 1,
  "document_count": 0,
  "is_active": true,
  "created_at": "2025-11-02T01:42:38.093034"
}

Get Organization Usage

Endpoint: GET /api/v1/organizations/me/usage

Headers:

Authorization: Bearer <access_token>

Response (200 OK):

{
  "period": {
    "start": "2025-11-01T00:00:00",
    "end": "2025-11-02T03:30:00.123456"
  },
  "usage": {
    "documents_processed": 15,
    "pages_processed": 325,
    "api_calls": 0,
    "tokens_used": 0,
    "storage_bytes": 52428800
  },
  "limits": {
    "documents_per_month": 100,
    "pages_per_month": 1000,
    "api_calls_per_month": 1000,
    "storage_bytes": 1073741824
  },
  "percentage_used": {
    "documents": 15.0,
    "pages": 32.5,
    "api_calls": 0.0,
    "storage": 4.88
  }
}

Get Organization Members

Endpoint: GET /api/v1/organizations/me/members

Headers:

Authorization: Bearer <access_token>

Response (200 OK):

{
  "members": [
    {
      "id": "79c3d962-21db-4c3a-964d-3daf30046cbf",
      "email": "user@test.com",
      "full_name": "Test User",
      "role": "user",
      "is_active": true,
      "joined_at": "2025-11-02T01:42:38.093034"
    }
  ],
  "total": 1
}

---

Error Handling

All errors follow a consistent format:

{
  "detail": "Error message describing what went wrong"
}

HTTP Status Codes

Code	Description
200	OK - Request successful
201	Created - Resource created successfully
204	No Content - Request successful, no response body
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing authentication
403	Forbidden - Authenticated but not authorized
404	Not Found - Resource doesn't exist
413	Payload Too Large - File exceeds size limit
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error
501	Not Implemented - Feature not yet implemented

Common Error Examples

Invalid Credentials (401):

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

Validation Error (422):

{
  "detail": [
    {
      "loc": ["body", "password"],
      "msg": "Password must contain at least one uppercase letter",
      "type": "value_error"
    }
  ]
}

File Too Large (413):

{
  "detail": "File size exceeds maximum allowed size of 50MB"
}

Resource Not Found (404):

{
  "detail": "Document not found"
}

---

Rate Limiting

Current Status: Not implemented

Planned Limits (per tier):

Tier	Requests/Hour	Uploads/Day
Free	100	10
Pro	1000	100
Enterprise	Unlimited	Unlimited

---

Document Processing Status

Documents go through the following lifecycle:

uploaded → processing → completed
                     ↘ failed

Status	Description
uploaded	File uploaded, queued for processing
processing	Currently being analyzed
completed	Processing finished successfully
failed	Processing encountered an error

---

Authentication Best Practices

1. Store tokens securely: Use httpOnly cookies or secure localStorage
2. Refresh tokens proactively: Refresh before access token expires
3. Handle 401 errors: Automatically refresh token or redirect to login
4. Logout properly: Delete tokens from client storage
5. Don't expose tokens: Never log or expose tokens in URLs

---

Testing Credentials

For development and testing:

Email: user@test.com
Password: test123

Email: admin@az1.ai
Password: admin123

⚠️ Warning: These are development credentials only. Never use in production.

---

Support

• Documentation: Project readme
• Issues: GitHub Issues
• Email: 1@az1.ai

---

Last Updated: 2025-11-02 Copyright: © 2025 AZ1.AI Inc. / Coditect.AI - All Rights Reserved