> ## 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 role



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/roles
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/roles:
    post:
      tags:
        - Roles
      summary: Create role
      operationId: post_api_v1_roles
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                template_name:
                  type: string
                  description: Display name, e.g. "Senior Backend Engineer"
                use_case:
                  type: string
                  enum:
                    - hiring
                    - admissions
                    - training
                    - custom_api
                  description: Determines recommendation vocabulary
                description:
                  type: string
                  description: 1–3 sentence overview of the role
                objective:
                  type: string
                  description: What the interview should determine
                success_outcome:
                  type: string
                  enum:
                    - hire_no_hire
                    - admit_reject
                    - pass_fail
                    - ready_needs_training
                    - certified_not_certified
                    - custom
                  description: Outcome label (auto-derived from use_case if omitted)
                status:
                  type: string
                  enum:
                    - draft
                    - active
                    - archived
                  description: 'Default: active'
                domain:
                  type: string
                  description: Industry or field, e.g. "Software Engineering"
                level:
                  type: string
                  description: Seniority, e.g. "Senior / 5+ years"
                requirements:
                  type: string
                  description: What the candidate must demonstrate to pass
                skills:
                  type: array
                  items:
                    type: string
                  description: Technical skills to probe, e.g. ["Go", "PostgreSQL"]
                soft_skills:
                  type: array
                  items:
                    type: string
                  description: Behavioural traits, e.g. ["Communication", "Ownership"]
                additional_notes:
                  type: string
                  description: Context for the AI — company culture, edge cases, etc.
                default_duration_minutes:
                  type: integer
                  description: 'Default session length (default: 30)'
                default_difficulty:
                  type: string
                  enum:
                    - beginner
                    - intermediate
                    - advanced
                    - expert
                    - adaptive
                  description: 'Default: intermediate'
                default_session_mode:
                  type: string
                  enum:
                    - live_ai_interview
                    - async_interview
                    - roleplay_simulation
                    - practice_session
                    - manual_review
                  description: 'Default: live_ai_interview'
                visibility:
                  type: string
                  enum:
                    - private
                    - team
                    - organization
                    - public_template
                  description: 'Default: team'
              required:
                - template_name
                - use_case
                - description
                - objective
      responses:
        '201':
          description: Success
        '400':
          description: Bad Request — Validation error — check issues array
          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 (roles.write)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict — A template with this name already exists
          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.

````