{
    "openapi": "3.0.3",
    "info": {
        "title": "HireSquire AI Agent API",
        "version": "2.0.0",
        "description": "Production-ready API for AI agents and automation platforms (n8n, Make, Zapier). Submit job descriptions with resumes and receive AI-powered candidate evaluations with scores, summaries, and interview questions.\n\n## Authentication\n\nAll endpoints require a Bearer token. Generate one from the HireSquire dashboard.\n\n```bash\nAuthorization: Bearer YOUR_API_TOKEN\n```\n\n## Key Features\n\n- **Hybrid Upload**: Submit resumes as raw text, base64, or file URLs\n- **Async Processing**: 202 Accepted with polling for results\n- **Webhooks**: Get notified when jobs complete or candidates are shortlisted\n- **Conditional Webhooks**: Filter events by score threshold, event type, or candidate rank\n- **Email Generation**: Generate interview invites, rejection emails, and icebreakers\n- **Schema Discovery**: Dynamic field mapping for no-code platforms\n\n## Rate Limits\n\n- 60 requests per minute per user\n- Higher limits available on Enterprise plans",
        "contact": {
            "name": "HireSquire Support",
            "url": "https://hiresquire.com/support"
        },
        "license": {
            "name": "Proprietary"
        }
    },
    "servers": [
        {
            "url": "https://hiresquireai.com/api/v1",
            "description": "Production server"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "API Token",
                "description": "Generate API tokens from your HireSquire dashboard. Include in Authorization header."
            }
        },
        "schemas": {
            "JobSubmission": {
                "type": "object",
                "required": [
                    "title",
                    "description",
                    "resumes"
                ],
                "properties": {
                    "title": {
                        "type": "string",
                        "maxLength": 255,
                        "description": "Job posting title",
                        "example": "Senior React Developer"
                    },
                    "description": {
                        "type": "string",
                        "minLength": 50,
                        "description": "Full job description with requirements",
                        "example": "We are looking for a Senior React Developer with 5+ years experience..."
                    },
                    "custom_instructions": {
                        "type": "string",
                        "maxLength": 5000,
                        "description": "Optional custom instructions for the AI evaluator",
                        "example": "Prioritize candidates with TypeScript experience"
                    },
                    "leniency_level": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 10,
                        "default": 5,
                        "description": "Screening strictness: 1=very lenient, 10=extremely strict"
                    },
                    "webhook_url": {
                        "type": "string",
                        "format": "uri",
                        "maxLength": 500,
                        "description": "Optional webhook URL for async notifications"
                    },
                    "webhook_conditions": {
                        "type": "object",
                        "description": "Filter which webhook events are sent",
                        "properties": {
                            "min_score": {
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 100,
                                "description": "Only trigger webhooks for candidates scoring above this threshold"
                            },
                            "only_top_n": {
                                "type": "integer",
                                "minimum": 1,
                                "maximum": 100,
                                "description": "Only trigger for top N ranked candidates"
                            },
                            "events": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "enum": [
                                        "job.completed",
                                        "job.processing",
                                        "job.failed",
                                        "high_score_detected",
                                        "candidate.shortlisted",
                                        "candidate.rejected"
                                    ]
                                },
                                "description": "Specific events to receive"
                            }
                        }
                    },
                    "resumes": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 100,
                        "description": "Array of resumes. Supports three input formats (content takes priority):",
                        "items": {
                            "type": "object",
                            "properties": {
                                "filename": {
                                    "type": "string",
                                    "maxLength": 255,
                                    "description": "Original filename",
                                    "example": "john-doe-resume.pdf"
                                },
                                "content": {
                                    "type": "string",
                                    "minLength": 50,
                                    "maxLength": 100000,
                                    "description": "Raw text content (highest priority)",
                                    "example": "John Doe\nSenior Developer\n5 years React experience..."
                                },
                                "base64": {
                                    "type": "string",
                                    "description": "Base64-encoded file content (PDF, DOCX, TXT)",
                                    "example": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoK..."
                                },
                                "file_url": {
                                    "type": "string",
                                    "format": "uri",
                                    "description": "Public URL to fetch resume from (for n8n/Make integrations)",
                                    "example": "https://example.com/resumes/john-doe.pdf"
                                }
                            },
                            "required": [
                                "filename"
                            ]
                        }
                    }
                }
            },
            "JobResponse": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "string",
                        "example": "Job accepted for processing"
                    },
                    "job_id": {
                        "type": "integer",
                        "example": 105
                    },
                    "status_url": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://hiresquireai.com/api/v1/jobs/105"
                    },
                    "results_url": {
                        "type": "string",
                        "format": "uri",
                        "nullable": true,
                        "example": "https://hiresquireai.com/api/v1/jobs/105/results"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "processing"
                        ],
                        "example": "processing"
                    },
                    "warnings": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "message": {
                                    "type": "string"
                                },
                                "failed_files": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            }
                        },
                        "nullable": true
                    }
                }
            },
            "JobStatus": {
                "type": "object",
                "properties": {
                    "job_id": {
                        "type": "integer"
                    },
                    "title": {
                        "type": "string"
                    },
                    "description": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "processing",
                            "completed",
                            "failed"
                        ]
                    },
                    "source": {
                        "type": "string"
                    },
                    "leniency_level": {
                        "type": "integer"
                    },
                    "custom_instructions": {
                        "type": "string"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "estimated_completion": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "candidate_count": {
                        "type": "integer"
                    },
                    "summary": {
                        "type": "object",
                        "properties": {
                            "total_candidates": {
                                "type": "integer"
                            },
                            "qualified_count": {
                                "type": "integer"
                            },
                            "top_score": {
                                "type": "number"
                            },
                            "average_score": {
                                "type": "number"
                            }
                        }
                    },
                    "results_url": {
                        "type": "string",
                        "format": "uri",
                        "nullable": true
                    },
                    "webhook_url": {
                        "type": "string",
                        "nullable": true
                    },
                    "webhook_status": {
                        "type": "string",
                        "nullable": true
                    }
                }
            },
            "JobListItem": {
                "type": "object",
                "properties": {
                    "job_id": {
                        "type": "integer"
                    },
                    "title": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string"
                    },
                    "source": {
                        "type": "string"
                    },
                    "candidate_count": {
                        "type": "integer"
                    },
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "status_url": {
                        "type": "string",
                        "format": "uri"
                    },
                    "results_url": {
                        "type": "string",
                        "format": "uri",
                        "nullable": true
                    }
                }
            },
            "InterviewQuestion": {
                "type": "object",
                "properties": {
                    "question": {
                        "type": "string"
                    },
                    "seeking": {
                        "type": "string",
                        "description": "What a good answer should demonstrate"
                    }
                }
            },
            "Candidate": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "score": {
                        "type": "integer",
                        "minimum": 0,
                        "maximum": 100
                    },
                    "summary": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "new",
                            "shortlisted",
                            "rejected",
                            "hired"
                        ]
                    },
                    "user_notes": {
                        "type": "string",
                        "nullable": true
                    },
                    "icebreaker": {
                        "type": "string",
                        "nullable": true
                    },
                    "contact_info": {
                        "type": "object",
                        "properties": {
                            "email": {
                                "type": "string",
                                "nullable": true
                            },
                            "phone": {
                                "type": "string",
                                "nullable": true
                            },
                            "linkedin_url": {
                                "type": "string",
                                "nullable": true
                            }
                        }
                    },
                    "generated_outreach": {
                        "type": "object",
                        "properties": {
                            "interview_questions": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/components/schemas/InterviewQuestion"
                                }
                            }
                        }
                    },
                    "processed_at": {
                        "type": "string",
                        "format": "date-time"
                    }
                }
            },
            "JobResults": {
                "type": "object",
                "properties": {
                    "job_id": {
                        "type": "integer"
                    },
                    "title": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string"
                    },
                    "total_candidates": {
                        "type": "integer"
                    },
                    "per_page": {
                        "type": "integer"
                    },
                    "current_page": {
                        "type": "integer"
                    },
                    "last_page": {
                        "type": "integer"
                    },
                    "candidates": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Candidate"
                        }
                    }
                }
            },
            "EmailGenerationRequest": {
                "type": "object",
                "required": [
                    "candidate_id",
                    "type"
                ],
                "properties": {
                    "candidate_id": {
                        "type": "integer",
                        "description": "ID of the candidate to generate email for"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "invite",
                            "rejection",
                            "keep-warm",
                            "icebreaker"
                        ],
                        "description": "Type of email to generate"
                    },
                    "tone": {
                        "type": "string",
                        "enum": [
                            "professional",
                            "friendly",
                            "casual"
                        ],
                        "default": "professional"
                    },
                    "custom_notes": {
                        "type": "string",
                        "maxLength": 1000,
                        "description": "Additional context for the email"
                    }
                }
            },
            "EmailGenerationResponse": {
                "type": "object",
                "properties": {
                    "candidate_id": {
                        "type": "integer"
                    },
                    "type": {
                        "type": "string"
                    },
                    "tone": {
                        "type": "string"
                    },
                    "generated_email": {
                        "type": "string"
                    },
                    "subject": {
                        "type": "string"
                    }
                }
            },
            "BulkEmailRequest": {
                "type": "object",
                "required": [
                    "type",
                    "candidate_ids"
                ],
                "properties": {
                    "type": {
                        "type": "string",
                        "enum": [
                            "invite",
                            "rejection",
                            "keep-warm"
                        ]
                    },
                    "candidate_ids": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        },
                        "description": "Array of candidate IDs (max 50)"
                    },
                    "tone": {
                        "type": "string",
                        "enum": [
                            "professional",
                            "friendly",
                            "casual"
                        ]
                    }
                }
            },
            "SchemaResponse": {
                "type": "object",
                "properties": {
                    "version": {
                        "type": "string"
                    },
                    "candidate_fields": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "job_fields": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "email_types": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "leniency_levels": {
                        "type": "array",
                        "items": {
                            "type": "integer"
                        }
                    },
                    "candidate_statuses": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "webhook_events": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "limits": {
                        "type": "object",
                        "properties": {
                            "max_resumes_per_job": {
                                "type": "integer"
                            },
                            "max_resume_size": {
                                "type": "integer"
                            },
                            "rate_limit_per_minute": {
                                "type": "integer"
                            }
                        }
                    },
                    "examples": {
                        "type": "object"
                    }
                }
            },
            "WhoAmIResponse": {
                "type": "object",
                "properties": {
                    "valid": {
                        "type": "boolean"
                    },
                    "user": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "name": {
                                "type": "string"
                            },
                            "email": {
                                "type": "string"
                            },
                            "credits": {
                                "type": "object",
                                "properties": {
                                    "balance": {
                                        "type": "number"
                                    },
                                    "formatted_balance": {
                                        "type": "string"
                                    },
                                    "is_low": {
                                        "type": "boolean"
                                    },
                                    "auto_reload_enabled": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    },
                    "agent_key": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "name": {
                                "type": "string"
                            },
                            "monthly_spend_limit": {
                                "type": "number"
                            },
                            "total_spent_this_month": {
                                "type": "number"
                            }
                        }
                    }
                }
            },
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    },
                    "errors": {
                        "type": "object",
                        "additionalProperties": true
                    }
                }
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/jobs": {
            "post": {
                "summary": "Submit job for screening",
                "description": "Submit a job description with resumes for AI analysis. Returns 202 Accepted with job_id for polling.",
                "operationId": "submitJob",
                "x-agent-guidance": "Use this endpoint to start the screening process. For large batches (>10 resumes), use a webhook_url instead of polling.",
                "x-agent-capability": "core-screening",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/JobSubmission"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Job accepted for processing",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/JobResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Screening limit exceeded"
                    },
                    "422": {
                        "description": "Validation error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            },
            "get": {
                "summary": "List user's jobs",
                "description": "Get all job postings for the authenticated user with optional filtering.",
                "operationId": "listJobs",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/StatusFilter"
                    },
                    {
                        "$ref": "#/components/parameters/SourceFilter"
                    },
                    {
                        "$ref": "#/components/parameters/SinceFilter"
                    },
                    {
                        "$ref": "#/components/parameters/LimitParam"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of jobs",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/JobListItem"
                                            }
                                        },
                                        "pagination": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/jobs/{jobId}": {
            "get": {
                "summary": "Get job status",
                "description": "Check the processing status of a job.",
                "operationId": "getJobStatus",
                "x-agent-guidance": "Poll this endpoint using exponential backoff (2s, 5s, 10s). Stop when status is 'completed' or 'failed'.",
                "x-agent-capability": "job-monitoring",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/JobIdParam"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Job status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/JobStatus"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Job not found"
                    }
                }
            }
        },
        "/jobs/{jobId}/results": {
            "get": {
                "summary": "Get candidate results",
                "description": "Retrieve evaluated candidates. Only available when job status is 'completed'.",
                "operationId": "getJobResults",
                "x-agent-guidance": "Only call this after status is 'completed'. Candidates are sorted by score descending.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/JobIdParam"
                    },
                    {
                        "$ref": "#/components/parameters/PageParam"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Candidate results",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/JobResults"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Job not found"
                    },
                    "425": {
                        "description": "Results not yet available (job still processing)"
                    }
                }
            }
        },
        "/jobs/{jobId}/generate-email": {
            "post": {
                "summary": "Generate email for candidate",
                "description": "Generate an interview invitation, rejection, or follow-up email for a specific candidate.",
                "operationId": "generateEmail",
                "x-agent-guidance": "Use this to create personalized outreach. Provide a candidate_id from a completed job results. Types include 'invite', 'rejection', or 'icebreaker'.",
                "x-agent-capability": "outreach-generation",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/JobIdParam"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/EmailGenerationRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Generated email",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/EmailGenerationResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation error"
                    }
                }
            }
        },
        "/jobs/{jobId}/bulk-generate-emails": {
            "post": {
                "summary": "Bulk generate emails",
                "description": "Generate emails for multiple candidates at once (max 50).",
                "operationId": "bulkGenerateEmails",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/JobIdParam"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/BulkEmailRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Bulk email results",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "results": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/EmailGenerationResponse"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/candidates": {
            "get": {
                "summary": "List candidates",
                "description": "Search and filter all candidates across jobs.",
                "operationId": "listCandidates",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/JobIdFilter"
                    },
                    {
                        "$ref": "#/components/parameters/MinScoreFilter"
                    },
                    {
                        "$ref": "#/components/parameters/MaxScoreFilter"
                    },
                    {
                        "$ref": "#/components/parameters/SearchFilter"
                    },
                    {
                        "$ref": "#/components/parameters/StatusFilter"
                    },
                    {
                        "$ref": "#/components/parameters/SortBy"
                    },
                    {
                        "$ref": "#/components/parameters/SortDir"
                    },
                    {
                        "$ref": "#/components/parameters/LimitParam"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of candidates",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Candidate"
                                            }
                                        },
                                        "pagination": {
                                            "type": "object"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/candidates/{candidateId}": {
            "get": {
                "summary": "Get candidate details",
                "operationId": "getCandidate",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CandidateIdParam"
                    }
                ],
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Candidate"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Candidate not found"
                    }
                }
            }
        },
        "/candidates/{candidateId}/status": {
            "patch": {
                "summary": "Update candidate status",
                "description": "Update candidate pipeline status. Triggers webhook events for shortlisted/rejected.",
                "operationId": "updateCandidateStatus",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CandidateIdParam"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "status"
                                ],
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "new",
                                            "shortlisted",
                                            "rejected",
                                            "hired"
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Status updated",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "candidate_id": {
                                            "type": "integer"
                                        },
                                        "previous_status": {
                                            "type": "string"
                                        },
                                        "current_status": {
                                            "type": "string"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/candidates/{candidateId}/notes": {
            "patch": {
                "summary": "Update candidate notes",
                "operationId": "updateCandidateNotes",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/CandidateIdParam"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "notes"
                                ],
                                "properties": {
                                    "notes": {
                                        "type": "string",
                                        "maxLength": 10000
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Notes updated"
                    }
                }
            }
        },
        "/schema": {
            "get": {
                "summary": "Get API schema",
                "description": "Dynamic schema for no-code platform field mapping (n8n, Make, Zapier).",
                "operationId": "getSchema",
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SchemaResponse"
                                }
                            }
}
                     }
                 }
             }
         },
        "/schema/validate": {
            "get": {
                "summary": "Validate API token",
                "description": "Verify token validity and get account info (balance, limits).",
                "operationId": "validateToken",
                "x-agent-guidance": "Always call this first to verify your token and get current spend limits. This endpoint does not cost any credits.",
                "x-agent-capability": "health-check",
                "responses": {
                    "200": {
                        "description": "Token is valid",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WhoAmIResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/schema/health": {
            "get": {
                "summary": "Check system health",
                "description": "Get real-time system status and operational metrics.",
                "operationId": "getHealth",
                "responses": {
                    "200": {
                        "description": "System health status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {"type": "string"},
                                        "version": {"type": "string"},
                                        "environment": {"type": "string"},
                                        "timestamp": {"type": "string"},
                                        "api_latency": {"type": "string"},
                                        "queue_status": {"type": "string"},
                                        "services": {"type": "object"},
                                        "agent_readiness": {"type": "boolean"}
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/credits/balance": {
            "get": {
                "summary": "Get credit balance",
                "description": "Get current credit balance and account settings.",
                "operationId": "getCreditBalance",
                "x-agent-guidance": "Check this before starting a job to ensure you have enough credits. Use auto_reload_enabled to avoid interruptions.",
                "x-agent-capability": "credit-monitoring",
                "responses": {
                    "200": {
                        "description": "Credit balance",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "balance": {"type": "integer"},
                                        "formatted_balance": {"type": "string"},
                                        "total_purchased": {"type": "number"},
                                        "total_spent": {"type": "number"},
                                        "free_credits_available": {"type": "integer"},
                                        "monthly_free_credits": {"type": "integer"},
                                        "cost_per_candidate": {"type": "number"},
                                        "auto_reload_enabled": {"type": "boolean"}
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/credits/estimate-cost": {
            "get": {
                "summary": "Estimate screening cost",
                "description": "Estimate credits and cost for screening candidates (max 100 candidates).",
                "operationId": "estimateScreeningCost",
                "x-agent-guidance": "Calculate exactly how many credits you need before submitting a job. Compare this against your balance from /credits/balance.",
                "x-agent-capability": "cost-prediction",
                "parameters": [
                    {
                        "name": "candidate_count",
                        "in": "query",
                        "required": true,
                        "schema": {"type": "integer", "minimum": 1, "maximum": 100}
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Cost estimate",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "candidate_count": {"type": "integer"},
                                        "estimated_credits": {"type": "integer"},
                                        "estimated_cost": {"type": "number"},
                                        "current_balance": {"type": "integer"},
                                        "can_proceed": {"type": "boolean"},
                                        "shortage": {"type": "integer"},
                                        "cost_per_candidate": {"type": "number"},
                                        "currency": {"type": "string"}
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/credits/estimate": {
            "get": {
                "summary": "Estimate cost per candidate",
                "description": "Get cost per candidate for credit purchases (supports up to 1000 candidates).",
                "operationId": "estimateCost",
                "x-agent-guidance": "Get the bulk cost per candidate. Useful for high-volume screening projections.",
                "x-agent-capability": "cost-prediction",
                "parameters": [
                    {
                        "name": "candidate_count",
                        "in": "query",
                        "required": true,
                        "schema": {"type": "integer", "minimum": 1, "maximum": 1000}
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Cost estimate",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "candidate_count": {"type": "integer"},
                                        "cost_per_candidate": {"type": "number"},
                                        "total_cost": {"type": "number"},
                                        "currency": {"type": "string"}
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/credits/packs": {
            "get": {
                "summary": "List credit packs",
                "description": "List available credit packs for purchase with pricing and bonus credits.",
                "operationId": "listCreditPacks",
                "x-agent-guidance": "Retrieve available pricing tiers. Use this to suggest the best value pack to your human user if credits are low.",
                "x-agent-capability": "pricing-discovery",
                "responses": {
                    "200": {
                        "description": "Available credit packs",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "packs": {
                                            "type": "object",
                                            "additionalProperties": {
                                                "type": "object",
                                                "properties": {
                                                    "name": {"type": "string"},
                                                    "price": {"type": "number"},
                                                    "credits": {"type": "integer"},
                                                    "bonus": {"type": "integer"},
                                                    "per_credit": {"type": "number"}
                                                }
                                            }
                                        },
                                        "default_price_per_credit": {"type": "number"}
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/credits/transactions": {
            "get": {
                "summary": "Get credit transactions",
                "description": "Get credit transaction history with pagination.",
                "operationId": "getCreditTransactions",
                "parameters": [
                    {"$ref": "#/components/parameters/LimitParam"},
                    {"name": "offset", "in": "query", "schema": {"type": "integer", "default": 0}}
                ],
                "responses": {
                    "200": {
                        "description": "Transaction history",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "transactions": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": {"type": "integer"},
                                                    "type": {"type": "string"},
                                                    "amount": {"type": "integer"},
                                                    "balance_after": {"type": "integer"},
                                                    "description": {"type": "string"},
                                                    "created_at": {"type": "string", "format": "date-time"}
                                                }
                                            }
                                        },
                                        "balance": {"type": "integer"}
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "parameters": {
            "JobIdParam": {
                "name": "jobId",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "integer"
                }
            },
            "CandidateIdParam": {
                "name": "candidateId",
                "in": "path",
                "required": true,
                "schema": {
                    "type": "integer"
                }
            },
            "PageParam": {
                "name": "page",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "default": 1
                }
            },
            "LimitParam": {
                "name": "limit",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 20
                }
            },
            "StatusFilter": {
                "name": "status",
                "in": "query",
                "schema": {
                    "type": "string",
                    "enum": [
                        "processing",
                        "completed",
                        "failed"
                    ]
                }
            },
            "SourceFilter": {
                "name": "source",
                "in": "query",
                "schema": {
                    "type": "string"
                }
            },
            "SinceFilter": {
                "name": "since",
                "in": "query",
                "schema": {
                    "type": "string",
                    "format": "date"
                }
            },
            "JobIdFilter": {
                "name": "job_id",
                "in": "query",
                "schema": {
                    "type": "integer"
                }
            },
            "MinScoreFilter": {
                "name": "min_score",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100
                }
            },
            "MaxScoreFilter": {
                "name": "max_score",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 100
                }
            },
            "SearchFilter": {
                "name": "search",
                "in": "query",
                "schema": {
                    "type": "string"
                }
            },
            "SortBy": {
                "name": "sort_by",
                "in": "query",
                "schema": {
                    "type": "string",
                    "enum": [
                        "score",
                        "name",
                        "created_at"
                    ],
                    "default": "score"
                }
            },
            "SortDir": {
                "name": "sort_dir",
                "in": "query",
                "schema": {
                    "type": "string",
                    "enum": [
                        "asc",
                        "desc"
                    ],
                    "default": "desc"
                }
            }
        }
    },
    "tags": [
        {
            "name": "Jobs",
            "description": "Job submission and status"
        },
        {
            "name": "Candidates",
            "description": "Candidate management"
        },
        {
            "name": "Email",
            "description": "Email generation"
        },
        {
            "name": "Schema",
            "description": "API schema discovery"
        },
        {
            "name": "Credits",
            "description": "Credit management and purchases"
        }
    ]
}