> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tidyhire.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Interview Questions

<Info>
  This endpoint is **AI-powered**. It uses a large language model to generate tailored interview questions based on the job details, skills, and requirements provided.
</Info>


## OpenAPI

````yaml POST /api/public/v1/ai/generate-questions
openapi: 3.1.0
info:
  title: Tidyhire API
  description: Tidyhire Public API for ATS integrations
  version: 1.0.0
servers:
  - url: https://api.tidyhire.app
    description: Production
security:
  - apiKey: []
paths:
  /api/public/v1/ai/generate-questions:
    post:
      tags:
        - AI
      summary: Generate Interview Questions
      operationId: generateInterviewQuestions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateQuestionsRequest'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateQuestionsSuccessResponse'
        '400':
          description: Validation Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'
      security:
        - apiKey: []
components:
  schemas:
    GenerateQuestionsRequest:
      type: object
      required:
        - job_title
        - company_name
        - job_description
        - min_experience
        - max_experience
        - seniority_level
        - work_type
        - employment_type
        - skills_required
      properties:
        job_title:
          type: string
        company_name:
          type: string
        job_description:
          type: string
        min_experience:
          type: number
          description: Minimum years of experience required.
          example: 3
        max_experience:
          type: number
          description: Maximum years of experience required.
          example: 5
        seniority_level:
          type: string
          enum:
            - Entry
            - Mid
            - Senior
            - Lead
            - Principal
            - Staff
        work_type:
          type: string
          enum:
            - Remote
            - On Site
            - Hybrid
        employment_type:
          type: string
          enum:
            - Full Time
            - Part Time
            - Contract
            - Freelance
        location:
          type: string
        skills_required:
          type: array
          items:
            type: string
        skills_good_to_have:
          type: array
          items:
            type: string
        interview_duration:
          type: string
          enum:
            - 15 Minutes
            - 30 Minutes
            - 1 hour
            - 2 hours
    GenerateQuestionsSuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Question'
    ValidationErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          example: VALIDATION_ERROR
        message:
          type: string
          example: Request validation failed
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                example: candidates.0.name
              message:
                type: string
                example: Candidate name must be at least 3 characters
    UnauthorizedResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Unauthorized
        error:
          type: string
          example: INVALID_API_KEY
    InternalErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          example: UNKNOWN_ERROR
        message:
          type: string
          example: Something went wrong.
    Question:
      oneOf:
        - $ref: '#/components/schemas/VerbalQuestion'
        - $ref: '#/components/schemas/TaskQuestion'
      discriminator:
        propertyName: type
        mapping:
          verbal:
            $ref: '#/components/schemas/VerbalQuestion'
          task:
            $ref: '#/components/schemas/TaskQuestion'
    VerbalQuestion:
      type: object
      required:
        - id
        - question
        - type
      properties:
        id:
          type: string
          minLength: 1
          description: Unique question identifier.
          example: a1b2c3d4e5f60123456789abcdef0123
        question:
          type: string
          minLength: 1
          description: The interview question text.
          example: >-
            Tell me about a production application you led. What architecture
            choices did you make?
        type:
          type: string
          enum:
            - verbal
          description: Question type.
          example: verbal
    TaskQuestion:
      type: object
      required:
        - id
        - question
        - task
        - type
      properties:
        id:
          type: string
          minLength: 1
          description: Unique question identifier.
          example: 07f8e9d1c2b3456789abcdef0123456789ab
        question:
          type: string
          minLength: 1
          description: The interview question text.
          example: >-
            Implement an Angular component and service to display a paginated,
            sortable analytics table.
        task:
          $ref: '#/components/schemas/QuestionTask'
        type:
          type: string
          enum:
            - task
          description: Question type.
          example: task
    QuestionTask:
      type: object
      required:
        - problem_statement
        - type
      properties:
        language:
          type: string
          description: >-
            Programming language for the task. Required for `code` tasks;
            optional for `general` tasks (use "N/A" if not applicable).
          example: TypeScript
        problem_statement:
          type: string
          minLength: 1
          description: Detailed problem statement for the candidate to solve.
          example: >-
            Create an Angular service that calls a REST endpoint
            /api/patients/search...
        starter_code:
          type: string
          description: >-
            Starter code template provided to the candidate. Required for `code`
            tasks; optional for `general` tasks.
          example: |-
            import { Injectable } from '@angular/core';
            ...
        type:
          type: string
          enum:
            - code
            - general
          description: Task type — `code` for coding tasks, `general` for non-coding tasks.
          example: code
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-tidyhire-api-key
      description: Your Tidyhire API key

````