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

# Create or fork an interviewer

> Creates a new interviewer from the body below. To **fork** an existing public profile into your account instead, call this endpoint with `?action=fork` and a body of `{ "sourceId": "<public-profile-uuid>" }`.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/interviewers
openapi: 3.1.0
info:
  title: intervyo.ai REST API
  version: 1.0.0
  description: >-
    Programmatic access to participants, sessions, roles, rounds, interviewers,
    and code execution.


    **Authentication.** Pass your API key in the `x-api-key` header (`x-api-key:
    iv_live_...`). Keys are created in the team dashboard under **Developer →
    API Keys**. Session (cookie) auth also works from the dashboard; for those
    calls pass `accountSlug` as a query parameter.
servers:
  - url: https://www.intervyo.ai
    description: Production
security:
  - apiKey: []
tags:
  - name: Participants
    description: >-
      Participants (candidates, applicants, trainees) are the people being
      evaluated. Create them first, then schedule sessions.
  - name: Sessions
    description: >-
      A session is one AI interview instance for one participant. Create a
      participant first, then schedule a session — the invite email is sent
      automatically.
  - name: Roles
    description: >-
      Templates define what the AI should assess — the role, skills, objective,
      and pass bar. Every session and stage belongs to a template.
  - name: Rounds
    description: >-
      Stages are the individual interview steps within a template — e.g. Phone
      Screen → Technical → Final. Each stage can have a different AI agent,
      duration, and pass threshold.
  - name: Interviewers
    description: >-
      Interviewers define the AI persona, evaluation dimensions, scoring logic,
      and tone. Assign an Interviewer to a Round to customise how the AI
      conducts that interview.
  - name: Code Execution
    description: >-
      Run candidate code against test cases. Currently supports python,
      javascript, and typescript via the OneCompiler runner. This endpoint is
      also exposed as the execute_code MCP tool — same engine, different
      transport.
  - name: Remote MCP Server
    description: >-
      Expose problem generation and code execution to any MCP-compatible client
      (Claude Desktop, Claude Code, Cursor). Speaks JSON-RPC 2.0 over HTTP.
      Requires an API key — session cookies are NOT accepted on this surface.
      Usage is metered against your plan (mcp_problem_generations and
      mcp_code_executions).
paths:
  /api/v1/interviewers:
    post:
      tags:
        - Interviewers
      summary: Create or fork an interviewer
      description: >-
        Creates a new interviewer from the body below. To **fork** an existing
        public profile into your account instead, call this endpoint with
        `?action=fork` and a body of `{ "sourceId": "<public-profile-uuid>" }`.
      operationId: post_api_v1_interviewers
      parameters:
        - name: action
          in: query
          required: false
          schema:
            type: string
          description: Set to "fork" to fork a public profile instead of creating a new one
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Display name, e.g. "Senior Engineering Interviewer"
                persona:
                  type: string
                  description: How the AI introduces itself at the start of a session
                useCase:
                  type: string
                  enum:
                    - hiring
                    - admissions
                    - training
                    - custom_api
                  description: Determines recommendation vocabulary
                evaluationDimensions:
                  type: array
                  items:
                    type: object
                  description: '[{ name, description, weight }] — weights must sum to 100'
                context:
                  type: object
                  additionalProperties: true
                  description: '{ organizationContext?, domainContext?, scenarioContext? }'
                interaction:
                  type: object
                  additionalProperties: true
                  description: >-
                    { tone?: friendly|professional|strict|challenging, style?:
                    structured|conversational|adaptive, difficulty?:
                    easy|medium|hard|adaptive, probingDepth?: low|medium|high }
                scoring:
                  type: object
                  additionalProperties: true
                  description: >-
                    { scale?: 0-10|0-5|0-100, scoringMethod?:
                    weighted_average|rule_based, recommendationLogic? }
                output:
                  type: object
                  additionalProperties: true
                  description: >-
                    { includeTranscript?, includeScoreBreakdown?,
                    includeRecommendation?, includeImprovementFeedback? } — all
                    default to true
                additionalInstructions:
                  type: string
                  description: Edge cases, constraints, or tone overrides for this agent
                isPublic:
                  type: boolean
                  description: 'Publish to the shared library (default: false)'
              required:
                - name
                - persona
                - useCase
                - evaluationDimensions
      responses:
        '201':
          description: Success
        '400':
          description: Bad Request — Validation error — weights must sum to 100
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Payment Required — Active paid plan required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — Insufficient permissions (interviewers.write)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        issues:
          type: array
          items:
            type: object
          description: Field-level validation issues (present on 400 responses)
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key with the `iv_live_` prefix. Create one under Developer → API
        Keys.

````