API Endpoints Documentation

AI-Powered PDF Analysis Platform

Copyright © 2025 AZ1.AI Inc. / Coditect.AI - All Rights Reserved

Table of Contents

• Authentication
• Users
• Organizations
• Documents
• Processing Jobs
• Analysis Results
• WebSocket
• Health & Status

---

Base URL

Production:  https://api.pdfanalysis.az1.ai
Staging:     https://staging-api.pdfanalysis.az1.ai
Development: http://localhost:8000

Authentication

All API endpoints (except /auth/login, /auth/register, /health) require authentication using JWT tokens.

Headers

Authorization: Bearer <access_token>

Token Refresh

Access tokens expire after 30 minutes. Use the refresh token to obtain a new access token.

---

Endpoints

Authentication

POST /api/v1/auth/register

Register a new user account.

Request:

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "full_name": "John Doe",
  "organization_name": "Acme Inc."
}

Response: 201 Created

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "full_name": "John Doe",
    "role": "user",
    "tier": "free",
    "is_active": true,
    "created_at": "2025-01-01T00:00:00Z"
  }
}

Errors:

• 400 Bad Request - Invalid input or email already exists
• 422 Unprocessable Entity - Validation error

---

POST /api/v1/auth/login

Authenticate user and receive tokens.

Request:

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

Response: 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "full_name": "John Doe",
    "organization_id": "660e8400-e29b-41d4-a716-446655440000",
    "organization_name": "Acme Inc.",
    "role": "user",
    "tier": "pro",
    "is_active": true,
    "last_login": "2025-01-01T00:00:00Z"
  }
}

Errors:

• 401 Unauthorized - Invalid credentials
• 403 Forbidden - Account disabled

---

POST /api/v1/auth/refresh

Refresh access token using refresh token.

Request:

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

Response: 200 OK

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

Errors:

• 401 Unauthorized - Invalid or expired refresh token

---

POST /api/v1/auth/logout

Logout user and invalidate tokens.

Headers: Authorization: Bearer <access_token>

Response: 204 No Content

---

POST /api/v1/auth/oauth/{provider}

OAuth authentication (Google, GitHub).

Path Parameters:

• provider - OAuth provider (google, github)

Query Parameters:

• code - OAuth authorization code
• state - CSRF state parameter

Response: 200 OK

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

---

Users

GET /api/v1/users/me

Get current user profile.

Headers: Authorization: Bearer <access_token>

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "full_name": "John Doe",
  "organization_id": "660e8400-e29b-41d4-a716-446655440000",
  "organization_name": "Acme Inc.",
  "role": "user",
  "tier": "pro",
  "anthropic_api_key": "sk-ant-api03-***",
  "is_active": true,
  "is_verified": true,
  "preferences": {
    "theme": "dark",
    "notifications": true,
    "language": "en"
  },
  "last_login": "2025-01-01T00:00:00Z",
  "created_at": "2024-12-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

---

PUT /api/v1/users/me

Update current user profile.

Headers: Authorization: Bearer <access_token>

Request:

{
  "full_name": "John A. Doe",
  "preferences": {
    "theme": "light",
    "notifications": false
  }
}

Response: 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "full_name": "John A. Doe",
  /* ... updated user object */
}

---

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

Update Anthropic API key.

Headers: Authorization: Bearer <access_token>

Request:

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

Response: 200 OK

{
  "message": "API key updated successfully",
  "masked_key": "sk-ant-api03-***"
}

---

DELETE /api/v1/users/me

Delete current user account (soft delete).

Headers: Authorization: Bearer <access_token>

Response: 204 No Content

---

Organizations

GET /api/v1/organizations/me

Get current organization details.

Headers: Authorization: Bearer <access_token>

Response: 200 OK

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "Acme Inc.",
  "tier": "pro",
  "settings": {
    "allow_sharing": true,
    "max_file_size_mb": 50,
    "retention_days": 90
  },
  "member_count": 15,
  "document_count": 1247,
  "is_active": true,
  "created_at": "2024-06-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

---

PUT /api/v1/organizations/me

Update organization settings (admin only).

Headers: Authorization: Bearer <access_token>

Request:

{
  "name": "Acme Corporation",
  "settings": {
    "allow_sharing": false,
    "max_file_size_mb": 100
  }
}

Response: 200 OK

---

GET /api/v1/organizations/me/usage

Get organization usage statistics.

Headers: Authorization: Bearer <access_token>

Query Parameters:

• start_date - Start date (ISO 8601)
• end_date - End date (ISO 8601)

Response: 200 OK

{
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "usage": {
    "documents_processed": 145,
    "pages_processed": 3240,
    "api_calls": 5678,
    "tokens_used": 1250000,
    "storage_bytes": 524288000
  },
  "limits": {
    "documents_per_month": 1000,
    "pages_per_month": 50000,
    "api_calls_per_month": 100000,
    "storage_bytes": 10737418240
  },
  "percentage_used": {
    "documents": 14.5,
    "pages": 6.48,
    "api_calls": 5.68,
    "storage": 4.88
  }
}

---

Documents

POST /api/v1/documents/upload

Upload a PDF document for processing.

Headers:

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

Request (multipart/form-data):

file: <PDF file>
mode: "mixed" (optional: "text", "table", "mixed")

Response: 201 Created

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "filename": "report_2025.pdf",
  "original_filename": "Annual Report 2025.pdf",
  "file_size": 2500000,
  "mime_type": "application/pdf",
  "status": "uploaded",
  "page_count": null,
  "created_at": "2025-01-01T00:00:00Z",
  "job_id": "880e8400-e29b-41d4-a716-446655440000"
}

Errors:

• 400 Bad Request - Invalid file type or size exceeds limit
• 413 Payload Too Large - File exceeds maximum size

---

GET /api/v1/documents

List user's documents with pagination and filtering.

Headers: Authorization: Bearer <access_token>

Query Parameters:

• page - Page number (default: 1)
• per_page - Items per page (default: 20, max: 100)
• status - Filter by status (uploaded, processing, completed, failed)
• search - Search by filename
• sort - Sort field (created_at, filename, file_size)
• order - Sort order (asc, desc)

Response: 200 OK

{
  "items": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "filename": "report_2025.pdf",
      "original_filename": "Annual Report 2025.pdf",
      "file_size": 2500000,
      "status": "completed",
      "page_count": 45,
      "metadata": {
        "author": "Finance Dept",
        "created": "2025-01-01"
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:05:00Z"
    }
  ],
  "total": 147,
  "page": 1,
  "per_page": 20,
  "pages": 8
}

---

GET /api/v1/documents/{document_id}

Get document details by ID.

Headers: Authorization: Bearer <access_token>

Path Parameters:

• document_id - Document UUID

Response: 200 OK

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "filename": "report_2025.pdf",
  "original_filename": "Annual Report 2025.pdf",
  "file_size": 2500000,
  "mime_type": "application/pdf",
  "gcs_path": "gs://bucket/path/to/file.pdf",
  "status": "completed",
  "page_count": 45,
  "metadata": {},
  "processing_jobs": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440000",
      "job_type": "text_extraction",
      "status": "completed",
      "progress": 100,
      "completed_at": "2025-01-01T00:05:00Z"
    }
  ],
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:05:00Z"
}

Errors:

• 404 Not Found - Document not found or access denied

---

DELETE /api/v1/documents/{document_id}

Delete a document (soft delete).

Headers: Authorization: Bearer <access_token>

Path Parameters:

• document_id - Document UUID

Response: 204 No Content

---

GET /api/v1/documents/{document_id}/download

Download the original PDF document.

Headers: Authorization: Bearer <access_token>

Path Parameters:

• document_id - Document UUID

Response: 200 OK

• Content-Type: application/pdf
• Content-Disposition: attachment; filename="document.pdf"
• Body: PDF file bytes

---

Processing Jobs

GET /api/v1/jobs

List processing jobs.

Headers: Authorization: Bearer <access_token>

Query Parameters:

• page - Page number
• per_page - Items per page
• status - Filter by status
• document_id - Filter by document ID

Response: 200 OK

{
  "items": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440000",
      "document_id": "770e8400-e29b-41d4-a716-446655440000",
      "job_type": "text_extraction",
      "status": "running",
      "priority": 5,
      "progress": 65,
      "config": {
        "mode": "mixed",
        "include_tables": true
      },
      "started_at": "2025-01-01T00:01:00Z",
      "created_at": "2025-01-01T00:00:30Z",
      "updated_at": "2025-01-01T00:03:00Z"
    }
  ],
  "total": 23,
  "page": 1,
  "per_page": 20,
  "pages": 2
}

---

GET /api/v1/jobs/{job_id}

Get job details by ID.

Headers: Authorization: Bearer <access_token>

Path Parameters:

• job_id - Job UUID

Response: 200 OK

{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "document_id": "770e8400-e29b-41d4-a716-446655440000",
  "job_type": "text_extraction",
  "status": "completed",
  "priority": 5,
  "progress": 100,
  "config": {
    "mode": "mixed",
    "include_tables": true
  },
  "result": {
    "text_length": 45000,
    "table_count": 15,
    "processing_time_ms": 3500
  },
  "started_at": "2025-01-01T00:01:00Z",
  "completed_at": "2025-01-01T00:04:30Z",
  "created_at": "2025-01-01T00:00:30Z",
  "updated_at": "2025-01-01T00:04:30Z"
}

---

Analysis Results

GET /api/v1/documents/{document_id}/analysis

Get all analysis results for a document.

Headers: Authorization: Bearer <access_token>

Path Parameters:

• document_id - Document UUID

Query Parameters:

• analysis_type - Filter by analysis type

Response: 200 OK

{
  "document_id": "770e8400-e29b-41d4-a716-446655440000",
  "analyses": [
    {
      "id": "990e8400-e29b-41d4-a716-446655440000",
      "analysis_type": "financial_analysis",
      "result_data": {
        "summary": "Strong Q4 performance with 15% growth",
        "key_metrics": {
          "revenue": "$10.5M",
          "profit": "$2.1M"
        },
        "insights": [
          "Cloud revenue doubled",
          "Costs well controlled"
        ]
      },
      "confidence_score": 0.92,
      "model_version": "claude-sonnet-4-20250514",
      "processing_time_ms": 2800,
      "token_usage": 4500,
      "created_at": "2025-01-01T00:05:00Z"
    }
  ]
}

---

POST /api/v1/documents/{document_id}/analyze

Request new analysis on a document.

Headers: Authorization: Bearer <access_token>

Path Parameters:

• document_id - Document UUID

Request:

{
  "analysis_type": "financial_analysis",
  "prompt": "Analyze the financial performance and provide key insights",
  "options": {
    "extract_tables": true,
    "summarize": true
  }
}

Response: 202 Accepted

{
  "job_id": "aa0e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Analysis job created"
}

---

WebSocket

WS /ws/{user_id}

Real-time updates for document processing and job status.

Connection:

const ws = new WebSocket(`wss://api.pdfanalysis.az1.ai/ws/{user_id}?token={access_token}`);

Query Parameters:

• token - JWT access token

Message Types:

Subscribe to channels:

{
  "type": "subscribe",
  "channels": ["document_updates", "job_updates"]
}

Heartbeat (ping/pong):

{
  "type": "ping"
}

Server response:

{
  "type": "pong"
}

Document update notification:

{
  "type": "document_update",
  "data": {
    "document_id": "770e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "page_count": 45
  }
}

Job update notification:

{
  "type": "job_update",
  "data": {
    "job_id": "880e8400-e29b-41d4-a716-446655440000",
    "status": "running",
    "progress": 75
  }
}

---

Health & Status

GET /health

Health check endpoint (no authentication required).

Response: 200 OK

{
  "status": "healthy",
  "timestamp": "2025-01-01T00:00:00Z",
  "version": "1.0.0",
  "services": {
    "database": "healthy",
    "redis": "healthy",
    "gcs": "healthy"
  }
}

---

GET /api/v1/status

API status and version information.

Response: 200 OK

{
  "api_version": "1.0.0",
  "environment": "production",
  "uptime_seconds": 86400,
  "request_count": 1000000,
  "active_connections": 250
}

---

Rate Limiting

Rate limits are enforced based on user tier:

Tier	Requests/Minute	Requests/Hour
Free	10	100
Pro	100	5,000
Enterprise	1,000	50,000

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

Rate Limit Exceeded:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "retry_after": 42
}

---

Error Responses

All errors follow this format:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    "field": "Additional error context"
  }
}

Common Error Codes:

• 400 Bad Request - Invalid input
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 409 Conflict - Resource conflict (e.g., duplicate email)
• 422 Unprocessable Entity - Validation error
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error
• 503 Service Unavailable - Service temporarily unavailable

---

Contact

For API support and questions:

• Email: 1@az1.ai
• Documentation: https://docs.pdfanalysis.az1.ai

---

Copyright © 2025 AZ1.AI Inc. / Coditect.AI - All Rights Reserved

Author: Hal Casteel, CEO/CTO AZ1.AI Inc. Contact: 1@az1.ai