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

# Create interview

> Create a Tracy interview for a specific candidate.



## OpenAPI

````yaml POST /interviews
openapi: 3.1.0
info:
  title: Tracy Interview API
  description: >-
    Programmatically schedule AI-powered candidate interviews. Authenticate with
    an API key, list the jobs you can hire for, and create an interview by
    supplying the candidate's contact details, a CV link, and the job id.
  version: 1.0.0
  contact:
    name: Interview API support
    url: https://interview.gomu.ai
servers:
  - url: https://interview.qode.world/api/v1
    description: Production
  - url: https://interview.gomu.ai/api/v1
    description: Staging
security:
  - ApiKeyAuth: []
tags:
  - name: Interviews
    description: >-
      Create AI interviews for your candidates and list the jobs you can hire
      for.
  - name: Coding Interviews
    description: >-
      List the coding task bank and create or adjust coding interviews — either
      by picking explicit task ids or generating them randomly by topic,
      difficulty, and programming language.
  - name: System
    description: Service health.
paths:
  /interviews:
    post:
      tags:
        - Interviews
      summary: Create an interview
      description: >-
        Schedules an AI interview for a candidate against one of your jobs.
        Supply the candidate's email, name, a link to their CV, and the
        `qodeJobId` of the job they're applying for (obtain it from `GET
        /jobs`).


        The response returns a candidate-facing `interview_link` you can send by
        email or otherwise share with the candidate. The interview's questions,
        language, and other configuration are taken from the job's interview
        template — you don't need to provide them.


        If the supplied CV link can't be downloaded or parsed, the interview is
        still created and the candidate is identified by email alone.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInterviewRequest'
            example:
              candidate_email: thanh.le+dev@qode.world
              candidate_name: Le Phuoc Thanh
              cv_link: >-
                https://cdn.qode.gg/ptp-ms-file-store/production/cv_container/resume-4a9c9c320351d1a14a0b8479551c3ac939c6b6d9.pdf.pdf
              qodeJobId: 478e8e8b-87c9-4c2a-926f-ebce52442d39
      responses:
        '200':
          description: >-
            Interview created. PTP has scheduled the interview and a
            candidate-facing link is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInterviewResponse'
              example:
                success: true
                data:
                  interview_link: https://qode.world/interview/abc123
                  name: Tracy interview | Le Phuoc Thanh - Software Engineer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ValidationError'
        '404':
          description: >-
            The supplied `qodeJobId` does not exist or has no interview template
            configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                status: 404
                errors: >-
                  No interview template found for
                  qodeJobId=478e8e8b-87c9-4c2a-926f-ebce52442d39
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateInterviewRequest:
      type: object
      required:
        - candidate_email
        - candidate_name
        - cv_link
        - qodeJobId
      properties:
        candidate_email:
          type: string
          format: email
          description: Candidate's email. Used as the interview attendee.
        candidate_name:
          type: string
          minLength: 1
          description: Candidate's full name. Used to build the interview title.
        cv_link:
          type: string
          format: uri
          description: >-
            Public URL to the candidate's CV (PDF or DOCX). Plain HTTPS links
            and Google Drive sharing links are both supported.
        qodeJobId:
          type: string
          minLength: 1
          description: >-
            Job identifier returned by `GET /jobs`. Determines which interview
            template (questions, language, intro/outro) is used.
    CreateInterviewResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            interview_link:
              type: string
              format: uri
              description: Candidate-facing interview URL. Share this with the candidate.
            name:
              type: string
              description: >-
                Auto-generated interview title in the form `Tracy interview |
                <candidate_name> - <job_name>`.
    Error:
      type: object
      properties:
        status:
          type: integer
          example: 401
        errors:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
          description: Either a human-readable string or a list of Zod validation issues.
  responses:
    Unauthorized:
      description: API key missing, malformed, expired, or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 401
            errors: Invalid API key
    ValidationError:
      description: >-
        Request body failed Zod validation. The `errors` field contains the
        issue list.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Unexpected server-side failure. Safe to retry with exponential backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: Opaque token (starts with `qint_`)
      description: >-
        Provide the API key issued to you by your organization admin. Send it as
        `Authorization: Bearer <api-key>` on every request.

````