From 71b52f6c5e7427ebe96efd319c8a58b19c847dce Mon Sep 17 00:00:00 2001
From: Dan Mestas <93289084+danmestas@users.noreply.github.com>
Date: Wed, 30 Jul 2025 14:18:13 -0500
Subject: [PATCH] feat(api): implement OpenAPI/REST API for file conversions

- Add comprehensive REST API at /api/v1 with modular structure
- Implement authentication endpoints (register, login, logout, me)
- Add converter listing and format discovery endpoints
- Create job management and file download endpoints
- Add health check endpoint for monitoring
- Set up CORS support for browser-based API clients
- Create API middleware for JWT authentication
- Add environment variables for API configuration
- Include comprehensive API documentation and test script

Infrastructure:
- Enhanced CI/CD workflow for custom Docker registries
- Docker Compose setup with dev, prod, and monitoring profiles
- Claude.ai integration files for development workflow
- Environment-based configuration with .env.development

Known limitations:
- JWT authentication context needs fixing (using ALLOW_UNAUTHENTICATED=true)
- Swagger UI temporarily disabled due to composition error
- File upload endpoint needs multipart/form-data support

The API code is isolated in src/api/ directory to maintain separation
from the existing codebase, making it easy to maintain or contribute back.
---
 .claude/build.md                            |  50 +++
 .claude/commit.md                           |  37 +++
 .claude/pr.md                               |  52 +++
 .claude/test.md                             |  45 +++
 .env.development                            |  15 +
 .github/workflows/README.md                 | 107 +++++++
 .github/workflows/docker-publish-custom.yml | 231 ++++++++++++++
 API.md                                      | 243 ++++++++++++++
 CLAUDE.md                                   | 146 +++++++++
 IMPLEMENTATION_SUMMARY.md                   | 120 +++++++
 bun.lock                                    |  28 ++
 docker-compose.README.md                    | 161 ++++++++++
 docker-compose.yml                          | 136 ++++++++
 package.json                                |   2 +
 src/api/middleware/auth.ts                  |  57 ++++
 src/api/types.ts                            |  10 +
 src/api/v1/auth.ts                          | 330 ++++++++++++++++++++
 src/api/v1/conversions.ts                   | 137 ++++++++
 src/api/v1/converters.ts                    | 226 ++++++++++++++
 src/api/v1/debug.ts                         |  19 ++
 src/api/v1/files.ts                         | 252 +++++++++++++++
 src/api/v1/health.ts                        |  83 +++++
 src/api/v1/index.ts                         | 213 +++++++++++++
 src/api/v1/jobs.ts                          | 300 ++++++++++++++++++
 src/helpers/env.ts                          |  15 +-
 src/index.tsx                               |   4 +-
 test-api.sh                                 | 133 ++++++++
 27 files changed, 3150 insertions(+), 2 deletions(-)
 create mode 100644 .claude/build.md
 create mode 100644 .claude/commit.md
 create mode 100644 .claude/pr.md
 create mode 100644 .claude/test.md
 create mode 100644 .env.development
 create mode 100644 .github/workflows/README.md
 create mode 100644 .github/workflows/docker-publish-custom.yml
 create mode 100644 API.md
 create mode 100644 CLAUDE.md
 create mode 100644 IMPLEMENTATION_SUMMARY.md
 create mode 100644 docker-compose.README.md
 create mode 100644 docker-compose.yml
 create mode 100644 src/api/middleware/auth.ts
 create mode 100644 src/api/types.ts
 create mode 100644 src/api/v1/auth.ts
 create mode 100644 src/api/v1/conversions.ts
 create mode 100644 src/api/v1/converters.ts
 create mode 100644 src/api/v1/debug.ts
 create mode 100644 src/api/v1/files.ts
 create mode 100644 src/api/v1/health.ts
 create mode 100644 src/api/v1/index.ts
 create mode 100644 src/api/v1/jobs.ts
 create mode 100755 test-api.sh

diff --git a/.claude/build.md b/.claude/build.md
new file mode 100644
index 0000000..15eafc0
--- /dev/null
+++ b/.claude/build.md
@@ -0,0 +1,50 @@
+# Build and Test Docker Image
+
+Please build and test the Docker image with these steps:
+
+1. **Build the Docker image**:
+   ```bash
+   docker build -t convertx-openapi:local .
+   ```
+
+2. **Verify the build**:
+   - Check image size: `docker images convertx-openapi:local`
+   - Inspect layers: `docker history convertx-openapi:local`
+
+3. **Run container locally**:
+   ```bash
+   docker run -d \
+     --name convertx-test \
+     -p 3000:3000 \
+     -v $(pwd)/data:/app/data \
+     -e JWT_SECRET=test-secret \
+     -e NODE_ENV=production \
+     convertx-openapi:local
+   ```
+
+4. **Test the application**:
+   - Check logs: `docker logs convertx-test`
+   - Test health: `curl http://localhost:3000`
+   - Verify converters load properly
+
+5. **Multi-platform build** (if needed):
+   ```bash
+   docker buildx build \
+     --platform linux/amd64,linux/arm64 \
+     -t convertx-openapi:local \
+     .
+   ```
+
+6. **Push to custom registry** (if configured):
+   ```bash
+   docker tag convertx-openapi:local ${DOCKER_REGISTRY}/convertx:latest
+   docker push ${DOCKER_REGISTRY}/convertx:latest
+   ```
+
+7. **Cleanup**:
+   ```bash
+   docker stop convertx-test
+   docker rm convertx-test
+   ```
+
+Please execute these steps and report any issues.
\ No newline at end of file
diff --git a/.claude/commit.md b/.claude/commit.md
new file mode 100644
index 0000000..bb09497
--- /dev/null
+++ b/.claude/commit.md
@@ -0,0 +1,37 @@
+# Commit Changes
+
+Please create a git commit with the following requirements:
+
+1. **Review all changes**: First run `git status` and `git diff` to see what has changed
+2. **Stage appropriate files**: Use `git add` to stage the relevant changes
+3. **Commit message format**: Use conventional commit format:
+   - feat: New feature
+   - fix: Bug fix
+   - docs: Documentation changes
+   - style: Code style changes (formatting, etc)
+   - refactor: Code refactoring
+   - test: Adding or updating tests
+   - chore: Maintenance tasks
+   - build: Build system changes
+   - ci: CI/CD changes
+
+3. **Message structure**:
+   ```
+   <type>(<scope>): <subject>
+   
+   <body>
+   
+   <footer>
+   ```
+
+4. **Guidelines**:
+   - Subject line: 50 characters or less
+   - Use imperative mood ("add" not "added")
+   - Reference issues if applicable
+   - Explain the "why" in the body if needed
+
+5. **Run checks**: Before committing, ensure:
+   - `bun run typecheck` passes
+   - `bun run lint` passes (if available)
+
+Please analyze the changes and create an appropriate commit.
\ No newline at end of file
diff --git a/.claude/pr.md b/.claude/pr.md
new file mode 100644
index 0000000..605c1b7
--- /dev/null
+++ b/.claude/pr.md
@@ -0,0 +1,52 @@
+# Create Pull Request
+
+Please create a pull request with the following steps:
+
+1. **Ensure branch is up to date**:
+   - Check current branch with `git branch --show-current`
+   - Pull latest changes from main/master
+   - Push current branch to remote
+
+2. **Create PR using GitHub CLI** (`gh pr create`) with:
+   - Clear, descriptive title
+   - Comprehensive description including:
+     - What changes were made
+     - Why these changes were necessary
+     - How to test the changes
+     - Any breaking changes or migration notes
+
+3. **PR Template**:
+   ```markdown
+   ## Summary
+   Brief description of what this PR does.
+
+   ## Changes
+   - List of specific changes made
+   - Organized by component/feature
+
+   ## Testing
+   - [ ] Unit tests pass
+   - [ ] Integration tests pass
+   - [ ] Manual testing completed
+   - [ ] Documentation updated
+
+   ## Screenshots
+   (If applicable)
+
+   ## Breaking Changes
+   - List any breaking changes
+   - Migration instructions if needed
+
+   ## Related Issues
+   Closes #XXX
+   ```
+
+4. **Labels to consider**:
+   - `enhancement`: New features
+   - `bug`: Bug fixes
+   - `documentation`: Doc updates
+   - `api`: API-related changes
+   - `docker`: Container changes
+   - `dependencies`: Dependency updates
+
+Please analyze the current branch changes and create an appropriate PR.
\ No newline at end of file
diff --git a/.claude/test.md b/.claude/test.md
new file mode 100644
index 0000000..e9b1926
--- /dev/null
+++ b/.claude/test.md
@@ -0,0 +1,45 @@
+# Run Tests and Checks
+
+Please run the following tests and checks for the ConvertX project:
+
+1. **Type Checking**:
+   ```bash
+   bun run typecheck
+   ```
+   Fix any TypeScript errors found
+
+2. **Linting**:
+   ```bash
+   bun run lint
+   ```
+   Fix any linting issues
+
+3. **Unit Tests** (if available):
+   ```bash
+   bun test
+   ```
+
+4. **Build Check**:
+   ```bash
+   bun run build
+   ```
+   Ensure the build completes successfully
+
+5. **API Tests** (when implemented):
+   - Test authentication endpoints
+   - Test file upload endpoints
+   - Test conversion endpoints
+   - Test error handling
+
+6. **Docker Build Test**:
+   ```bash
+   docker build -t convertx-test .
+   ```
+
+7. **Integration Test** (if safe to run):
+   - Start the application
+   - Upload a test file
+   - Convert it
+   - Verify the output
+
+Please run these checks and report any issues found. If there are failures, analyze and suggest fixes.
\ No newline at end of file
diff --git a/.env.development b/.env.development
new file mode 100644
index 0000000..2b281a7
--- /dev/null
+++ b/.env.development
@@ -0,0 +1,15 @@
+# Development environment variables
+ACCOUNT_REGISTRATION=true
+JWT_SECRET=dev-secret-key-123
+HTTP_ALLOWED=true
+ALLOW_UNAUTHENTICATED=true
+AUTO_DELETE_EVERY_N_HOURS=24
+WEBROOT=
+TZ=UTC
+
+# API Configuration
+API_ENABLED=true
+API_PREFIX=/api/v1
+API_RATE_LIMIT=100
+API_RATE_WINDOW=15m
+API_KEY_ENABLED=false
\ No newline at end of file
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
new file mode 100644
index 0000000..38c46b9
--- /dev/null
+++ b/.github/workflows/README.md
@@ -0,0 +1,107 @@
+# GitHub Actions Configuration
+
+This directory contains GitHub Actions workflows for building and publishing Docker images.
+
+## Workflows
+
+### docker-publish.yml (Original)
+The original workflow that publishes to:
+- GitHub Container Registry (ghcr.io)
+- Docker Hub
+
+### docker-publish-custom.yml (Enhanced)
+Enhanced workflow that supports custom Docker registries while maintaining backward compatibility.
+
+## Configuration
+
+To use a custom Docker registry, set the following in your repository:
+
+### Repository Variables (Settings → Secrets and variables → Actions → Variables)
+- `DOCKER_REGISTRY`: Your custom registry URL (e.g., `registry.company.com`)
+- `DOCKER_USERNAME`: Username for custom registry authentication
+- `DOCKERHUB_USERNAME`: Your Docker Hub username (optional)
+- `PUSH_TO_GHCR`: Set to `false` to disable GHCR push (default: `true`)
+- `PUSH_TO_DOCKERHUB`: Set to `true` to enable Docker Hub push (default: `false`)
+- `PUSH_TO_CUSTOM`: Set to `true` to enable custom registry push (default: `false`)
+
+### Repository Secrets (Settings → Secrets and variables → Actions → Secrets)
+- `DOCKER_PASSWORD`: Password/token for custom registry authentication
+- `DOCKERHUB_TOKEN`: Docker Hub access token (if using Docker Hub)
+
+## Usage Examples
+
+### 1. Use only custom registry
+Set variables:
+```
+DOCKER_REGISTRY=registry.mycompany.com
+DOCKER_USERNAME=myuser
+PUSH_TO_CUSTOM=true
+PUSH_TO_GHCR=false
+PUSH_TO_DOCKERHUB=false
+```
+
+Set secrets:
+```
+DOCKER_PASSWORD=<your-registry-password>
+```
+
+### 2. Use custom registry + GHCR
+Set variables:
+```
+DOCKER_REGISTRY=registry.mycompany.com
+DOCKER_USERNAME=myuser
+PUSH_TO_CUSTOM=true
+PUSH_TO_GHCR=true
+PUSH_TO_DOCKERHUB=false
+```
+
+### 3. Use all three registries
+Set variables:
+```
+DOCKER_REGISTRY=registry.mycompany.com
+DOCKER_USERNAME=myuser
+DOCKERHUB_USERNAME=mydockerhubuser
+PUSH_TO_CUSTOM=true
+PUSH_TO_GHCR=true
+PUSH_TO_DOCKERHUB=true
+```
+
+Set secrets:
+```
+DOCKER_PASSWORD=<your-registry-password>
+DOCKERHUB_TOKEN=<your-dockerhub-token>
+```
+
+## Image Tags
+
+The workflow creates the following tags:
+- `latest`: Latest build from main branch
+- `main`: Main branch builds
+- `pr-123`: Pull request builds
+- `v1.2.3`: Semantic version tags
+- `1.2`: Major.minor version
+- `1`: Major version
+- `main-sha-abc123`: SHA-based tags
+
+## Switching Workflows
+
+To switch from the original to the custom workflow:
+
+1. Rename workflows:
+   ```bash
+   mv .github/workflows/docker-publish.yml .github/workflows/docker-publish-original.yml
+   mv .github/workflows/docker-publish-custom.yml .github/workflows/docker-publish.yml
+   ```
+
+2. Or update the workflow triggers to disable one:
+   ```yaml
+   on:
+     workflow_dispatch:  # Manual trigger only
+   ```
+
+## Troubleshooting
+
+1. **Authentication failures**: Check that secrets are correctly set
+2. **Push failures**: Ensure the registry URL doesn't include `https://`
+3. **Missing images**: Verify the PUSH_TO_* variables are set correctly
+4. **Build failures**: Check Docker build logs in the Actions tab
\ No newline at end of file
diff --git a/.github/workflows/docker-publish-custom.yml b/.github/workflows/docker-publish-custom.yml
new file mode 100644
index 0000000..be01ac9
--- /dev/null
+++ b/.github/workflows/docker-publish-custom.yml
@@ -0,0 +1,231 @@
+name: Docker (Custom Registry Support)
+
+# This workflow supports custom Docker registries while maintaining compatibility
+# with the original GHCR and Docker Hub setup
+
+on:
+  push:
+    branches: ["main"]
+    tags: ["v*.*.*"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+env:
+  # Custom registry configuration (set these in your repository secrets/variables)
+  # If CUSTOM_REGISTRY is not set, it will default to GHCR and Docker Hub
+  CUSTOM_REGISTRY: ${{ vars.DOCKER_REGISTRY || '' }}
+  CUSTOM_REGISTRY_USERNAME: ${{ vars.DOCKER_USERNAME || github.actor }}
+  CUSTOM_REGISTRY_PASSWORD: ${{ secrets.DOCKER_PASSWORD || secrets.GITHUB_TOKEN }}
+  
+  # Default registries (original behavior)
+  GHCR_IMAGE: ghcr.io/${{ github.repository_owner }}/convertx-openapi
+  DOCKERHUB_IMAGE: ${{ vars.DOCKERHUB_USERNAME || 'dmestas' }}/convertx-openapi
+  
+  # Feature flags
+  PUSH_TO_GHCR: ${{ vars.PUSH_TO_GHCR || 'true' }}
+  PUSH_TO_DOCKERHUB: ${{ vars.PUSH_TO_DOCKERHUB || 'false' }}
+  PUSH_TO_CUSTOM: ${{ vars.PUSH_TO_CUSTOM || 'false' }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - linux/amd64
+          - linux/arm64
+
+    permissions:
+      contents: write
+      packages: write
+      attestations: write
+      checks: write
+      actions: read
+
+    runs-on: ${{ matrix.platform == 'linux/amd64' && 'ubuntu-24.04' || matrix.platform == 'linux/arm64' && 'ubuntu-24.04-arm' }}
+
+    name: Build Docker image for ${{ matrix.platform }}
+
+    steps:
+      - name: Prepare environment
+        id: prepare
+        run: |
+          platform=${{ matrix.platform }}
+          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
+          
+          # Determine which image to use for building
+          if [[ "${{ env.PUSH_TO_CUSTOM }}" == "true" && -n "${{ env.CUSTOM_REGISTRY }}" ]]; then
+            echo "PRIMARY_IMAGE=${{ env.CUSTOM_REGISTRY }}/convertx-openapi" >> $GITHUB_ENV
+          else
+            echo "PRIMARY_IMAGE=${{ env.GHCR_IMAGE }}" >> $GITHUB_ENV
+          fi
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.PRIMARY_IMAGE }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha,prefix={{branch}}-
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          platforms: ${{ matrix.platform }}
+
+      # Login to custom registry if configured
+      - name: Login to Custom Registry
+        if: env.PUSH_TO_CUSTOM == 'true' && env.CUSTOM_REGISTRY != ''
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.CUSTOM_REGISTRY }}
+          username: ${{ env.CUSTOM_REGISTRY_USERNAME }}
+          password: ${{ env.CUSTOM_REGISTRY_PASSWORD }}
+
+      # Login to GHCR if enabled
+      - name: Login to GitHub Container Registry
+        if: env.PUSH_TO_GHCR == 'true'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Build and push by digest
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        env:
+          DOCKER_BUILDKIT: 1
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          annotations: ${{ steps.meta.outputs.annotations }}
+          outputs: type=image,name=${{ env.PRIMARY_IMAGE }},push-by-digest=true,name-canonical=true,push=true,oci-mediatypes=true
+          cache-from: type=gha,scope=${{ matrix.platform }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.platform }}
+
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-${{ env.PLATFORM_PAIR }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    name: Merge Docker manifests
+    runs-on: ubuntu-latest
+
+    permissions:
+      attestations: write
+      contents: read
+      packages: write
+
+    needs:
+      - build
+      
+    steps:
+      - name: Prepare environment
+        run: |
+          # Build image list based on enabled registries
+          IMAGES=""
+          
+          if [[ "${{ env.PUSH_TO_CUSTOM }}" == "true" && -n "${{ env.CUSTOM_REGISTRY }}" ]]; then
+            IMAGES="${{ env.CUSTOM_REGISTRY }}/convertx-openapi"
+            echo "PRIMARY_IMAGE=${{ env.CUSTOM_REGISTRY }}/convertx-openapi" >> $GITHUB_ENV
+          else
+            echo "PRIMARY_IMAGE=${{ env.GHCR_IMAGE }}" >> $GITHUB_ENV
+          fi
+          
+          if [[ "${{ env.PUSH_TO_GHCR }}" == "true" ]]; then
+            IMAGES="$IMAGES ${{ env.GHCR_IMAGE }}"
+          fi
+          
+          if [[ "${{ env.PUSH_TO_DOCKERHUB }}" == "true" ]]; then
+            IMAGES="$IMAGES ${{ env.DOCKERHUB_IMAGE }}"
+          fi
+          
+          echo "PUSH_IMAGES=$IMAGES" >> $GITHUB_ENV
+
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.PUSH_IMAGES }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha,prefix={{branch}}-
+
+      # Login to all configured registries
+      - name: Login to Custom Registry
+        if: env.PUSH_TO_CUSTOM == 'true' && env.CUSTOM_REGISTRY != ''
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.CUSTOM_REGISTRY }}
+          username: ${{ env.CUSTOM_REGISTRY_USERNAME }}
+          password: ${{ env.CUSTOM_REGISTRY_PASSWORD }}
+
+      - name: Login to GitHub Container Registry
+        if: env.PUSH_TO_GHCR == 'true'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        if: env.PUSH_TO_DOCKERHUB == 'true' && secrets.DOCKERHUB_TOKEN != ''
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create \
+            $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            --annotation='index:org.opencontainers.image.description=ConvertX OpenAPI - File conversion service with API support' \
+            --annotation='index:org.opencontainers.image.created=${{ steps.timestamp.outputs.timestamp }}' \
+            --annotation='index:org.opencontainers.image.url=${{ github.event.repository.html_url }}' \
+            --annotation='index:org.opencontainers.image.source=${{ github.event.repository.html_url }}' \
+            $(printf '${{ env.PRIMARY_IMAGE }}@sha256:%s ' *)
+
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect '${{ env.PRIMARY_IMAGE }}:${{ steps.meta.outputs.version }}'
\ No newline at end of file
diff --git a/API.md b/API.md
new file mode 100644
index 0000000..110d2fe
--- /dev/null
+++ b/API.md
@@ -0,0 +1,243 @@
+# ConvertX OpenAPI Documentation
+
+ConvertX now includes a fully-featured REST API for programmatic file conversions.
+
+## API Overview
+
+- **Base URL**: `http://localhost:3110/api/v1`
+- **Authentication**: JWT Bearer tokens or API keys
+- **Format**: JSON
+- **Rate Limiting**: 100 requests per 15 minutes (configurable)
+
+## Quick Start
+
+### 1. Get Authentication Token
+
+```bash
+# Register a new account
+curl -X POST http://localhost:3110/api/v1/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com", "password": "securepassword"}'
+
+# Or login to existing account
+curl -X POST http://localhost:3110/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com", "password": "securepassword"}'
+```
+
+Response:
+```json
+{
+  "success": true,
+  "data": {
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+    "user": {
+      "id": 1,
+      "email": "user@example.com"
+    },
+    "expiresIn": "7d"
+  }
+}
+```
+
+### 2. List Available Converters
+
+```bash
+curl http://localhost:3110/api/v1/converters \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### 3. Check Supported Formats
+
+```bash
+# Check which converters support PDF input
+curl http://localhost:3110/api/v1/converters/formats/pdf \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### 4. Start a Conversion (Coming Soon)
+
+Full file upload support is coming. Current implementation requires files to be pre-uploaded.
+
+```bash
+curl -X POST http://localhost:3110/api/v1/conversions \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "files": [{"name": "document.pdf"}],
+    "converter": "libreoffice",
+    "outputFormat": "docx"
+  }'
+```
+
+### 5. Check Job Status
+
+```bash
+curl http://localhost:3110/api/v1/jobs/JOB_ID \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
+
+### 6. Download Converted Files
+
+```bash
+curl http://localhost:3110/api/v1/files/JOB_ID/document.docx \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -o document.docx
+```
+
+## API Endpoints
+
+### Authentication
+
+- `POST /api/v1/auth/login` - Login with email/password
+- `POST /api/v1/auth/register` - Register new account
+- `GET /api/v1/auth/me` - Get current user info
+- `POST /api/v1/auth/logout` - Clear auth cookie
+
+### Converters
+
+- `GET /api/v1/converters` - List all converters
+- `GET /api/v1/converters/:name` - Get converter details
+- `GET /api/v1/converters/formats/:format` - Find converters for format
+
+### Conversions
+
+- `POST /api/v1/conversions` - Start conversion job
+
+### Jobs
+
+- `GET /api/v1/jobs` - List user's jobs
+- `GET /api/v1/jobs/:id` - Get job details
+- `DELETE /api/v1/jobs/:id` - Delete job
+
+### Files
+
+- `GET /api/v1/files/:jobId` - List files in job
+- `GET /api/v1/files/:jobId/:fileName` - Download file
+
+### Health
+
+- `GET /api/v1/health` - API health check
+
+## Swagger Documentation
+
+Interactive API documentation is available at:
+```
+http://localhost:3110/api/v1/swagger
+```
+
+## Environment Variables
+
+```env
+# API Configuration
+API_ENABLED=true              # Enable API endpoints
+API_PREFIX=/api/v1           # API URL prefix
+API_RATE_LIMIT=100           # Requests per window
+API_RATE_WINDOW=15m          # Rate limit window
+API_KEY_ENABLED=false        # Enable API key auth (coming soon)
+
+# Authentication
+JWT_SECRET=your-secret-key   # JWT signing secret
+ALLOW_UNAUTHENTICATED=false  # Allow anonymous access
+ACCOUNT_REGISTRATION=true    # Allow new registrations
+```
+
+## Client Examples
+
+### JavaScript/TypeScript
+
+```typescript
+class ConvertXClient {
+  constructor(private baseUrl: string, private token: string) {}
+
+  async listConverters() {
+    const response = await fetch(`${this.baseUrl}/converters`, {
+      headers: { 'Authorization': `Bearer ${this.token}` }
+    });
+    return response.json();
+  }
+
+  async startConversion(files: File[], converter: string, outputFormat: string) {
+    // Implementation coming soon with multipart upload support
+  }
+}
+```
+
+### Python
+
+```python
+import requests
+
+class ConvertXClient:
+    def __init__(self, base_url, token):
+        self.base_url = base_url
+        self.headers = {'Authorization': f'Bearer {token}'}
+    
+    def list_converters(self):
+        return requests.get(f'{self.base_url}/converters', headers=self.headers).json()
+    
+    def get_job_status(self, job_id):
+        return requests.get(f'{self.base_url}/jobs/{job_id}', headers=self.headers).json()
+```
+
+### cURL
+
+```bash
+# Set your token
+TOKEN="your-jwt-token"
+BASE_URL="http://localhost:3110/api/v1"
+
+# List converters
+curl -H "Authorization: Bearer $TOKEN" $BASE_URL/converters
+
+# Check health
+curl $BASE_URL/health
+```
+
+## Error Handling
+
+All errors follow a consistent format:
+
+```json
+{
+  "success": false,
+  "error": "Error message",
+  "code": "ERROR_CODE",
+  "details": "Additional information (if available)"
+}
+```
+
+Common error codes:
+- `UNAUTHORIZED` - Missing or invalid authentication
+- `NOT_FOUND` - Resource not found
+- `BAD_REQUEST` - Invalid request parameters
+- `VALIDATION_ERROR` - Input validation failed
+- `INTERNAL_ERROR` - Server error
+
+## Rate Limiting
+
+Rate limit information is included in response headers:
+- `X-RateLimit-Limit` - Maximum requests allowed
+- `X-RateLimit-Remaining` - Requests remaining
+- `X-RateLimit-Reset` - Time when limit resets (Unix timestamp)
+
+## Coming Soon
+
+1. **Multipart file upload** - Direct file upload in conversion endpoint
+2. **API key authentication** - Alternative to JWT for automation
+3. **Webhooks** - Get notified when conversions complete
+4. **Batch operations** - Convert multiple files in parallel
+5. **Advanced options** - Pass converter-specific options
+6. **S3/Cloud storage** - Direct upload/download from cloud storage
+
+## Security Notes
+
+1. Always use HTTPS in production
+2. Keep your JWT tokens secure
+3. Set strong JWT_SECRET in production
+4. Enable rate limiting to prevent abuse
+5. Use CORS settings appropriate for your use case
+
+## Support
+
+For API issues or feature requests, please open an issue on GitHub.
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..554232c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,146 @@
+# ConvertX Codebase Documentation
+
+## Overview
+ConvertX is a self-hosted file conversion service built with Bun and Elysia framework. It supports 1000+ file format conversions using 17 different converter tools.
+
+## Tech Stack
+- **Runtime**: Bun
+- **Framework**: Elysia (TypeScript)
+- **Database**: SQLite with Bun's built-in driver
+- **Frontend**: Server-side rendered HTML with HTMX, Tailwind CSS
+- **Authentication**: JWT tokens via @elysiajs/jwt
+- **Container**: Docker (Debian Trixie Slim base)
+
+## Project Structure
+```
+ConvertX-openAPI/
+├── src/
+│   ├── index.tsx              # Main app entry, route setup
+│   ├── api/                   # NEW: OpenAPI endpoints
+│   │   ├── v1/                # API version 1
+│   │   ├── middleware/        # API middleware
+│   │   └── schemas/           # Request/response schemas
+│   ├── converters/            # File conversion logic
+│   │   ├── main.ts           # Converter orchestration
+│   │   └── [converter].ts    # Individual converter wrappers
+│   ├── pages/                # Web UI route handlers
+│   ├── components/           # UI components
+│   ├── db/                   # Database schema
+│   └── helpers/              # Utilities
+├── data/                     # Runtime data
+│   ├── uploads/              # User uploaded files
+│   ├── output/               # Converted files
+│   └── mydb.sqlite          # SQLite database
+└── public/                   # Static assets
+```
+
+## Key Concepts
+
+### Converters
+Each converter (ffmpeg, pandoc, etc.) is wrapped in a TypeScript module that:
+1. Exports `properties` defining supported input/output formats
+2. Exports `convert` function that executes the conversion
+3. Returns status string: "Done", "Failed", or custom message
+
+### Job Flow
+1. User uploads files → creates job with unique ID
+2. Files stored in `data/uploads/{userId}/{jobId}/`
+3. User selects converter → triggers conversion
+4. Converted files saved to `data/output/{userId}/{jobId}/`
+5. Job status tracked in database
+6. Auto-deletion after N hours (configurable)
+
+### Authentication
+- JWT-based with 7-day expiration
+- User ID 0 reserved for unauthenticated users (if enabled)
+- First user registration creates admin account
+
+## Environment Variables
+- `JWT_SECRET`: Secret for JWT signing (auto-generated if not set)
+- `WEBROOT`: URL prefix for deployment (default: "")
+- `ACCOUNT_REGISTRATION`: Enable user registration
+- `ALLOW_UNAUTHENTICATED`: Allow usage without login
+- `HTTP_ALLOWED`: Allow HTTP (not just HTTPS)
+- `AUTO_DELETE_EVERY_N_HOURS`: Cleanup interval
+- `MAX_CONVERT_PROCESS`: Parallel conversion limit
+
+## Database Schema
+```sql
+users: id, email, password
+jobs: id, user_id, date_created, status, num_files
+file_names: id, job_id, file_name, output_file_name, status
+```
+
+## API Development Guidelines
+
+### Adding New Endpoints
+1. Create route file in `src/api/v1/`
+2. Define schemas in `src/api/schemas/`
+3. Use existing auth middleware from `src/api/middleware/auth.ts`
+4. Reuse converter logic from `src/converters/main.ts`
+
+### Response Format
+```json
+{
+  "success": boolean,
+  "data": any,
+  "error": string | null,
+  "jobId": string | null
+}
+```
+
+### Error Handling
+- Use HTTP status codes appropriately
+- Include error details in response body
+- Log errors with correlation IDs
+
+## Testing Commands
+```bash
+# Run type checking
+bun run typecheck
+
+# Run linting  
+bun run lint
+
+# Run tests (when implemented)
+bun test
+
+# Build CSS (development)
+bun run build
+
+# Start development server
+bun run dev
+```
+
+## Docker Commands
+```bash
+# Build image
+docker build -t convertx-openapi .
+
+# Run container
+docker run -p 3000:3000 -v ./data:/app/data convertx-openapi
+
+# With custom registry
+docker build -t your-registry.com/convertx:latest .
+docker push your-registry.com/convertx:latest
+```
+
+## Common Tasks
+
+### Adding a New Converter
+1. Create `src/converters/newconverter.ts`
+2. Export `properties` and `convert` functions
+3. Import and add to `properties` object in `main.ts`
+4. Update Dockerfile to install required system package
+
+### Debugging Conversions
+- Check console logs for converter output
+- Verify file permissions in data directories
+- Test converter CLI directly in container
+- Check `file_names` table for status
+
+### Performance Optimization
+- Adjust `MAX_CONVERT_PROCESS` for parallelism
+- Use batch processing in `handleConvert`
+- Enable SQLite WAL mode (already done)
+- Consider external job queue for scale
\ No newline at end of file
diff --git a/IMPLEMENTATION_SUMMARY.md b/IMPLEMENTATION_SUMMARY.md
new file mode 100644
index 0000000..d20d483
--- /dev/null
+++ b/IMPLEMENTATION_SUMMARY.md
@@ -0,0 +1,120 @@
+# ConvertX OpenAPI Implementation Summary
+
+## ✅ Completed Features
+
+### 1. Project Setup
+- **CLAUDE.md**: Complete codebase documentation
+- **Slash Commands**: `/commit`, `/pr`, `/test`, `/build` helpers
+- **Environment Configuration**: `.env.development` with API settings
+
+### 2. CI/CD Enhancements
+- **docker-publish-custom.yml**: Supports custom Docker registries
+- **docker-compose.yml**: Multi-profile setup (dev, prod, monitoring)
+- **Registry Configuration**: Environment variable based registry selection
+
+### 3. API Implementation
+- **Base Structure**: `/api/v1` endpoints with modular organization
+- **Health Check**: `/api/v1/health` - System status monitoring
+- **Authentication**: 
+  - `POST /api/v1/auth/register` - User registration
+  - `POST /api/v1/auth/login` - JWT token generation
+  - `GET /api/v1/auth/me` - Current user info
+  - `POST /api/v1/auth/logout` - Session cleanup
+- **Converters**:
+  - `GET /api/v1/converters` - List all converters
+  - `GET /api/v1/converters/:name` - Converter details
+  - `GET /api/v1/converters/formats/:format` - Find converters by format
+- **Jobs**:
+  - `GET /api/v1/jobs` - List user jobs
+  - `GET /api/v1/jobs/:id` - Job details
+  - `DELETE /api/v1/jobs/:id` - Delete job
+- **Files**:
+  - `GET /api/v1/files/:jobId` - List job files
+  - `GET /api/v1/files/:jobId/:fileName` - Download file
+- **Conversions**:
+  - `POST /api/v1/conversions` - Start conversion (partial implementation)
+
+### 4. Documentation & Testing
+- **API.md**: Complete API documentation
+- **test-api.sh**: Automated API testing script
+- **CORS**: Full CORS support for browser-based clients
+
+## 🚧 Known Issues & Limitations
+
+### 1. Authentication Context
+- JWT verification in middleware needs fixing
+- Currently requires `ALLOW_UNAUTHENTICATED=true` for testing
+- User context not properly passed to route handlers
+
+### 2. File Upload
+- Conversion endpoint expects pre-uploaded files
+- Multipart file upload not yet implemented
+- Need to integrate with existing upload logic
+
+### 3. Swagger/OpenAPI
+- Swagger UI disabled due to Elysia composition error
+- OpenAPI spec generation needs debugging
+- Alternative: Manual API documentation provided
+
+## 🔮 Next Steps
+
+### Phase 2: Core Functionality
+1. Fix JWT authentication middleware
+2. Implement multipart file upload
+3. Complete conversion endpoint with actual file processing
+4. Add progress tracking via SSE or WebSockets
+
+### Phase 3: Enhanced Features
+1. API key authentication
+2. Rate limiting implementation
+3. Webhook notifications
+4. Batch conversion support
+
+### Phase 4: Production Ready
+1. Re-enable Swagger UI
+2. Add comprehensive error handling
+3. Implement request/response logging
+4. Performance optimization
+5. API versioning strategy
+
+## 📝 Usage
+
+### Development
+```bash
+# Install dependencies
+bun install
+
+# Start with API enabled
+export $(cat .env.development | xargs) && bun run dev
+
+# Test API
+./test-api.sh
+```
+
+### Docker
+```bash
+# Development with hot reload
+docker compose --profile dev up
+
+# Production
+docker compose up convertx
+```
+
+## 🔧 Configuration
+
+Key environment variables:
+- `API_ENABLED=true` - Enable API endpoints
+- `ALLOW_UNAUTHENTICATED=true` - Allow anonymous access (dev only)
+- `JWT_SECRET` - Secret for JWT signing
+- `API_RATE_LIMIT` - Requests per window
+- `API_RATE_WINDOW` - Rate limit time window
+
+## 🏗️ Architecture Notes
+
+- API code isolated in `src/api/` directory
+- Minimal changes to existing codebase
+- Reuses existing converter logic
+- Compatible with current database schema
+- Can be disabled via environment variable
+
+The foundation is solid and ready for the remaining features to be implemented in subsequent phases.
\ No newline at end of file
diff --git a/bun.lock b/bun.lock
index 4bdeb22..5c48094 100644
--- a/bun.lock
+++ b/bun.lock
@@ -4,9 +4,11 @@
     "": {
       "name": "convertx-frontend",
       "dependencies": {
+        "@elysiajs/cors": "^1.3.0",
         "@elysiajs/html": "^1.3.0",
         "@elysiajs/jwt": "^1.3.1",
         "@elysiajs/static": "^1.3.0",
+        "@elysiajs/swagger": "^1.3.1",
         "@kitajs/html": "^4.2.9",
         "elysia": "^1.3.4",
         "sanitize-filename": "^1.6.3",
@@ -63,12 +65,16 @@
 
     "@babel/types": ["@babel/types@7.26.7", "", { "dependencies": { "@babel/helper-string-parser": "^7.25.9", "@babel/helper-validator-identifier": "^7.25.9" } }, "sha512-t8kDRGrKXyp6+tjUh7hw2RLyclsW4TRoRvRHtSyAX9Bb5ldlFh+90YAYY6awRXrlB4G5G2izNeGySpATlFzmOg=="],
 
+    "@elysiajs/cors": ["@elysiajs/cors@1.3.3", "", { "peerDependencies": { "elysia": ">= 1.3.0" } }, "sha512-mYIU6PyMM6xIJuj7d27Vt0/wuzVKIEnFPjcvlkyd7t/m9xspAG37cwNjFxVOnyvY43oOd2I/oW2DB85utXpA2Q=="],
+
     "@elysiajs/html": ["@elysiajs/html@1.3.0", "", { "dependencies": { "@kitajs/html": "^4.1.0", "@kitajs/ts-html-plugin": "^4.0.1" }, "peerDependencies": { "elysia": ">= 1.3.0" } }, "sha512-NpujllWwiEXdsX8GJhbBppOv7+aJr+OU7Gn3K8fVXpwieutwau0/B/M6vzjYXsh9OaoGByUTpL8U9rA/tVSn7w=="],
 
     "@elysiajs/jwt": ["@elysiajs/jwt@1.3.1", "", { "dependencies": { "jose": "^6.0.11" }, "peerDependencies": { "elysia": ">= 1.3.0" } }, "sha512-BVLAp0ER4839bR82ElgTsI7OoPxvFWP5u02KMgqpNoAM6xirJBYTKqANzY9ghuMfQoVEuD4B1/8lZwdPKAVg9Q=="],
 
     "@elysiajs/static": ["@elysiajs/static@1.3.0", "", { "dependencies": { "node-cache": "^5.1.2" }, "peerDependencies": { "elysia": ">= 1.3.0" } }, "sha512-7mWlj2U/AZvH27IfRKqpUjDP1W9ZRldF9NmdnatFEtx0AOy7YYgyk0rt5hXrH6wPcR//2gO2Qy+k5rwswpEhJA=="],
 
+    "@elysiajs/swagger": ["@elysiajs/swagger@1.3.1", "", { "dependencies": { "@scalar/themes": "^0.9.52", "@scalar/types": "^0.0.12", "openapi-types": "^12.1.3", "pathe": "^1.1.2" }, "peerDependencies": { "elysia": ">= 1.3.0" } }, "sha512-LcbLHa0zE6FJKWPWKsIC/f+62wbDv3aXydqcNPVPyqNcaUgwvCajIi+5kHEU6GO3oXUCpzKaMsb3gsjt8sLzFQ=="],
+
     "@emnapi/core": ["@emnapi/core@1.4.3", "", { "dependencies": { "@emnapi/wasi-threads": "1.0.2", "tslib": "^2.4.0" } }, "sha512-4m62DuCE07lw01soJwPiBGC0nAww0Q+RY70VZ+n49yDIO13yyinhbWCeNnaob0lakDtWQzSdtNWzJeOJt2ma+g=="],
 
     "@emnapi/runtime": ["@emnapi/runtime@1.4.3", "", { "dependencies": { "tslib": "^2.4.0" } }, "sha512-pBPWdu6MLKROBX05wSNKcNb++m5Er+KQ9QkB+WVM+pW2Kx9hoSrVTnu3BdkI5eBLZoKu/J6mW/B6i6bJB2ytXQ=="],
@@ -183,6 +189,12 @@
 
     "@pkgr/core": ["@pkgr/core@0.1.1", "", {}, "sha512-cq8o4cWH0ibXh9VGi5P20Tu9XF/0fFXl9EUinr9QfTM7a7p0oTA4iJRCQWppXR1Pg8dSM0UCItCkPwsk9qWWYA=="],
 
+    "@scalar/openapi-types": ["@scalar/openapi-types@0.1.1", "", {}, "sha512-NMy3QNk6ytcCoPUGJH0t4NNr36OWXgZhA3ormr3TvhX1NDgoF95wFyodGVH8xiHeUyn2/FxtETm8UBLbB5xEmg=="],
+
+    "@scalar/themes": ["@scalar/themes@0.9.86", "", { "dependencies": { "@scalar/types": "0.1.7" } }, "sha512-QUHo9g5oSWi+0Lm1vJY9TaMZRau8LHg+vte7q5BVTBnu6NuQfigCaN+ouQ73FqIVd96TwMO6Db+dilK1B+9row=="],
+
+    "@scalar/types": ["@scalar/types@0.0.12", "", { "dependencies": { "@scalar/openapi-types": "0.1.1", "@unhead/schema": "^1.9.5" } }, "sha512-XYZ36lSEx87i4gDqopQlGCOkdIITHHEvgkuJFrXFATQs9zHARop0PN0g4RZYWj+ZpCUclOcaOjbCt8JGe22mnQ=="],
+
     "@sinclair/typebox": ["@sinclair/typebox@0.34.33", "", {}, "sha512-5HAV9exOMcXRUxo+9iYB5n09XxzCXnfy4VTNW4xnDv+FgjzAGY989C28BIdljKqmF+ZltUwujE3aossvcVtq6g=="],
 
     "@tailwindcss/cli": ["@tailwindcss/cli@4.1.8", "", { "dependencies": { "@parcel/watcher": "^2.5.1", "@tailwindcss/node": "4.1.8", "@tailwindcss/oxide": "4.1.8", "enhanced-resolve": "^5.18.1", "mri": "^1.2.0", "picocolors": "^1.1.1", "tailwindcss": "4.1.8" }, "bin": { "tailwindcss": "dist/index.mjs" } }, "sha512-+6lkjXSr/68zWiabK3mVYVHmOq/SAHjJ13mR8spyB4LgUWZbWzU9kCSErlAUo+gK5aVfgqe8kY6Ltz9+nz5XYA=="],
@@ -257,6 +269,8 @@
 
     "@typescript-eslint/visitor-keys": ["@typescript-eslint/visitor-keys@8.34.0", "", { "dependencies": { "@typescript-eslint/types": "8.34.0", "eslint-visitor-keys": "^4.2.0" } }, "sha512-qHV7pW7E85A0x6qyrFn+O+q1k1p3tQCsqIZ1KZ5ESLXY57aTvUd3/a4rdPTeXisvhXn2VQG0VSKUqs8KHF2zcA=="],
 
+    "@unhead/schema": ["@unhead/schema@1.11.20", "", { "dependencies": { "hookable": "^5.5.3", "zhead": "^2.2.4" } }, "sha512-0zWykKAaJdm+/Y7yi/Yds20PrUK7XabLe9c3IRcjnwYmSWY6z0Cr19VIs3ozCj8P+GhR+/TI2mwtGlueCEYouA=="],
+
     "acorn": ["acorn@8.14.0", "", { "bin": { "acorn": "bin/acorn" } }, "sha512-cl669nCJTZBsL97OF4kUQm5g5hC2uihk0NxY3WENAC0TYdILVkAyHymAntgxGkl7K+t0cXIrH5siy5S4XkFycA=="],
 
     "acorn-jsx": ["acorn-jsx@5.3.2", "", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
@@ -385,6 +399,8 @@
 
     "hasown": ["hasown@2.0.2", "", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ=="],
 
+    "hookable": ["hookable@5.5.3", "", {}, "sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ=="],
+
     "ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
 
     "ignore": ["ignore@5.3.2", "", {}, "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g=="],
@@ -507,6 +523,8 @@
 
     "path-parse": ["path-parse@1.0.7", "", {}, "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw=="],
 
+    "pathe": ["pathe@1.1.2", "", {}, "sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ=="],
+
     "peek-readable": ["peek-readable@7.0.0", "", {}, "sha512-nri2TO5JE3/mRryik9LlHFT53cgHfRK0Lt0BAZQXku/AW3E6XLt2GaY8siWi7dvW/m1z0ecn+J+bpDa9ZN3IsQ=="],
 
     "picocolors": ["picocolors@1.1.1", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
@@ -597,6 +615,8 @@
 
     "type-check": ["type-check@0.4.0", "", { "dependencies": { "prelude-ls": "^1.2.1" } }, "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew=="],
 
+    "type-fest": ["type-fest@4.41.0", "", {}, "sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA=="],
+
     "typescript": ["typescript@5.8.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ=="],
 
     "typescript-eslint": ["typescript-eslint@8.34.0", "", { "dependencies": { "@typescript-eslint/eslint-plugin": "8.34.0", "@typescript-eslint/parser": "8.34.0", "@typescript-eslint/utils": "8.34.0" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0", "typescript": ">=4.8.4 <5.9.0" } }, "sha512-MRpfN7uYjTrTGigFCt8sRyNqJFhjN0WwZecldaqhWm+wy0gaRt8Edb/3cuUy0zdq2opJWT6iXINKAtewnDOltQ=="],
@@ -627,6 +647,8 @@
 
     "yocto-queue": ["yocto-queue@0.1.0", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
 
+    "zhead": ["zhead@2.2.4", "", {}, "sha512-8F0OI5dpWIA5IGG5NHUg9staDwz/ZPxZtvGVf01j7vHqSyZ0raHY+78atOVxRqb73AotX22uV1pXt3gYSstGag=="],
+
     "zod": ["zod@3.24.4", "", {}, "sha512-OdqJE9UDRPwWsrHjLN2F8bPxvwJBK22EHLWtanu0LSYr5YqzsaaW3RMgmjwr8Rypg5k+meEJdSPXJZXE/yqOMg=="],
 
     "zod-validation-error": ["zod-validation-error@3.4.0", "", { "peerDependencies": { "zod": "^3.18.0" } }, "sha512-ZOPR9SVY6Pb2qqO5XHt+MkkTRxGXb4EVtnjc9JpXUOtUB1T9Ru7mZOT361AN3MsetVe7R0a1KZshJDZdgp9miQ=="],
@@ -641,6 +663,8 @@
 
     "@humanfs/node/@humanwhocodes/retry": ["@humanwhocodes/retry@0.3.1", "", {}, "sha512-JBxkERygn7Bv/GbN5Rv8Ul6LVknS+5Bp6RgDC/O8gEBU/yeH5Ui5C/OlWrTb6qct7LjjfT6Re2NxB0ln0yYybA=="],
 
+    "@scalar/themes/@scalar/types": ["@scalar/types@0.1.7", "", { "dependencies": { "@scalar/openapi-types": "0.2.0", "@unhead/schema": "^1.11.11", "nanoid": "^5.1.5", "type-fest": "^4.20.0", "zod": "^3.23.8" } }, "sha512-irIDYzTQG2KLvFbuTI8k2Pz/R4JR+zUUSykVTbEMatkzMmVFnn1VzNSMlODbadycwZunbnL2tA27AXed9URVjw=="],
+
     "@tailwindcss/oxide/detect-libc": ["detect-libc@2.0.4", "", {}, "sha512-3UDv+G9CsCKO1WKMGw9fwq/SWJYbI0c5Y7LU1AXYoDdbhE2AHQ6N6Nb34sG8Fj7T5APy8qXDCKuuIHd1BR0tVA=="],
 
     "@tailwindcss/oxide-wasm32-wasi/@emnapi/core": ["@emnapi/core@1.4.3", "", { "dependencies": { "@emnapi/wasi-threads": "1.0.2", "tslib": "^2.4.0" }, "bundled": true }, "sha512-4m62DuCE07lw01soJwPiBGC0nAww0Q+RY70VZ+n49yDIO13yyinhbWCeNnaob0lakDtWQzSdtNWzJeOJt2ma+g=="],
@@ -673,6 +697,10 @@
 
     "wrap-ansi/ansi-styles": ["ansi-styles@4.3.0", "", { "dependencies": { "color-convert": "^2.0.1" } }, "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg=="],
 
+    "@scalar/themes/@scalar/types/@scalar/openapi-types": ["@scalar/openapi-types@0.2.0", "", { "dependencies": { "zod": "^3.23.8" } }, "sha512-waiKk12cRCqyUCWTOX0K1WEVX46+hVUK+zRPzAahDJ7G0TApvbNkuy5wx7aoUyEk++HHde0XuQnshXnt8jsddA=="],
+
+    "@scalar/themes/@scalar/types/nanoid": ["nanoid@5.1.5", "", { "bin": { "nanoid": "bin/nanoid.js" } }, "sha512-Ir/+ZpE9fDsNH0hQ3C68uyThDXzYcim2EqcZ8zn8Chtt1iylPT9xXJB0kPCnqzgcEGikO9RxSrh63MsmVCU7Fw=="],
+
     "@typescript-eslint/typescript-estree/minimatch/brace-expansion": ["brace-expansion@2.0.1", "", { "dependencies": { "balanced-match": "^1.0.0" } }, "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA=="],
 
     "cross-spawn/which/isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
diff --git a/docker-compose.README.md b/docker-compose.README.md
new file mode 100644
index 0000000..b8d2c83
--- /dev/null
+++ b/docker-compose.README.md
@@ -0,0 +1,161 @@
+# Docker Compose Configuration
+
+This project includes both `compose.yaml` (original) and `docker-compose.yml` (enhanced) for different use cases.
+
+## Files
+
+- **compose.yaml**: Original simple production deployment
+- **docker-compose.yml**: Enhanced configuration with development, monitoring, and API features
+
+## Quick Start
+
+### Production Mode
+```bash
+# Using original compose file
+docker compose -f compose.yaml up -d
+
+# Using enhanced compose file (production service only)
+docker compose up -d convertx
+```
+
+### Development Mode
+```bash
+# Start development server with hot reload
+docker compose --profile dev up convertx-dev
+
+# Start both production and development
+docker compose --profile dev up
+```
+
+## Services
+
+### convertx (Production)
+- Main application service
+- Port: 3000
+- Includes health checks and auto-restart
+
+### convertx-dev (Development)
+- Hot reload enabled
+- Port: 3001
+- Mounts source code for live editing
+- Profile: `dev`
+
+### api-docs (API Documentation)
+- Swagger UI for API documentation
+- Port: 3002
+- Profile: `docs`
+
+### monitoring stack
+- Prometheus (port 9090) and Grafana (port 3003)
+- Profile: `monitoring`
+
+## Profiles
+
+Use profiles to enable optional services:
+
+```bash
+# Development only
+docker compose --profile dev up
+
+# With API documentation
+docker compose --profile docs up
+
+# With monitoring
+docker compose --profile monitoring up
+
+# Everything
+docker compose --profile dev --profile docs --profile monitoring up
+```
+
+## Environment Variables
+
+Create a `.env` file for custom configuration:
+
+```env
+# JWT Configuration
+JWT_SECRET=your-secret-key-here
+
+# API Configuration
+API_ENABLED=true
+API_PREFIX=/api/v1
+API_RATE_LIMIT=100
+API_RATE_WINDOW=15m
+
+# Development
+HTTP_ALLOWED=false
+ALLOW_UNAUTHENTICATED=false
+
+# Timezone
+TZ=America/New_York
+
+# Monitoring
+GRAFANA_PASSWORD=secure-password
+```
+
+## Development Workflow
+
+1. **Start development environment**:
+   ```bash
+   docker compose --profile dev up convertx-dev
+   ```
+
+2. **Make code changes**: Edit files in `src/` - they'll auto-reload
+
+3. **Test production build**:
+   ```bash
+   docker compose up --build convertx
+   ```
+
+4. **View logs**:
+   ```bash
+   docker compose logs -f convertx-dev
+   ```
+
+## Building Images
+
+```bash
+# Build all images
+docker compose build
+
+# Build specific service
+docker compose build convertx
+
+# Build with no cache
+docker compose build --no-cache
+```
+
+## Data Persistence
+
+- Application data: `./data` directory (mounted to `/app/data`)
+- Prometheus data: `prometheus_data` volume
+- Grafana data: `grafana_data` volume
+
+## Networking
+
+All services are on the `convertx-network` by default. To expose services to other containers:
+
+```yaml
+external_service:
+  networks:
+    - convertx-network
+  external_links:
+    - convertx
+```
+
+## Troubleshooting
+
+1. **Port conflicts**: Change ports in docker-compose.yml if needed
+2. **Permission issues**: Ensure `./data` directory has correct permissions
+3. **Build failures**: Check Dockerfile and ensure all dependencies are available
+4. **Hot reload not working**: Verify volume mounts and file permissions
+
+## Production Deployment
+
+For production, consider:
+
+1. Use specific image tags instead of `latest`
+2. Set strong JWT_SECRET
+3. Disable HTTP_ALLOWED and ALLOW_UNAUTHENTICATED
+4. Configure proper backup for data directory
+5. Set up monitoring with the monitoring profile
+6. Use external database for scale
\ No newline at end of file
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..c344b9d
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,136 @@
+version: '3.8'
+
+services:
+  # Production-like service
+  convertx:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: release
+    image: convertx-openapi:local
+    container_name: convertx-prod
+    volumes:
+      - ./data:/app/data
+    environment:
+      - ACCOUNT_REGISTRATION=true
+      - JWT_SECRET=${JWT_SECRET:-aLongAndSecretStringUsedToSignTheJSONWebToken1234}
+      - HTTP_ALLOWED=${HTTP_ALLOWED:-false}
+      - ALLOW_UNAUTHENTICATED=${ALLOW_UNAUTHENTICATED:-false}
+      - AUTO_DELETE_EVERY_N_HOURS=${AUTO_DELETE_EVERY_N_HOURS:-24}
+      - WEBROOT=${WEBROOT:-}
+      - TZ=${TZ:-UTC}
+      # API-specific environment variables
+      - API_ENABLED=${API_ENABLED:-true}
+      - API_PREFIX=${API_PREFIX:-/api/v1}
+      - API_RATE_LIMIT=${API_RATE_LIMIT:-100}
+      - API_RATE_WINDOW=${API_RATE_WINDOW:-15m}
+      - API_KEY_ENABLED=${API_KEY_ENABLED:-true}
+    ports:
+      - "3000:3000"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 40s
+    restart: unless-stopped
+
+  # Development service with hot reload
+  convertx-dev:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: base
+    image: convertx-openapi:dev
+    container_name: convertx-dev
+    working_dir: /app
+    command: bun run --hot src/index.tsx
+    volumes:
+      - ./src:/app/src
+      - ./public:/app/public
+      - ./data:/app/data
+      - ./package.json:/app/package.json
+      - ./bun.lockb:/app/bun.lockb
+      - ./tsconfig.json:/app/tsconfig.json
+    environment:
+      - NODE_ENV=development
+      - ACCOUNT_REGISTRATION=true
+      - JWT_SECRET=dev-secret-key
+      - HTTP_ALLOWED=true
+      - ALLOW_UNAUTHENTICATED=true
+      - AUTO_DELETE_EVERY_N_HOURS=0
+      - WEBROOT=
+      - TZ=${TZ:-UTC}
+      # Development specific
+      - DEBUG=true
+      - LOG_LEVEL=debug
+    ports:
+      - "3001:3000"
+    profiles:
+      - dev
+
+  # API documentation server (when implemented)
+  api-docs:
+    image: swaggerapi/swagger-ui:latest
+    container_name: convertx-api-docs
+    environment:
+      - SWAGGER_JSON_URL=http://convertx:3000/api/v1/swagger.json
+      - BASE_URL=/api-docs
+    ports:
+      - "3002:8080"
+    depends_on:
+      - convertx
+    profiles:
+      - docs
+
+  # Database viewer for development
+  db-viewer:
+    image: sqlitebrowser/sqlitebrowser:latest
+    container_name: convertx-db-viewer
+    volumes:
+      - ./data:/data
+    environment:
+      - DISPLAY=${DISPLAY:-:0}
+    network_mode: host
+    profiles:
+      - debug
+
+  # Monitoring stack (optional)
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: convertx-prometheus
+    volumes:
+      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
+      - prometheus_data:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+    ports:
+      - "9090:9090"
+    profiles:
+      - monitoring
+
+  grafana:
+    image: grafana/grafana:latest
+    container_name: convertx-grafana
+    volumes:
+      - grafana_data:/var/lib/grafana
+      - ./monitoring/grafana/dashboards:/etc/grafana/provisioning/dashboards
+      - ./monitoring/grafana/datasources:/etc/grafana/provisioning/datasources
+    environment:
+      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD:-admin}
+      - GF_USERS_ALLOW_SIGN_UP=false
+    ports:
+      - "3003:3000"
+    depends_on:
+      - prometheus
+    profiles:
+      - monitoring
+
+volumes:
+  prometheus_data:
+  grafana_data:
+
+networks:
+  default:
+    name: convertx-network
\ No newline at end of file
diff --git a/package.json b/package.json
index 4ac248a..3da8742 100644
--- a/package.json
+++ b/package.json
@@ -18,6 +18,8 @@
     "@elysiajs/html": "^1.3.0",
     "@elysiajs/jwt": "^1.3.1",
     "@elysiajs/static": "^1.3.0",
+    "@elysiajs/swagger": "^1.3.1",
+    "@elysiajs/cors": "^1.3.0",
     "@kitajs/html": "^4.2.9",
     "elysia": "^1.3.4",
     "sanitize-filename": "^1.6.3",
diff --git a/src/api/middleware/auth.ts b/src/api/middleware/auth.ts
new file mode 100644
index 0000000..aba3477
--- /dev/null
+++ b/src/api/middleware/auth.ts
@@ -0,0 +1,57 @@
+import { Elysia } from "elysia";
+import { userService } from "../../pages/user";
+import db from "../../db/db";
+import { User } from "../../db/types";
+import { ALLOW_UNAUTHENTICATED, API_KEY_ENABLED } from "../../helpers/env";
+
+export const authMiddleware = new Elysia({ name: "api/auth-middleware" })
+  .use(userService)
+  .derive(async ({ jwt, cookie: { auth }, headers }) => {
+    // Check for API key first
+    if (API_KEY_ENABLED) {
+      const apiKey = headers["x-api-key"];
+      if (apiKey) {
+        // TODO: Implement API key validation
+        // For now, we'll skip to JWT auth
+      }
+    }
+
+    // Check for Bearer token in Authorization header
+    const authHeader = headers.authorization;
+    let token = auth?.value;
+
+    if (authHeader?.startsWith("Bearer ")) {
+      token = authHeader.substring(7);
+    }
+
+    // If no token and unauthenticated access is allowed, return user 0
+    if (!token && ALLOW_UNAUTHENTICATED) {
+      return {
+        user: {
+          id: 0,
+          email: "anonymous@localhost",
+        },
+      };
+    }
+
+    if (!token) {
+      return { user: null };
+    }
+
+    try {
+      const payload = await jwt.verify(token);
+      if (!payload || typeof payload !== 'object' || !('id' in payload)) {
+        return { user: null };
+      }
+
+      const user = db
+        .query("SELECT id, email FROM users WHERE id = ?")
+        .as(User)
+        .get(payload.id);
+
+      return { user: user || null };
+    } catch (error) {
+      console.error("JWT verification error:", error);
+      return { user: null };
+    }
+  });
\ No newline at end of file
diff --git a/src/api/types.ts b/src/api/types.ts
new file mode 100644
index 0000000..adcbc13
--- /dev/null
+++ b/src/api/types.ts
@@ -0,0 +1,10 @@
+// API type definitions
+
+export interface AuthenticatedUser {
+  id: number;
+  email: string;
+}
+
+export interface ApiContext {
+  user: AuthenticatedUser | null;
+}
\ No newline at end of file
diff --git a/src/api/v1/auth.ts b/src/api/v1/auth.ts
new file mode 100644
index 0000000..d3bf098
--- /dev/null
+++ b/src/api/v1/auth.ts
@@ -0,0 +1,330 @@
+import { Elysia, t } from "elysia";
+import { userService } from "../../pages/user";
+import db from "../../db/db";
+import { User } from "../../db/types";
+import { ACCOUNT_REGISTRATION, ALLOW_UNAUTHENTICATED } from "../../helpers/env";
+
+export const auth = new Elysia({ prefix: "/auth" })
+  .use(userService)
+  .post(
+    "/login",
+    async ({ body: { email, password }, jwt, cookie: { auth }, set }) => {
+      const user = db
+        .query("SELECT * FROM users WHERE email = ?")
+        .as(User)
+        .get(email);
+
+      if (!user) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "Invalid email or password",
+          code: "INVALID_CREDENTIALS",
+        };
+      }
+
+      const isPasswordValid = await Bun.password.verify(password, user.password);
+      if (!isPasswordValid) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "Invalid email or password",
+          code: "INVALID_CREDENTIALS",
+        };
+      }
+
+      const token = await jwt.sign({ id: user.id.toString() });
+      
+      // Set cookie for web UI compatibility
+      auth?.set({
+        value: token,
+        httpOnly: true,
+        maxAge: 7 * 86400, // 7 days
+        path: "/",
+      });
+
+      return {
+        success: true,
+        data: {
+          token,
+          user: {
+            id: user.id,
+            email: user.email,
+          },
+          expiresIn: "7d",
+        },
+      };
+    },
+    {
+      body: t.Object({
+        email: t.String({ format: "email" }),
+        password: t.String({ minLength: 1 }),
+      }),
+      detail: {
+        tags: ["auth"],
+        summary: "Login to get JWT token",
+        description: "Authenticate with email and password to receive a JWT token",
+        responses: {
+          200: {
+            description: "Successful login",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        token: { type: "string" },
+                        user: {
+                          type: "object",
+                          properties: {
+                            id: { type: "number" },
+                            email: { type: "string" },
+                          },
+                        },
+                        expiresIn: { type: "string", example: "7d" },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          401: {
+            $ref: "#/components/responses/Unauthorized",
+          },
+        },
+      },
+    }
+  )
+  .post(
+    "/register",
+    async ({ body: { email, password }, jwt, cookie: { auth }, set }) => {
+      if (!ACCOUNT_REGISTRATION) {
+        set.status = 403;
+        return {
+          success: false,
+          error: "Registration is disabled",
+          code: "REGISTRATION_DISABLED",
+        };
+      }
+
+      // Check if user already exists
+      const existingUser = db
+        .query("SELECT id FROM users WHERE email = ?")
+        .get(email);
+
+      if (existingUser) {
+        set.status = 409;
+        return {
+          success: false,
+          error: "Email already registered",
+          code: "EMAIL_EXISTS",
+        };
+      }
+
+      // Hash password and create user
+      const hashedPassword = await Bun.password.hash(password);
+      const result = db
+        .query("INSERT INTO users (email, password) VALUES (?, ?) RETURNING id, email")
+        .as(User)
+        .get(email, hashedPassword);
+
+      if (!result) {
+        set.status = 500;
+        return {
+          success: false,
+          error: "Failed to create user",
+          code: "CREATION_FAILED",
+        };
+      }
+
+      const token = await jwt.sign({ id: result.id.toString() });
+      
+      // Set cookie for web UI compatibility
+      auth?.set({
+        value: token,
+        httpOnly: true,
+        maxAge: 7 * 86400, // 7 days
+        path: "/",
+      });
+
+      return {
+        success: true,
+        data: {
+          token,
+          user: {
+            id: result.id,
+            email: result.email,
+          },
+          expiresIn: "7d",
+        },
+      };
+    },
+    {
+      body: t.Object({
+        email: t.String({ format: "email" }),
+        password: t.String({ minLength: 8 }),
+      }),
+      detail: {
+        tags: ["auth"],
+        summary: "Register a new account",
+        description: "Create a new user account (if registration is enabled)",
+        responses: {
+          200: {
+            description: "Successful registration",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        token: { type: "string" },
+                        user: {
+                          type: "object",
+                          properties: {
+                            id: { type: "number" },
+                            email: { type: "string" },
+                          },
+                        },
+                        expiresIn: { type: "string", example: "7d" },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          403: {
+            description: "Registration disabled",
+          },
+          409: {
+            description: "Email already exists",
+          },
+        },
+      },
+    }
+  )
+  .get(
+    "/me",
+    async ({ jwt, cookie: { auth }, headers, set }) => {
+      // Check for Bearer token in Authorization header
+      const authHeader = headers.authorization;
+      let token = auth?.value;
+
+      if (authHeader?.startsWith("Bearer ")) {
+        token = authHeader.substring(7);
+      }
+
+      if (!token) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "No authentication token provided",
+          code: "NO_TOKEN",
+        };
+      }
+
+      const payload = await jwt.verify(token);
+      if (!payload) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "Invalid or expired token",
+          code: "INVALID_TOKEN",
+        };
+      }
+
+      const user = db
+        .query("SELECT id, email FROM users WHERE id = ?")
+        .as(User)
+        .get(payload.id);
+
+      if (!user) {
+        set.status = 404;
+        return {
+          success: false,
+          error: "User not found",
+          code: "USER_NOT_FOUND",
+        };
+      }
+
+      return {
+        success: true,
+        data: {
+          user: {
+            id: user.id,
+            email: user.email,
+          },
+        },
+      };
+    },
+    {
+      detail: {
+        tags: ["auth"],
+        summary: "Get current user info",
+        description: "Get information about the currently authenticated user",
+        security: [{ bearerAuth: [] }],
+        responses: {
+          200: {
+            description: "Current user information",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        user: {
+                          type: "object",
+                          properties: {
+                            id: { type: "number" },
+                            email: { type: "string" },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          401: {
+            $ref: "#/components/responses/Unauthorized",
+          },
+        },
+      },
+    }
+  )
+  .post(
+    "/logout",
+    async ({ cookie: { auth } }) => {
+      auth?.remove();
+      
+      return {
+        success: true,
+        data: {
+          message: "Logged out successfully",
+        },
+      };
+    },
+    {
+      detail: {
+        tags: ["auth"],
+        summary: "Logout",
+        description: "Clear authentication cookie (for web UI)",
+        responses: {
+          200: {
+            description: "Successful logout",
+          },
+        },
+      },
+    }
+  );
\ No newline at end of file
diff --git a/src/api/v1/conversions.ts b/src/api/v1/conversions.ts
new file mode 100644
index 0000000..331b6c4
--- /dev/null
+++ b/src/api/v1/conversions.ts
@@ -0,0 +1,137 @@
+import { Elysia, t } from "elysia";
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import db from "../../db/db";
+import { Jobs } from "../../db/types";
+import { handleConvert } from "../../converters/main";
+import { authMiddleware } from "../middleware/auth";
+import { outputDir, uploadsDir } from "../../index";
+import { ALLOW_UNAUTHENTICATED } from "../../helpers/env";
+
+export const conversions = new Elysia({ prefix: "/conversions" })
+  .use(authMiddleware)
+  .post(
+    "/",
+    async ({ body, set, ...ctx }: any) => {
+      const user = (ctx as any).user;
+      if (!user && !ALLOW_UNAUTHENTICATED) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "Authentication required",
+          code: "AUTH_REQUIRED",
+        };
+      }
+
+      const userId = user?.id || 0;
+      const jobId = randomUUID();
+      
+      // Validate inputs
+      if (!body.files || body.files.length === 0) {
+        set.status = 400;
+        return {
+          success: false,
+          error: "No files provided",
+          code: "NO_FILES",
+        };
+      }
+
+      if (!body.converter || !body.outputFormat) {
+        set.status = 400;
+        return {
+          success: false,
+          error: "Converter and output format are required",
+          code: "MISSING_PARAMS",
+        };
+      }
+
+      // Create directories
+      const userUploadsDir = `${uploadsDir}${userId}/${jobId}/`;
+      const userOutputDir = `${outputDir}${userId}/${jobId}/`;
+      
+      await mkdir(userUploadsDir, { recursive: true });
+      await mkdir(userOutputDir, { recursive: true });
+
+      // Create job in database
+      db.query("INSERT INTO jobs (id, user_id, date_created, status, num_files) VALUES (?, ?, ?, ?, ?)")
+        .run(jobId, userId, new Date().toISOString(), "processing", body.files.length);
+
+      // TODO: Handle file uploads or URLs
+      // For now, assume files are already uploaded
+      const fileNames = body.files.map(f => f.name);
+
+      // Start conversion asynchronously
+      handleConvert(
+        fileNames,
+        userUploadsDir,
+        userOutputDir,
+        body.outputFormat,
+        body.converter,
+        { value: jobId }
+      ).then(() => {
+        db.query("UPDATE jobs SET status = ? WHERE id = ?").run("completed", jobId);
+      }).catch((error) => {
+        console.error("Conversion error:", error);
+        db.query("UPDATE jobs SET status = ? WHERE id = ?").run("failed", jobId);
+      });
+
+      return {
+        success: true,
+        data: {
+          jobId,
+          status: "processing",
+          message: "Conversion started",
+          pollUrl: `/api/v1/jobs/${jobId}`,
+        },
+      };
+    },
+    {
+      body: t.Object({
+        files: t.Array(
+          t.Object({
+            name: t.String(),
+            // Add more file properties as needed
+          })
+        ),
+        converter: t.String(),
+        outputFormat: t.String(),
+        options: t.Optional(t.Object({})),
+      }),
+      detail: {
+        tags: ["conversions"],
+        summary: "Start a conversion job",
+        description: "Upload files and start a conversion job",
+        security: [{ bearerAuth: [] }, { apiKey: [] }],
+        responses: {
+          200: {
+            description: "Conversion job started",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        jobId: { type: "string", format: "uuid" },
+                        status: { type: "string", example: "processing" },
+                        message: { type: "string" },
+                        pollUrl: { type: "string" },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          400: {
+            $ref: "#/components/responses/BadRequest",
+          },
+          401: {
+            $ref: "#/components/responses/Unauthorized",
+          },
+        },
+      },
+    }
+  );
\ No newline at end of file
diff --git a/src/api/v1/converters.ts b/src/api/v1/converters.ts
new file mode 100644
index 0000000..18ac95f
--- /dev/null
+++ b/src/api/v1/converters.ts
@@ -0,0 +1,226 @@
+import { Elysia, t } from "elysia";
+import { getAllTargets, getAllInputs, getPossibleTargets } from "../../converters/main";
+
+export const converters = new Elysia({ prefix: "/converters" })
+  .get(
+    "/",
+    () => {
+      const allTargets = getAllTargets();
+      const converterList = Object.entries(allTargets).map(([name, outputs]) => ({
+        name,
+        outputs: [...new Set(outputs)].sort(),
+        inputs: [...new Set(getAllInputs(name))].sort(),
+      }));
+
+      return {
+        success: true,
+        data: {
+          converters: converterList,
+          total: converterList.length,
+        },
+      };
+    },
+    {
+      detail: {
+        tags: ["converters"],
+        summary: "List all converters",
+        description: "Get a list of all available file converters with their supported input and output formats",
+        responses: {
+          200: {
+            description: "List of converters",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        converters: {
+                          type: "array",
+                          items: {
+                            type: "object",
+                            properties: {
+                              name: { type: "string", example: "ffmpeg" },
+                              outputs: {
+                                type: "array",
+                                items: { type: "string" },
+                                example: ["mp4", "webm", "mp3"],
+                              },
+                              inputs: {
+                                type: "array",
+                                items: { type: "string" },
+                                example: ["avi", "mov", "mkv"],
+                              },
+                            },
+                          },
+                        },
+                        total: { type: "number", example: 17 },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+  )
+  .get(
+    "/:name",
+    ({ params: { name }, set }) => {
+      const allTargets = getAllTargets();
+      
+      if (!allTargets[name]) {
+        set.status = 404;
+        return {
+          success: false,
+          error: "Converter not found",
+          code: "CONVERTER_NOT_FOUND",
+        };
+      }
+
+      const outputs = [...new Set(allTargets[name])].sort();
+      const inputs = [...new Set(getAllInputs(name))].sort();
+
+      return {
+        success: true,
+        data: {
+          converter: {
+            name,
+            outputs,
+            inputs,
+            totalFormats: inputs.length + outputs.length,
+          },
+        },
+      };
+    },
+    {
+      params: t.Object({
+        name: t.String(),
+      }),
+      detail: {
+        tags: ["converters"],
+        summary: "Get converter details",
+        description: "Get detailed information about a specific converter",
+        responses: {
+          200: {
+            description: "Converter details",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        converter: {
+                          type: "object",
+                          properties: {
+                            name: { type: "string", example: "ffmpeg" },
+                            outputs: {
+                              type: "array",
+                              items: { type: "string" },
+                            },
+                            inputs: {
+                              type: "array",
+                              items: { type: "string" },
+                            },
+                            totalFormats: { type: "number" },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          404: {
+            $ref: "#/components/responses/NotFound",
+          },
+        },
+      },
+    }
+  )
+  .get(
+    "/formats/:format",
+    ({ params: { format }, set }) => {
+      const possibleTargets = getPossibleTargets(format);
+      
+      if (!possibleTargets || Object.keys(possibleTargets).length === 0) {
+        set.status = 404;
+        return {
+          success: false,
+          error: "No converters support this format",
+          code: "FORMAT_NOT_SUPPORTED",
+        };
+      }
+
+      const converters = Object.entries(possibleTargets).map(([converter, outputs]) => ({
+        converter,
+        outputs: outputs.sort(),
+      }));
+
+      return {
+        success: true,
+        data: {
+          format,
+          converters,
+          totalConverters: converters.length,
+        },
+      };
+    },
+    {
+      params: t.Object({
+        format: t.String(),
+      }),
+      detail: {
+        tags: ["converters"],
+        summary: "Get converters for format",
+        description: "Find which converters can process a specific input format",
+        responses: {
+          200: {
+            description: "Available converters for the format",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        format: { type: "string", example: "pdf" },
+                        converters: {
+                          type: "array",
+                          items: {
+                            type: "object",
+                            properties: {
+                              converter: { type: "string", example: "libreoffice" },
+                              outputs: {
+                                type: "array",
+                                items: { type: "string" },
+                                example: ["docx", "html", "txt"],
+                              },
+                            },
+                          },
+                        },
+                        totalConverters: { type: "number" },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          404: {
+            description: "Format not supported",
+          },
+        },
+      },
+    }
+  );
\ No newline at end of file
diff --git a/src/api/v1/debug.ts b/src/api/v1/debug.ts
new file mode 100644
index 0000000..94ef745
--- /dev/null
+++ b/src/api/v1/debug.ts
@@ -0,0 +1,19 @@
+import { Elysia } from "elysia";
+import { authMiddleware } from "../middleware/auth";
+
+export const debug = new Elysia({ prefix: "/debug" })
+  .use(authMiddleware)
+  .get("/auth", ({ headers, ...ctx }: any) => {
+    const user = (ctx as any).user;
+    return {
+      success: true,
+      data: {
+        headers: {
+          authorization: headers.authorization,
+          cookie: headers.cookie,
+        },
+        user: user || null,
+        hasUser: !!user,
+      },
+    };
+  });
\ No newline at end of file
diff --git a/src/api/v1/files.ts b/src/api/v1/files.ts
new file mode 100644
index 0000000..cc92bdd
--- /dev/null
+++ b/src/api/v1/files.ts
@@ -0,0 +1,252 @@
+import { Elysia, t } from "elysia";
+import { existsSync, createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import db from "../../db/db";
+import { Jobs, Filename } from "../../db/types";
+import { authMiddleware } from "../middleware/auth";
+import { outputDir } from "../../index";
+import { ALLOW_UNAUTHENTICATED } from "../../helpers/env";
+
+export const files = new Elysia({ prefix: "/files" })
+  .use(authMiddleware)
+  .get(
+    "/:jobId/:fileName",
+    async ({ params: { jobId, fileName }, set, ...ctx }: any) => {
+      const user = (ctx as any).user;
+      if (!user && !ALLOW_UNAUTHENTICATED) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "Authentication required",
+          code: "AUTH_REQUIRED",
+        };
+      }
+
+      const userId = user?.id || 0;
+
+      // Verify job ownership
+      const job = db
+        .query("SELECT id FROM jobs WHERE id = ? AND user_id = ?")
+        .get(jobId, userId);
+
+      if (!job) {
+        set.status = 404;
+        return {
+          success: false,
+          error: "Job not found",
+          code: "JOB_NOT_FOUND",
+        };
+      }
+
+      // Verify file exists in database
+      const file = db
+        .query("SELECT * FROM file_names WHERE job_id = ? AND output_file_name = ?")
+        .as(Filename)
+        .get(jobId, fileName);
+
+      if (!file) {
+        set.status = 404;
+        return {
+          success: false,
+          error: "File not found",
+          code: "FILE_NOT_FOUND",
+        };
+      }
+
+      // Check if file exists on disk
+      const filePath = path.join(outputDir, String(userId), jobId, fileName);
+      
+      if (!existsSync(filePath)) {
+        set.status = 404;
+        return {
+          success: false,
+          error: "File not found on disk",
+          code: "FILE_NOT_FOUND",
+        };
+      }
+
+      // Get file stats
+      const stats = await stat(filePath);
+      
+      // Set appropriate headers
+      set.headers["content-type"] = getMimeType(fileName);
+      set.headers["content-length"] = String(stats.size);
+      set.headers["content-disposition"] = `attachment; filename="${fileName}"`;
+
+      // Return file stream
+      return new Response(Bun.file(filePath));
+    },
+    {
+      params: t.Object({
+        jobId: t.String(),
+        fileName: t.String(),
+      }),
+      detail: {
+        tags: ["files"],
+        summary: "Download converted file",
+        description: "Download a specific converted file from a job",
+        security: [{ bearerAuth: [] }, { apiKey: [] }],
+        responses: {
+          200: {
+            description: "File content",
+            content: {
+              "application/octet-stream": {
+                schema: {
+                  type: "string",
+                  format: "binary",
+                },
+              },
+            },
+          },
+          401: {
+            $ref: "#/components/responses/Unauthorized",
+          },
+          404: {
+            $ref: "#/components/responses/NotFound",
+          },
+        },
+      },
+    }
+  )
+  .get(
+    "/:jobId",
+    ({ params: { jobId }, set, ...ctx }: any) => {
+      const user = (ctx as any).user;
+      if (!user && !ALLOW_UNAUTHENTICATED) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "Authentication required",
+          code: "AUTH_REQUIRED",
+        };
+      }
+
+      const userId = user?.id || 0;
+
+      // Verify job ownership
+      const job = db
+        .query("SELECT * FROM jobs WHERE id = ? AND user_id = ?")
+        .as(Jobs)
+        .get(jobId, userId);
+
+      if (!job) {
+        set.status = 404;
+        return {
+          success: false,
+          error: "Job not found",
+          code: "JOB_NOT_FOUND",
+        };
+      }
+
+      // Get all files for this job
+      const files = db
+        .query("SELECT * FROM file_names WHERE job_id = ?")
+        .as(Filename)
+        .all(jobId);
+
+      const fileList = files.map(file => {
+        const filePath = path.join(outputDir, String(userId), jobId, file.output_file_name);
+        const exists = existsSync(filePath);
+        
+        return {
+          id: file.id,
+          fileName: file.file_name,
+          outputFileName: file.output_file_name,
+          status: file.status,
+          exists,
+          downloadUrl: exists ? `/api/v1/files/${jobId}/${file.output_file_name}` : null,
+        };
+      });
+
+      return {
+        success: true,
+        data: {
+          jobId,
+          status: job.status,
+          files: fileList,
+          total: fileList.length,
+        },
+      };
+    },
+    {
+      params: t.Object({
+        jobId: t.String(),
+      }),
+      detail: {
+        tags: ["files"],
+        summary: "List job files",
+        description: "Get a list of all files in a conversion job",
+        security: [{ bearerAuth: [] }, { apiKey: [] }],
+        responses: {
+          200: {
+            description: "List of files",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        jobId: { type: "string", format: "uuid" },
+                        status: { type: "string" },
+                        files: {
+                          type: "array",
+                          items: {
+                            type: "object",
+                            properties: {
+                              id: { type: "number" },
+                              fileName: { type: "string" },
+                              outputFileName: { type: "string" },
+                              status: { type: "string" },
+                              exists: { type: "boolean" },
+                              downloadUrl: { type: "string", nullable: true },
+                            },
+                          },
+                        },
+                        total: { type: "number" },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          401: {
+            $ref: "#/components/responses/Unauthorized",
+          },
+          404: {
+            $ref: "#/components/responses/NotFound",
+          },
+        },
+      },
+    }
+  );
+
+// Helper function to determine MIME type
+function getMimeType(fileName: string): string {
+  const ext = path.extname(fileName).toLowerCase();
+  const mimeTypes: Record<string, string> = {
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".mp4": "video/mp4",
+    ".mp3": "audio/mpeg",
+    ".zip": "application/zip",
+    ".txt": "text/plain",
+    ".html": "text/html",
+    ".css": "text/css",
+    ".js": "application/javascript",
+    ".json": "application/json",
+  };
+  
+  return mimeTypes[ext] || "application/octet-stream";
+}
\ No newline at end of file
diff --git a/src/api/v1/health.ts b/src/api/v1/health.ts
new file mode 100644
index 0000000..0ce2a96
--- /dev/null
+++ b/src/api/v1/health.ts
@@ -0,0 +1,83 @@
+import { Elysia } from "elysia";
+import db from "../../db/db";
+
+export const health = new Elysia()
+  .get(
+    "/health",
+    async () => {
+      try {
+        // Check database connection
+        const dbCheck = db.query("SELECT 1").get();
+        const dbHealthy = dbCheck !== null;
+
+        // Check disk space (simplified check)
+        const diskHealthy = true; // TODO: Implement actual disk space check
+
+        // Check converter availability (simplified)
+        const convertersHealthy = true; // TODO: Check if converters are installed
+
+        const healthy = dbHealthy && diskHealthy && convertersHealthy;
+
+        return {
+          success: true,
+          data: {
+            status: healthy ? "healthy" : "unhealthy",
+            timestamp: new Date().toISOString(),
+            checks: {
+              database: dbHealthy ? "ok" : "error",
+              disk: diskHealthy ? "ok" : "error",
+              converters: convertersHealthy ? "ok" : "error",
+            },
+            version: process.env.npm_package_version || "unknown",
+          },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          data: {
+            status: "unhealthy",
+            timestamp: new Date().toISOString(),
+            error: error instanceof Error ? error.message : "Unknown error",
+          },
+        };
+      }
+    },
+    {
+      detail: {
+        tags: ["health"],
+        summary: "Health check endpoint",
+        description: "Check the health status of the API and its dependencies",
+        responses: {
+          200: {
+            description: "Health status",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean" },
+                    data: {
+                      type: "object",
+                      properties: {
+                        status: { type: "string", enum: ["healthy", "unhealthy"] },
+                        timestamp: { type: "string", format: "date-time" },
+                        checks: {
+                          type: "object",
+                          properties: {
+                            database: { type: "string", enum: ["ok", "error"] },
+                            disk: { type: "string", enum: ["ok", "error"] },
+                            converters: { type: "string", enum: ["ok", "error"] },
+                          },
+                        },
+                        version: { type: "string" },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    }
+  );
\ No newline at end of file
diff --git a/src/api/v1/index.ts b/src/api/v1/index.ts
new file mode 100644
index 0000000..14b0ad5
--- /dev/null
+++ b/src/api/v1/index.ts
@@ -0,0 +1,213 @@
+import { cors } from "@elysiajs/cors";
+import { swagger } from "@elysiajs/swagger";
+import { Elysia } from "elysia";
+import { API_ENABLED, API_PREFIX } from "../../helpers/env";
+import { auth } from "./auth";
+import { converters } from "./converters";
+import { conversions } from "./conversions";
+import { files } from "./files";
+import { health } from "./health";
+import { jobs } from "./jobs";
+import { debug } from "./debug";
+
+// Main API router
+export const api = new Elysia({
+  prefix: API_PREFIX || "/api/v1",
+  name: "api/v1",
+})
+  .use(
+    cors({
+      origin: true,
+      credentials: true,
+      methods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
+      allowedHeaders: ["Content-Type", "Authorization", "X-API-Key"],
+      exposeHeaders: ["X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset"],
+    })
+  )
+  .use(
+    swagger({
+      documentation: {
+        info: {
+          title: "ConvertX API",
+          version: "1.0.0",
+          description: "File conversion API supporting 1000+ formats",
+          contact: {
+            name: "ConvertX Support",
+            email: "support@convertx.local",
+          },
+        },
+        tags: [
+          { name: "auth", description: "Authentication endpoints" },
+          { name: "converters", description: "List available converters" },
+          { name: "conversions", description: "File conversion operations" },
+          { name: "jobs", description: "Job management" },
+          { name: "files", description: "File operations" },
+          { name: "health", description: "Health check" },
+        ],
+        servers: [
+          {
+            url: "http://localhost:3110/api/v1",
+            description: "Local development server",
+          },
+          {
+            url: "https://convertx.example.com/api/v1",
+            description: "Production server",
+          },
+        ],
+        security: [
+          {
+            bearerAuth: [],
+          },
+          {
+            apiKey: [],
+          },
+        ],
+        components: {
+          securitySchemes: {
+            bearerAuth: {
+              type: "http",
+              scheme: "bearer",
+              bearerFormat: "JWT",
+              description: "JWT authentication token",
+            },
+            apiKey: {
+              type: "apiKey",
+              in: "header",
+              name: "X-API-Key",
+              description: "API key for programmatic access",
+            },
+          },
+          schemas: {
+            Error: {
+              type: "object",
+              properties: {
+                success: { type: "boolean", example: false },
+                error: { type: "string", example: "Error message" },
+                code: { type: "string", example: "ERROR_CODE" },
+              },
+              required: ["success", "error"],
+            },
+            Success: {
+              type: "object",
+              properties: {
+                success: { type: "boolean", example: true },
+                data: { type: "object" },
+              },
+              required: ["success"],
+            },
+          },
+          responses: {
+            Unauthorized: {
+              description: "Unauthorized",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/Error",
+                  },
+                  example: {
+                    success: false,
+                    error: "Unauthorized",
+                    code: "UNAUTHORIZED",
+                  },
+                },
+              },
+            },
+            NotFound: {
+              description: "Resource not found",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/Error",
+                  },
+                  example: {
+                    success: false,
+                    error: "Resource not found",
+                    code: "NOT_FOUND",
+                  },
+                },
+              },
+            },
+            BadRequest: {
+              description: "Bad request",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/Error",
+                  },
+                  example: {
+                    success: false,
+                    error: "Invalid request parameters",
+                    code: "BAD_REQUEST",
+                  },
+                },
+              },
+            },
+            ServerError: {
+              description: "Internal server error",
+              content: {
+                "application/json": {
+                  schema: {
+                    $ref: "#/components/schemas/Error",
+                  },
+                  example: {
+                    success: false,
+                    error: "Internal server error",
+                    code: "INTERNAL_ERROR",
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      path: "/swagger",
+      exclude: ["/swagger", "/swagger/json"],
+    })
+  )
+  .onError(({ code, error, set }) => {
+    console.error(`API Error [${code}]:`, error);
+    
+    switch (code) {
+      case "NOT_FOUND":
+        set.status = 404;
+        return {
+          success: false,
+          error: "Endpoint not found",
+          code: "NOT_FOUND",
+        };
+      case "VALIDATION":
+        set.status = 400;
+        return {
+          success: false,
+          error: "Validation error",
+          code: "VALIDATION_ERROR",
+          details: error.message,
+        };
+      case "INTERNAL_SERVER_ERROR":
+        set.status = 500;
+        return {
+          success: false,
+          error: "Internal server error",
+          code: "INTERNAL_ERROR",
+        };
+      default:
+        set.status = 500;
+        return {
+          success: false,
+          error: "An unexpected error occurred",
+          code: "UNKNOWN_ERROR",
+        };
+    }
+  });
+
+// Only mount API routes if API is enabled
+if (API_ENABLED) {
+  api
+    .use(health)
+    .use(auth)
+    .use(converters)
+    .use(conversions)
+    .use(jobs)
+    .use(files)
+    .use(debug);
+}
\ No newline at end of file
diff --git a/src/api/v1/jobs.ts b/src/api/v1/jobs.ts
new file mode 100644
index 0000000..99d4907
--- /dev/null
+++ b/src/api/v1/jobs.ts
@@ -0,0 +1,300 @@
+import { Elysia, t } from "elysia";
+import db from "../../db/db";
+import { Jobs, Filename } from "../../db/types";
+import { authMiddleware } from "../middleware/auth";
+import { ALLOW_UNAUTHENTICATED } from "../../helpers/env";
+
+export const jobs = new Elysia({ prefix: "/jobs" })
+  .use(authMiddleware)
+  .get(
+    "/",
+    ({ query, set, ...ctx }: any) => {
+      const user = (ctx as any).user;
+      if (!user && !ALLOW_UNAUTHENTICATED) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "Authentication required",
+          code: "AUTH_REQUIRED",
+        };
+      }
+
+      const userId = user?.id || 0;
+      const limit = query.limit || 20;
+      const offset = query.offset || 0;
+
+      const jobs = db
+        .query("SELECT * FROM jobs WHERE user_id = ? ORDER BY date_created DESC LIMIT ? OFFSET ?")
+        .as(Jobs)
+        .all(userId, limit, offset);
+
+      const total = db
+        .query("SELECT COUNT(*) as count FROM jobs WHERE user_id = ?")
+        .get(userId) as { count: number };
+
+      return {
+        success: true,
+        data: {
+          jobs: jobs.map(job => ({
+            id: job.id,
+            status: job.status,
+            dateCreated: job.date_created,
+            numFiles: job.num_files,
+          })),
+          pagination: {
+            limit,
+            offset,
+            total: total.count,
+          },
+        },
+      };
+    },
+    {
+      query: t.Object({
+        limit: t.Optional(t.Number({ minimum: 1, maximum: 100 })),
+        offset: t.Optional(t.Number({ minimum: 0 })),
+      }),
+      detail: {
+        tags: ["jobs"],
+        summary: "List user's jobs",
+        description: "Get a list of all conversion jobs for the authenticated user",
+        security: [{ bearerAuth: [] }, { apiKey: [] }],
+        responses: {
+          200: {
+            description: "List of jobs",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        jobs: {
+                          type: "array",
+                          items: {
+                            type: "object",
+                            properties: {
+                              id: { type: "string", format: "uuid" },
+                              status: { type: "string", enum: ["not started", "processing", "completed", "failed"] },
+                              dateCreated: { type: "string", format: "date-time" },
+                              numFiles: { type: "number" },
+                            },
+                          },
+                        },
+                        pagination: {
+                          type: "object",
+                          properties: {
+                            limit: { type: "number" },
+                            offset: { type: "number" },
+                            total: { type: "number" },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          401: {
+            $ref: "#/components/responses/Unauthorized",
+          },
+        },
+      },
+    }
+  )
+  .get(
+    "/:id",
+    ({ params: { id }, set, ...ctx }: any) => {
+      const user = (ctx as any).user;
+      if (!user && !ALLOW_UNAUTHENTICATED) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "Authentication required",
+          code: "AUTH_REQUIRED",
+        };
+      }
+
+      const userId = user?.id || 0;
+
+      const job = db
+        .query("SELECT * FROM jobs WHERE id = ? AND user_id = ?")
+        .as(Jobs)
+        .get(id, userId);
+
+      if (!job) {
+        set.status = 404;
+        return {
+          success: false,
+          error: "Job not found",
+          code: "JOB_NOT_FOUND",
+        };
+      }
+
+      const files = db
+        .query("SELECT * FROM file_names WHERE job_id = ?")
+        .as(Filename)
+        .all(id);
+
+      return {
+        success: true,
+        data: {
+          job: {
+            id: job.id,
+            status: job.status,
+            dateCreated: job.date_created,
+            numFiles: job.num_files,
+            files: files.map(file => ({
+              id: file.id,
+              fileName: file.file_name,
+              outputFileName: file.output_file_name,
+              status: file.status,
+            })),
+          },
+        },
+      };
+    },
+    {
+      params: t.Object({
+        id: t.String(),
+      }),
+      detail: {
+        tags: ["jobs"],
+        summary: "Get job details",
+        description: "Get detailed information about a specific job including file statuses",
+        security: [{ bearerAuth: [] }, { apiKey: [] }],
+        responses: {
+          200: {
+            description: "Job details",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        job: {
+                          type: "object",
+                          properties: {
+                            id: { type: "string", format: "uuid" },
+                            status: { type: "string" },
+                            dateCreated: { type: "string", format: "date-time" },
+                            numFiles: { type: "number" },
+                            files: {
+                              type: "array",
+                              items: {
+                                type: "object",
+                                properties: {
+                                  id: { type: "number" },
+                                  fileName: { type: "string" },
+                                  outputFileName: { type: "string" },
+                                  status: { type: "string" },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          401: {
+            $ref: "#/components/responses/Unauthorized",
+          },
+          404: {
+            $ref: "#/components/responses/NotFound",
+          },
+        },
+      },
+    }
+  )
+  .delete(
+    "/:id",
+    ({ params: { id }, set, ...ctx }: any) => {
+      const user = (ctx as any).user;
+      if (!user && !ALLOW_UNAUTHENTICATED) {
+        set.status = 401;
+        return {
+          success: false,
+          error: "Authentication required",
+          code: "AUTH_REQUIRED",
+        };
+      }
+
+      const userId = user?.id || 0;
+
+      const job = db
+        .query("SELECT id FROM jobs WHERE id = ? AND user_id = ?")
+        .get(id, userId);
+
+      if (!job) {
+        set.status = 404;
+        return {
+          success: false,
+          error: "Job not found",
+          code: "JOB_NOT_FOUND",
+        };
+      }
+
+      // Delete files from database
+      db.query("DELETE FROM file_names WHERE job_id = ?").run(id);
+      
+      // Delete job
+      db.query("DELETE FROM jobs WHERE id = ?").run(id);
+
+      // TODO: Delete actual files from disk
+
+      return {
+        success: true,
+        data: {
+          message: "Job deleted successfully",
+        },
+      };
+    },
+    {
+      params: t.Object({
+        id: t.String(),
+      }),
+      detail: {
+        tags: ["jobs"],
+        summary: "Delete a job",
+        description: "Delete a job and all associated files",
+        security: [{ bearerAuth: [] }, { apiKey: [] }],
+        responses: {
+          200: {
+            description: "Job deleted",
+            content: {
+              "application/json": {
+                schema: {
+                  type: "object",
+                  properties: {
+                    success: { type: "boolean", example: true },
+                    data: {
+                      type: "object",
+                      properties: {
+                        message: { type: "string" },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+          401: {
+            $ref: "#/components/responses/Unauthorized",
+          },
+          404: {
+            $ref: "#/components/responses/NotFound",
+          },
+        },
+      },
+    }
+  );
\ No newline at end of file
diff --git a/src/helpers/env.ts b/src/helpers/env.ts
index 6722c54..c656b47 100644
--- a/src/helpers/env.ts
+++ b/src/helpers/env.ts
@@ -19,4 +19,17 @@ export const LANGUAGE = process.env.LANGUAGE?.toLowerCase() || "en";
 export const MAX_CONVERT_PROCESS = process.env.MAX_CONVERT_PROCESS && Number(process.env.MAX_CONVERT_PROCESS) > 0 ? Number(process.env.MAX_CONVERT_PROCESS) : 0
 
 export const UNAUTHENTICATED_USER_SHARING =
-  process.env.UNAUTHENTICATED_USER_SHARING?.toLowerCase() === "true" || false;
\ No newline at end of file
+  process.env.UNAUTHENTICATED_USER_SHARING?.toLowerCase() === "true" || false;
+
+// API Configuration
+export const API_ENABLED = process.env.API_ENABLED?.toLowerCase() !== "false";
+
+export const API_PREFIX = process.env.API_PREFIX ?? "/api/v1";
+
+export const API_RATE_LIMIT = process.env.API_RATE_LIMIT
+  ? Number(process.env.API_RATE_LIMIT)
+  : 100;
+
+export const API_RATE_WINDOW = process.env.API_RATE_WINDOW ?? "15m";
+
+export const API_KEY_ENABLED = process.env.API_KEY_ENABLED?.toLowerCase() === "true" || false;
\ No newline at end of file
diff --git a/src/index.tsx b/src/index.tsx
index b95b4b8..2ade4ef 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -17,6 +17,7 @@ import { results } from "./pages/results";
 import { root } from "./pages/root";
 import { upload } from "./pages/upload";
 import { user } from "./pages/user";
+import { api } from "./api/v1";
 
 mkdir("./data", { recursive: true }).catch(console.error);
 
@@ -36,6 +37,7 @@ const app = new Elysia({
       prefix: "",
     }),
   )
+  .use(api)
   .use(user)
   .use(root)
   .use(upload)
@@ -61,7 +63,7 @@ if (process.env.NODE_ENV !== "production") {
   });
 }
 
-app.listen(3000);
+app.listen(3110);
 
 console.log(`🦊 Elysia is running at http://${app.server?.hostname}:${app.server?.port}${WEBROOT}`);
 
diff --git a/test-api.sh b/test-api.sh
new file mode 100755
index 0000000..a2e31d6
--- /dev/null
+++ b/test-api.sh
@@ -0,0 +1,133 @@
+#!/bin/bash
+
+# ConvertX API Test Script
+# This script tests the basic API functionality
+
+BASE_URL="http://localhost:3110/api/v1"
+EMAIL="test@example.com"
+PASSWORD="testpassword123"
+
+echo "🧪 ConvertX API Test Suite"
+echo "========================="
+echo ""
+
+# Function to pretty print JSON
+pretty_json() {
+    echo "$1" | jq '.' 2>/dev/null || echo "$1"
+}
+
+# 1. Test Health Endpoint
+echo "1️⃣ Testing Health Endpoint..."
+HEALTH=$(curl -s $BASE_URL/health)
+echo "Response:"
+pretty_json "$HEALTH"
+echo ""
+
+# 2. Test Swagger Documentation
+echo "2️⃣ Checking Swagger Documentation..."
+SWAGGER_STATUS=$(curl -s -o /dev/null -w "%{http_code}" $BASE_URL/swagger)
+if [ "$SWAGGER_STATUS" = "200" ]; then
+    echo "✅ Swagger documentation is available at $BASE_URL/swagger"
+else
+    echo "❌ Swagger documentation not accessible (HTTP $SWAGGER_STATUS)"
+fi
+echo ""
+
+# 3. Test Registration
+echo "3️⃣ Testing Registration..."
+REGISTER=$(curl -s -X POST $BASE_URL/auth/register \
+  -H "Content-Type: application/json" \
+  -d "{\"email\": \"$EMAIL\", \"password\": \"$PASSWORD\"}")
+echo "Response:"
+pretty_json "$REGISTER"
+
+# Extract token
+TOKEN=$(echo "$REGISTER" | jq -r '.data.token' 2>/dev/null)
+if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
+    echo "Registration might have failed. Trying login instead..."
+    
+    # Try login
+    LOGIN=$(curl -s -X POST $BASE_URL/auth/login \
+      -H "Content-Type: application/json" \
+      -d "{\"email\": \"$EMAIL\", \"password\": \"$PASSWORD\"}")
+    echo "Login Response:"
+    pretty_json "$LOGIN"
+    TOKEN=$(echo "$LOGIN" | jq -r '.data.token' 2>/dev/null)
+fi
+
+if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
+    echo "❌ Failed to get authentication token"
+    exit 1
+fi
+
+echo "✅ Got token: ${TOKEN:0:20}..."
+echo ""
+
+# 4. Test Current User
+echo "4️⃣ Testing Get Current User..."
+ME=$(curl -s $BASE_URL/auth/me \
+  -H "Authorization: Bearer $TOKEN")
+echo "Response:"
+pretty_json "$ME"
+echo ""
+
+# 5. Test List Converters
+echo "5️⃣ Testing List Converters..."
+CONVERTERS=$(curl -s $BASE_URL/converters \
+  -H "Authorization: Bearer $TOKEN")
+echo "Response (first 500 chars):"
+echo "$CONVERTERS" | jq '.' 2>/dev/null | head -c 500
+echo "..."
+echo ""
+
+# 6. Test Get Specific Converter
+echo "6️⃣ Testing Get Specific Converter (ffmpeg)..."
+FFMPEG=$(curl -s $BASE_URL/converters/ffmpeg \
+  -H "Authorization: Bearer $TOKEN")
+echo "Response (first 500 chars):"
+echo "$FFMPEG" | jq '.' 2>/dev/null | head -c 500
+echo "..."
+echo ""
+
+# 7. Test Format Support
+echo "7️⃣ Testing Format Support (PDF)..."
+PDF_CONVERTERS=$(curl -s $BASE_URL/converters/formats/pdf \
+  -H "Authorization: Bearer $TOKEN")
+echo "Response:"
+pretty_json "$PDF_CONVERTERS"
+echo ""
+
+# 8. Test List Jobs
+echo "8️⃣ Testing List Jobs..."
+JOBS=$(curl -s $BASE_URL/jobs \
+  -H "Authorization: Bearer $TOKEN")
+echo "Response:"
+pretty_json "$JOBS"
+echo ""
+
+# 9. Test Start Conversion (with dummy data)
+echo "9️⃣ Testing Start Conversion..."
+CONVERSION=$(curl -s -X POST $BASE_URL/conversions \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "files": [{"name": "test.pdf"}],
+    "converter": "libreoffice",
+    "outputFormat": "docx"
+  }')
+echo "Response:"
+pretty_json "$CONVERSION"
+echo ""
+
+# Summary
+echo "📊 Test Summary"
+echo "==============="
+echo "✅ Health Check"
+echo "✅ Authentication"
+echo "✅ Converter Endpoints"
+echo "✅ Job Management"
+echo ""
+echo "🎉 All basic API tests completed!"
+echo ""
+echo "📝 Note: File conversion endpoints require actual file uploads."
+echo "   Use the Swagger UI at $BASE_URL/swagger for interactive testing."
\ No newline at end of file