job-forge/docs/api_specification.md

Job Forge - FastAPI Web Application API Specification

Version: 1.0.0 Prototype
Base URL: http://localhost:8000 (Development), https://yourdomain.com (Production)
Target Audience: Full-Stack Developers and API Consumers
Last Updated: August 2025

---

🔐 Authentication

Overview

• Method: JWT Bearer tokens
• Token Expiry: 24 hours (configurable)
• Refresh: Token refresh endpoint available
• Header Format: Authorization: Bearer <jwt_token>
• Security: HTTPS required in production

Authentication Endpoints

POST /api/v1/auth/register

Register new user account.

Request:

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "first_name": "John",
  "last_name": "Doe"
}

Response (201):

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "is_active": true,
    "created_at": "2025-08-02T10:00:00Z"
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400
}

Errors:

• 400 - Invalid email format or weak password
• 409 - Email already registered

POST /api/v1/auth/login

Authenticate user and return JWT token.

Request:

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

Response (200):

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "is_active": true,
    "created_at": "2025-08-02T10:00:00Z"
  },
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 86400
}

Errors:

• 401 - Invalid credentials
• 400 - Missing email or password

GET /api/v1/auth/me

Get current user profile (requires authentication).

Headers: Authorization: Bearer <token>

Response (200):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "is_active": true,
  "created_at": "2025-08-02T10:00:00Z",
  "updated_at": "2025-08-02T10:00:00Z"
}

Errors:

• 401 - Invalid or expired token

POST /api/v1/auth/refresh

Refresh JWT access token.

Headers: Authorization: Bearer <token>

Response (200):

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

Errors:

• 401 - Invalid or expired token

---

📋 Applications API

Application Model

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "google_senior_developer_2025_07_01",
  "company_name": "Google",
  "role_title": "Senior Developer", 
  "job_url": "https://careers.google.com/jobs/123",
  "job_description": "We are looking for...",
  "location": "Toronto, ON",
  "priority_level": "high",
  "status": "draft",
  "research_completed": false,
  "resume_optimized": false,
  "cover_letter_generated": false,
  "created_at": "2025-07-01T10:00:00Z",
  "updated_at": "2025-07-01T10:00:00Z"
}

Application Endpoints

POST /api/v1/applications

Create new job application.

Headers: Authorization: Bearer <token>

Request:

{
  "company_name": "Google",
  "role_title": "Senior Developer",
  "job_description": "We are looking for an experienced developer...",
  "job_url": "https://careers.google.com/jobs/123",
  "location": "Toronto, ON",
  "priority_level": "high",
  "additional_context": "Found through LinkedIn, know someone there"
}

Response (201):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "google_senior_developer_2025_07_01",
  "company_name": "Google",
  "role_title": "Senior Developer",
  "job_url": "https://careers.google.com/jobs/123", 
  "job_description": "We are looking for an experienced developer...",
  "location": "Toronto, ON",
  "priority_level": "high",
  "status": "draft",
  "research_completed": false,
  "resume_optimized": false,
  "cover_letter_generated": false,
  "created_at": "2025-07-01T10:00:00Z",
  "updated_at": "2025-07-01T10:00:00Z"
}

Validation Rules:

• company_name: Required, 1-255 characters
• role_title: Required, 1-255 characters
• job_description: Required, minimum 50 characters
• job_url: Optional, valid URL format
• priority_level: Optional, enum: low|medium|high

Errors:

• 400 - Validation errors
• 401 - Unauthorized

GET /api/v1/applications

List user's applications.

Headers: Authorization: Bearer <token>

Query Parameters:

• status: Filter by status (optional)
• priority: Filter by priority level (optional)
• limit: Number of results (default: 50, max: 100)
• offset: Pagination offset (default: 0)

Response (200):

{
  "applications": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "google_senior_developer_2025_07_01",
      "company_name": "Google",
      "role_title": "Senior Developer",
      "status": "research_complete",
      "priority_level": "high",
      "research_completed": true,
      "resume_optimized": false,
      "cover_letter_generated": false,
      "created_at": "2025-07-01T10:00:00Z",
      "updated_at": "2025-07-01T11:30:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

GET /api/v1/applications/{application_id}

Get specific application details.

Headers: Authorization: Bearer <token>

Response (200): Full application object (see Application Model above)

Errors:

• 404 - Application not found or not owned by user
• 401 - Unauthorized

PUT /api/v1/applications/{application_id}

Update application details.

Headers: Authorization: Bearer <token>

Request:

{
  "company_name": "Google Inc.",
  "location": "Toronto, ON, Canada",
  "priority_level": "medium"
}

Response (200): Updated application object

Errors:

• 404 - Application not found
• 400 - Validation errors
• 401 - Unauthorized

DELETE /api/v1/applications/{application_id}

Delete application and all associated documents.

Headers: Authorization: Bearer <token>

Response (204): No content

Errors:

• 404 - Application not found
• 401 - Unauthorized

---

📄 Documents API

Document Model

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "application_id": "456e7890-e89b-12d3-a456-426614174000", 
  "document_type": "research_report",
  "content": "# Research Report\n\n## Job Analysis\n...",
  "created_at": "2025-07-01T10:30:00Z",
  "updated_at": "2025-07-01T10:30:00Z"
}

Document Endpoints

GET /api/v1/applications/{application_id}/documents

Get all documents for an application.

Headers: Authorization: Bearer <token>

Response (200):

{
  "research_report": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "content": "# Research Report\n\n## Job Analysis\n...",
    "created_at": "2025-07-01T10:30:00Z",
    "updated_at": "2025-07-01T10:30:00Z"
  },
  "optimized_resume": {
    "id": "234e5678-e89b-12d3-a456-426614174000",
    "content": "# John Doe\n\n## Experience\n...",
    "created_at": "2025-07-01T11:00:00Z",
    "updated_at": "2025-07-01T11:00:00Z"
  },
  "cover_letter": null
}

GET /api/v1/applications/{application_id}/documents/{document_type}

Get specific document.

Headers: Authorization: Bearer <token>

URL Parameters:

• document_type: enum: research_report|optimized_resume|cover_letter

Response (200):

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "application_id": "456e7890-e89b-12d3-a456-426614174000",
  "document_type": "research_report", 
  "content": "# Research Report\n\n## Job Analysis\n...",
  "created_at": "2025-07-01T10:30:00Z",
  "updated_at": "2025-07-01T10:30:00Z"
}

Errors:

• 404 - Document not found or application not owned by user

PUT /api/v1/applications/{application_id}/documents/{document_type}

Update document content (user editing).

Headers: Authorization: Bearer <token>

Request:

{
  "content": "# Updated Research Report\n\n## Job Analysis\nUpdated content..."
}

Response (200): Updated document object

Validation:

• content: Required, minimum 10 characters

Errors:

• 404 - Document or application not found
• 400 - Validation errors

---

🤖 AI Processing API

Processing Status Model

{
  "application_id": "123e4567-e89b-12d3-a456-426614174000",
  "current_phase": "research",
  "status": "processing",
  "progress": 0.6,
  "estimated_completion": "2025-07-01T10:35:00Z",
  "error_message": null
}

Processing Endpoints

POST /api/v1/processing/applications/{application_id}/research

Start research phase processing.

Headers: Authorization: Bearer <token>

Response (202):

{
  "message": "Research phase started",
  "application_id": "123e4567-e89b-12d3-a456-426614174000",
  "estimated_completion": "2025-07-01T10:35:00Z"
}

Errors:

• 404 - Application not found
• 409 - Research already completed
• 400 - Application not in correct state

POST /api/v1/processing/applications/{application_id}/resume

Start resume optimization phase.

Headers: Authorization: Bearer <token>

Requirements: Research phase must be completed

Response (202):

{
  "message": "Resume optimization started", 
  "application_id": "123e4567-e89b-12d3-a456-426614174000",
  "estimated_completion": "2025-07-01T11:05:00Z"
}

Errors:

• 404 - Application not found
• 409 - Resume already optimized
• 412 - Research phase not completed

POST /api/v1/processing/applications/{application_id}/cover-letter

Start cover letter generation phase.

Headers: Authorization: Bearer <token>

Request:

{
  "additional_context": "I'm particularly interested in their AI/ML projects. I have experience with TensorFlow and PyTorch."
}

Requirements: Resume optimization must be completed

Response (202):

{
  "message": "Cover letter generation started",
  "application_id": "123e4567-e89b-12d3-a456-426614174000", 
  "estimated_completion": "2025-07-01T11:15:00Z"
}

Errors:

• 404 - Application not found
• 409 - Cover letter already generated
• 412 - Resume optimization not completed

GET /api/v1/processing/applications/{application_id}/status

Get current processing status.

Headers: Authorization: Bearer <token>

Response (200):

{
  "application_id": "123e4567-e89b-12d3-a456-426614174000",
  "current_phase": "resume",
  "status": "completed",
  "progress": 1.0,
  "completed_at": "2025-07-01T11:05:00Z",
  "error_message": null
}

Status Values:

• idle - No processing active
• processing - AI generation in progress
• completed - Phase completed successfully
• failed - Processing failed with error

---

👤 User Resumes API

Resume Model

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Technical Resume",
  "content": "# John Doe\n\n## Technical Skills\n...",
  "focus_area": "software_development",
  "is_primary": true,
  "created_at": "2025-07-01T09:00:00Z",
  "updated_at": "2025-07-01T09:00:00Z"
}

Resume Endpoints

GET /api/v1/resumes

Get user's resume library.

Headers: Authorization: Bearer <token>

Response (200):

{
  "resumes": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Technical Resume",
      "focus_area": "software_development", 
      "is_primary": true,
      "created_at": "2025-07-01T09:00:00Z",
      "updated_at": "2025-07-01T09:00:00Z"
    }
  ]
}

POST /api/v1/resumes

Upload new resume to library.

Headers: Authorization: Bearer <token>

Request:

{
  "name": "Management Resume",
  "content": "# John Doe\n\n## Leadership Experience\n...",
  "focus_area": "management",
  "is_primary": false
}

Response (201): Created resume object

Validation:

• name: Required, 1-255 characters
• content: Required, minimum 100 characters
• focus_area: Optional, enum: software_development|management|data_science|consulting|other

GET /api/v1/resumes/{resume_id}

Get specific resume details.

Headers: Authorization: Bearer <token>

Response (200): Full resume object

PUT /api/v1/resumes/{resume_id}

Update resume content.

Headers: Authorization: Bearer <token>

Request: Same as POST

Response (200): Updated resume object

DELETE /api/v1/resumes/{resume_id}

Delete resume from library.

Headers: Authorization: Bearer <token>

Response (204): No content

Errors:

• 409 - Cannot delete primary resume if it's the only one

---

🚨 Error Handling

Standard Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "company_name": ["This field is required"],
      "job_description": ["Must be at least 50 characters"]
    }
  },
  "timestamp": "2025-07-01T10:00:00Z",
  "path": "/api/v1/applications"
}

HTTP Status Codes

• 200 - Success
• 201 - Created successfully
• 202 - Accepted (async processing started)
• 204 - No content (successful deletion)
• 400 - Bad request (validation errors)
• 401 - Unauthorized (invalid/missing token)
• 403 - Forbidden (valid token, insufficient permissions)
• 404 - Not found
• 409 - Conflict (duplicate email, invalid state transition)
• 412 - Precondition failed (phase not completed)
• 422 - Unprocessable entity (semantic errors)
• 500 - Internal server error

Error Codes

• VALIDATION_ERROR - Input validation failed
• AUTHENTICATION_ERROR - Invalid credentials
• AUTHORIZATION_ERROR - Insufficient permissions
• NOT_FOUND - Resource not found
• DUPLICATE_RESOURCE - Resource already exists
• INVALID_STATE - Operation not valid for current state
• EXTERNAL_API_ERROR - Claude/OpenAI API error
• PROCESSING_ERROR - AI processing failed

---

🔧 Development Notes

Environment Configuration

• Development: http://localhost:8000
• Production: HTTPS required with proper SSL certificates
• Environment variables for API keys and database connections

Rate Limiting

• Implemented for AI endpoints to prevent abuse
• Authentication endpoints have basic rate limiting
• Configurable limits based on deployment environment

Pagination

• Default limit: 50
• Maximum limit: 100
• Use offset for pagination
• Consider cursor-based pagination for future versions

Content Validation

• Job description: 50-10000 characters
• Resume content: 100-50000 characters
• Names: 1-255 characters
• URLs: Valid HTTP/HTTPS format
• Email: RFC 5322 compliant

Background Processing

• AI operations run asynchronously via background tasks
• Use /processing/applications/{id}/status to check progress
• Frontend should poll every 2-3 seconds during processing
• Proper error handling and retry mechanisms implemented

Security Considerations

• JWT tokens signed with secure secret keys
• Row Level Security (RLS) enforced at database level
• Input validation and sanitization on all endpoints
• CORS properly configured for web application

Monitoring and Logging

• Structured logging with request IDs
• Performance monitoring for AI service calls
• Error tracking and alerting configured

---

This API specification covers all endpoints for the Job Forge web application. Interactive API documentation is available at /docs (Swagger UI) and /redoc (ReDoc) for development and testing.