HeyMilo Interviewers API

openapi: 3.2.0
info:
  title: HeyMilo Public ATS Interviewers API
  description: External developer-facing API for HeyMilo. Create interviewers with agentic workflows, ingest candidates, retrieve interview results, and manage workspace resources.
  version: 2.0.0
servers:
- url: https://api.heymilo.ai
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Interviewers
  description: Create, read, update, and manage interviewers. An interviewer (posting) combines job details with an AI agent configuration and agentic workflow.
paths:
  /api/v2/postings:
    post:
      tags:
      - Interviewers
      summary: Create an interviewer
      description: 'Create a fully-configured interviewer with an agentic workflow. Returns the new posting ID, URLs, and a full posting receipt.


        **ATS-derived templates use a two-step flow.** When `interview_template_id` references a template whose blueprint is ATS-derived, the new posting is returned in an intermediate stage (`status: "draft"`, `ats_metadata.pending_activation: true`) and does **not** begin ingesting candidates. Transition it to live by calling `POST /postings/{posting_id}/activate`, which finalizes the posting and attaches the ATS mapping in one step. Non-ATS create paths are unchanged.'
      operationId: createPosting
      parameters:
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostingRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponse_CreatePostingResponse_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Interviewers
      summary: List interviewers
      description: Retrieve a paginated list of interviewers for the authenticated workspace.
      operationId: listPostings
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Case-insensitive substring filter on the posting title.
          title: Search
        description: Case-insensitive substring filter on the posting title.
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_PostingResponse_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/postings/list:
    get:
      tags:
      - Interviewers
      summary: List interviewer summaries
      description: Retrieve a lightweight paginated list of interviewers (id, title, name only) for the authenticated workspace.
      operationId: listPostingSummaries
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Case-insensitive substring filter on the posting title.
          title: Search
        description: Case-insensitive substring filter on the posting title.
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_PostingSummary_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/postings/{posting_id}:
    get:
      tags:
      - Interviewers
      summary: Get an interviewer
      description: Retrieve the full details of a specific interviewer by ID.
      operationId: getPosting
      parameters:
      - name: posting_id
        in: path
        required: true
        schema:
          type: string
          title: Posting Id
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponse_PostingResponse_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Interviewers
      summary: Update an interviewer
      description: Update fields on an existing interviewer. Only provided fields are modified; omitted fields remain unchanged.
      operationId: updatePosting
      parameters:
      - name: posting_id
        in: path
        required: true
        schema:
          type: string
          title: Posting Id
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePostingRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponse_PostingResponse_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/postings/{posting_id}/stats:
    get:
      tags:
      - Interviewers
      summary: Get interviewer stats
      description: 'Retrieve aggregate statistics for an interviewer in a single call: total candidate count, completed interview count, and average interview and resume scores.


        The two score fields are independent per-agent averages and are `null` when that agent is not part of the interviewer''s workflow, or when no candidate has been scored yet.'
      operationId: getPostingStats
      parameters:
      - name: posting_id
        in: path
        required: true
        schema:
          type: string
          title: Posting Id
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponse_PostingStatsResponse_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/postings/{posting_id}/workflow/{step_id}:
    patch:
      tags:
      - Interviewers
      summary: Update a workflow step's config
      description: Partially update one workflow step's config without touching other steps or posting-level fields. ``step_id`` is the step's ``type`` or its 1-based ``order``.
      operationId: updateInterviewerWorkflowStep
      parameters:
      - name: posting_id
        in: path
        required: true
        schema:
          type: string
          title: Posting Id
      - name: step_id
        in: path
        required: true
        schema:
          type: string
          title: Step Id
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkflowStepRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponse_PostingResponse_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/postings/{posting_id}/archive:
    post:
      tags:
      - Interviewers
      summary: Archive an interviewer
      description: Archive an interviewer. Archived interviewers stop accepting new candidates.
      operationId: archivePosting
      parameters:
      - name: posting_id
        in: path
        required: true
        schema:
          type: string
          title: Posting Id
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponse_PostingResponse_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/postings/{posting_id}/activate:
    post:
      tags:
      - Interviewers
      summary: Activate an interviewer
      description: 'Activate an interviewer so it begins accepting candidates. The interviewer must have a valid workflow configuration.


        For ATS-derived postings still in the `pending_activation` intermediate stage (created via `createPosting` with an ATS-derived `interview_template_id`, or `clonePosting` of an ATS-derived posting), this call finalizes the posting **and** attaches the ATS mapping so candidate ingestion from the ATS begins. The two steps run in one call; the ATS attach is idempotent and best-effort, so re-calling activate is safe and a transient ATS integrator hiccup will not block finalize.'
      operationId: activatePosting
      parameters:
      - name: posting_id
        in: path
        required: true
        schema:
          type: string
          title: Posting Id
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponse_PostingResponse_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/postings/{posting_id}/clone:
    post:
      tags:
      - Interviewers
      summary: Clone an interviewer
      description: 'Create a copy of an existing interviewer with its workflow configuration.


        If the source interviewer is ATS-derived, the clone is returned in the same intermediate stage as a fresh ATS create (`status: "draft"`, `ats_metadata.pending_activation: true`) and must be transitioned to live via `POST /postings/{posting_id}/activate`. Cloning a non-ATS posting is unchanged.'
      operationId: clonePosting
      parameters:
      - name: posting_id
        in: path
        required: true
        schema:
          type: string
          title: Posting Id
      - name: X-API-KEY
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Workspace-Id
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Workspace-Id
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleResponse_CreatePostingResponse_'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PostingURLs:
      properties:
        candidate_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Candidate Url
          description: Candidate-facing interview URL.
          examples:
          - https://candidates.heymilo.io/acme/senior-engineer
        ingestion_url_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Ingestion Url Key
          description: URL key for candidate ingestion. Use with POST /intake/v1/candidate/{key}.
          examples:
          - ibURejyPMSlw6de0OZUdoxyoXTgWO78ey2NUo96EOG1gY
        review_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Review Url
          description: Admin dashboard review URL.
          examples:
          - https://admin.heymilo.ai/w/ABC123/lab2/POST_ID/1-details
      type: object
      title: PostingURLs
      description: All URLs associated with a posting.
    ListResponse_PostingResponse_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/PostingResponse'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
      type: object
      required:
      - data
      - pagination
      title: ListResponse[PostingResponse]
    PaginationMeta:
      properties:
        has_more:
          type: boolean
          title: Has More
          description: Whether more results exist beyond this page
        total_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Total Count
          description: Total number of results (if available)
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: URL of this resource
      type: object
      required:
      - has_more
      title: PaginationMeta
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    APIError:
      properties:
        type:
          type: string
          title: Type
          description: Error category
          examples:
          - invalid_request_error
        code:
          type: string
          title: Code
          description: Machine-readable error code
          examples:
          - validation_error
        message:
          type: string
          title: Message
          description: Human-readable summary
          examples:
          - The request body failed validation
        param:
          anyOf:
          - type: string
          - type: 'null'
          title: Param
          description: Top-level parameter that caused the error
        doc_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Doc Url
          description: Link to relevant documentation
        errors:
          items:
            $ref: '#/components/schemas/APIErrorDetail'
          type: array
          title: Errors
          description: Detailed per-field validation errors
      type: object
      required:
      - type
      - code
      - message
      title: APIError
    PostingStatsResponse:
      properties:
        object:
          type: string
          const: posting_stats
          title: Object
          description: Object type identifier.
          default: posting_stats
        posting_id:
          type: string
          title: Posting Id
          description: ID of the posting these stats describe.
          examples:
          - 13D77095
        title:
          type: string
          title: Title
          description: Job title of the posting.
          examples:
          - Senior Software Engineer
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: URL-friendly slug for the posting.
          examples:
          - senior-software-engineer
        total_candidates:
          type: integer
          title: Total Candidates
          description: Total number of candidates registered to the posting.
          examples:
          - 142
        completed_interviews:
          type: integer
          title: Completed Interviews
          description: Number of candidates that have fully completed the posting's workflow (every step complete).
          examples:
          - 87
        average_interview_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Average Interview Score
          description: Average web-interview score (0-100) across scored candidates. ``null`` when the posting has no web-interview agent or no candidate has been scored yet.
          examples:
          - 72.4
        average_resume_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Average Resume Score
          description: Average resume score (0-100) across scored candidates. ``null`` when the posting has no resume agent or no candidate has been scored yet.
          examples:
          - 65.1
      type: object
      required:
      - posting_id
      - title
      - total_candidates
      - completed_interviews
      title: PostingStatsResponse
      description: 'Aggregate statistics for a single posting.


        Returned in a single call without paginating the posting''s candidates.

        The two score fields are independent per-agent averages (not blended):

        each is ``null`` when that agent is not part of the posting''s workflow,

        or when no candidate has produced a score for it yet.'
    _FormStep:
      properties:
        type:
          type: string
          const: form
          title: Type
          description: Agent type.
        config:
          anyOf:
          - $ref: '#/components/schemas/FormConfig'
          - type: 'null'
          description: Form screening agent configuration.
        questions:
          anyOf:
          - items:
              $ref: '#/components/schemas/CreateQuestion'
            type: array
          - type: 'null'
          title: Questions
          description: Questions for this step. If omitted, AI auto-generates.
      type: object
      required:
      - type
      title: _FormStep
      description: Workflow step for form screening agent.
    ConversationalSMSConfig:
      properties:
        instructions:
          anyOf:
          - type: string
            maxLength: 10000
          - type: 'null'
          title: Instructions
          description: Per-step override for AI interviewer instructions. Falls back to the posting-level 'instructions' when omitted.
        company_overview:
          anyOf:
          - type: string
            maxLength: 10000
          - type: 'null'
          title: Company Overview
          description: Per-step override for company overview. Falls back to the posting-level 'company_overview' when omitted.
        job_overview:
          anyOf:
          - type: string
            maxLength: 10000
          - type: 'null'
          title: Job Overview
          description: Per-step override for job overview. Falls back to the posting-level 'job_overview' when omitted.
        interview_process_overview:
          anyOf:
          - type: string
            maxLength: 10000
          - type: 'null'
          title: Interview Process Overview
          description: Per-step override for interview process overview. Falls back to the posting-level 'interview_process_overview' when omitted.
        company_overview_delivery_mode:
          anyOf:
          - type: string
            enum:
            - exact_delivery
            - summarized_delivery
            - reference_only
            - silent_reference
          - type: 'null'
          title: Company Overview Delivery Mode
          description: Per-step override for how the AI interviewer delivers the company overview. Falls back to the posting-level value when omitted.
        job_overview_delivery_mode:
          anyOf:
          - type: string
            enum:
            - exact_delivery
            - summarized_delivery
            - reference_only
            - silent_reference
          - type: 'null'
          title: Job Overview Delivery Mode
          description: Per-step override for how the AI interviewer delivers the job overview. Falls back to the posting-level value when omitted.
        interview_process_overview_delivery_mode:
          anyOf:
          - type: string
            enum:
            - exact_delivery
            - summarized_delivery
            - reference_only
            - silent_reference
          - type: 'null'
          title: Interview Process Overview Delivery Mode
          description: Per-step override for how the AI interviewer delivers the interview process overview. Falls back to the posting-level value when omitted.
 

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/heymilo/refs/heads/main/openapi/heymilo-interviewers-api-openapi.yml