Servers Playground How we check Add a server Log in

JobMojito

Working · 2.3 s

com.jobmojito/jobmojitov1.3.2 Domain verified

Run AI interviews, simulated personas and coaching sessions on JobMojito.

Education

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://mcp.jobmojito.com/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

create_catalogue_directory Destructive

[Coaching catalogue] Create a directory (page) in the coaching portal catalogue. A directory nests other directories (`tags_sub`), lists coaching sessions whose own `tags` match its `tags_interview_set_filter`, and can carry a fully custom Markdown page (`content_md`) with `[sessions]`, `[directory:…]`, `[session:…]` and `[plan-progress]` directives. One directory can hold several languages: the top-level fields are the default language, `translations` adds the others. Coaching-platform feature. Creates a directory (page) in the coaching portal catalogue. A directory nests other directories through `tags_sub`, lists coaching sessions through `tags_interview_set_filter`, and can replace the default grid with a custom Markdown page through `content_md`. The id you choose is the catalogue URL segment and cannot be changed afterwards.

idstring, required

Directory id — also the catalogue URL segment (/catalogue/<id>) and the value other directories reference in their `tags_sub`. Lowercase letters, digits and single - or _ separators. Convention is to end language-specific directories with the language code, e.g. `sales-coaching-en`.

namestring, required

Display name of the directory, shown as the page title and on its card.

statusstring

Lifecycle status of the catalogue directory. Options — `draft`: Not published — the directory exists but is not served to visitors. | `active`: Published and served in the catalogue. | `archived`: Retired — kept for reference but no longer served..

tags_subarray

Ids of the directories nested under this one, in display order. Replaces the whole list — send the full set, not just the additions. A referenced directory only appears if it exists and is visible to the viewer.

coach_planstring

Coaching-plan stage this item belongs to, used by the coaching-plan progress view. Omit/null to leave it out of any plan. Options — `demo`: Demo session. | `screening`: Screening-interview practice. | `2nd`: Second-interview practice. | `3rd`: Third-interview practice. | `closing`: Closing / salary-negotiation practice. | `job-specific`: Job-specific coaching. | `other`: Anything that does not fit the other buckets..

content_mdstring

Markdown for a custom directory page. When set (even as an empty string) the markdown replaces the default grid and decides the layout itself; null renders the plain grid of sub-directories and sessions. Alongside normal Markdown you can place these directives, each ALONE on its own line: `[plan-progress]` (the learner's coaching-plan progress), `[directory:<tag-id>]` (a card for one sub-directory), `[session:<interview-id>]` (a card for one session), `[sessions]` (every session in this directory), `[sessions:<term>]` (sessions matching a term), `[sessions:filter=<term>,limit=<n>]` (a filtered, capped list). A directive on a line with other text is rendered as ordinary text. Chips, callouts, cards, columns and buttons are available here too — full vocabulary: https://developer.jobmojito.com/cookbooks/format-content-with-markdown

parent_tagstring

Id of an existing directory to nest this new one under: the new id is appended to that directory's `tags_sub`. Omit to create a top-level directory (reachable via a direct link, or by adding it to another directory later).

visibilitystring

Who can see the catalogue directory. Options — `public`: Shared across every merchant. Platform admins only — a merchant caller is rejected by row-level security. | `merchant_public`: Listed in the merchant's own catalogue — the normal choice. | `merchant_invite`: Owned by the merchant but not listed; reachable only for invited users. | `merchant_unlisted`: Owned by the merchant but not listed; reachable only via a direct link..

descriptionstring

Short description shown on the directory card.

merchant_idstring

Merchant that owns the directory. Admin / sub-merchant callers only; otherwise taken from your token.

translationsobject

Other language versions of the directory, keyed by mojito language code. The top-level fields are the default language (`mojito_language_code`); each version is a page of its own (name, Markdown, session filter, sub-directories) shown to learners who pick that language. A key may not equal `mojito_language_code`.

conversation_idstring

Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

cover_image_urlstring

Cover image URL shown on the directory card.

mojito_language_codestring

Language of the directory (one of the platform-languages.json codes). The catalogue groups directories by language; defaults to `en` when omitted.

tags_interview_set_filterarray

Tag filter selecting which coaching sessions this directory lists: a session appears when its own `tags` contain EVERY tag here (an AND, not an OR). Only `active` coaching/persona sessions with visibility `public` or `merchant_public` are listed. Set the matching tags on the session with the create-interview / job-interview-update `tags` field.

The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.

I understand, run it anyway

JobMojito MCP server | mcptry

JobMojito

Working · 2.3 s

com.jobmojito/jobmojitov1.3.2 Domain verified

Run AI interviews, simulated personas and coaching sessions on JobMojito.

Education

Source Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://mcp.jobmojito.com/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

create_catalogue_directory Destructive

idstring, required

namestring, required

Display name of the directory, shown as the page title and on its card.

statusstring

tags_subarray

coach_planstring

content_mdstring

parent_tagstring

visibilitystring

descriptionstring

Short description shown on the directory card.

merchant_idstring

Merchant that owns the directory. Admin / sub-merchant callers only; otherwise taken from your token.

translationsobject

conversation_idstring

cover_image_urlstring

Cover image URL shown on the directory card.

mojito_language_codestring

Language of the directory (one of the platform-languages.json codes). The catalogue groups directories by language; defaults to `en` when omitted.

tags_interview_set_filterarray

The server marks this tool as destructive. Running it may delete or overwrite data on the server or in any account you connected with your headers.

I understand, run it anyway

Tools (38)

create_catalogue_directory

destructive

Argument	Type	Description
id*	string \| null	Directory id — also the catalogue URL segment (/catalogue/<id>) and the value other directories reference in their `tags_sub`. Lowercase letters, digits and single - or _ separators. Convention is to end language-specific directories with the language code, e.g. `sales-coaching-en`.
name*	string \| null	Display name of the directory, shown as the page title and on its card.
status	string \| null	Lifecycle status of the catalogue directory. Options — `draft`: Not published — the directory exists but is not served to visitors. \| `active`: Published and served in the catalogue. \| `archived`: Retired — kept for reference but no longer served..
tags_sub	array \| null	Ids of the directories nested under this one, in display order. Replaces the whole list — send the full set, not just the additions. A referenced directory only appears if it exists and is visible to the viewer.
coach_plan	string \| null	Coaching-plan stage this item belongs to, used by the coaching-plan progress view. Omit/null to leave it out of any plan. Options — `demo`: Demo session. \| `screening`: Screening-interview practice. \| `2nd`: Second-interview practice. \| `3rd`: Third-interview practice. \| `closing`: Closing / salary-negotiation practice. \| `job-specific`: Job-specific coaching. \| `other`: Anything that does not fit the other buckets..
content_md	string \| null	Markdown for a custom directory page. When set (even as an empty string) the markdown replaces the default grid and decides the layout itself; null renders the plain grid of sub-directories and sessions. Alongside normal Markdown you can place these directives, each ALONE on its own line: `[plan-progress]` (the learner's coaching-plan progress), `[directory:<tag-id>]` (a card for one sub-directory), `[session:<interview-id>]` (a card for one session), `[sessions]` (every session in this directory), `[sessions:<term>]` (sessions matching a term), `[sessions:filter=<term>,limit=<n>]` (a filtered, capped list). A directive on a line with other text is rendered as ordinary text. Chips, callouts, cards, columns and buttons are available here too — full vocabulary: https://developer.jobmojito.com/cookbooks/format-content-with-markdown
parent_tag	string \| null	Id of an existing directory to nest this new one under: the new id is appended to that directory's `tags_sub`. Omit to create a top-level directory (reachable via a direct link, or by adding it to another directory later).
visibility	string \| null	Who can see the catalogue directory. Options — `public`: Shared across every merchant. Platform admins only — a merchant caller is rejected by row-level security. \| `merchant_public`: Listed in the merchant's own catalogue — the normal choice. \| `merchant_invite`: Owned by the merchant but not listed; reachable only for invited users. \| `merchant_unlisted`: Owned by the merchant but not listed; reachable only via a direct link..
description	string \| null	Short description shown on the directory card.
merchant_id	string \| null	Merchant that owns the directory. Admin / sub-merchant callers only; otherwise taken from your token.
translations	object \| null	Other language versions of the directory, keyed by mojito language code. The top-level fields are the default language (`mojito_language_code`); each version is a page of its own (name, Markdown, session filter, sub-directories) shown to learners who pick that language. A key may not equal `mojito_language_code`.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
cover_image_url	string \| null	Cover image URL shown on the directory card.
mojito_language_code	string \| null	Language of the directory (one of the platform-languages.json codes). The catalogue groups directories by language; defaults to `en` when omitted.
tags_interview_set_filter	array \| null	Tag filter selecting which coaching sessions this directory lists: a session appears when its own `tags` contain EVERY tag here (an AND, not an OR). Only `active` coaching/persona sessions with visibility `public` or `merchant_public` are listed. Set the matching tags on the session with the create-interview / job-interview-update `tags` field.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id",
    "name"
  ],
  "properties": {
    "id": {
      "type": [
        "string",
        "null"
      ],
      "example": "sales-coaching-en",
      "pattern": "^[a-z0-9]+(?:(?:-|_)+[a-z0-9]+)*$",
      "minLength": 1,
      "description": "Directory id — also the catalogue URL segment (/catalogue/<id>) and the value other directories reference in their `tags_sub`. Lowercase letters, digits and single - or _ separators. Convention is to end language-specific directories with the language code, e.g. `sales-coaching-en`."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Sales coaching",
      "minLength": 1,
      "description": "Display name of the directory, shown as the page title and on its card."
    },
    "status": {
      "enum": [
        "draft",
        "active",
        "archived",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "active",
      "description": "Lifecycle status of the catalogue directory. Options — `draft`: Not published — the directory exists but is not served to visitors. | `active`: Published and served in the catalogue. | `archived`: Retired — kept for reference but no longer served.."
    },
    "tags_sub": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "example": [
        "sales-coaching-objections-en",
        "sales-coaching-closing-en"
      ],
      "description": "Ids of the directories nested under this one, in display order. Replaces the whole list — send the full set, not just the additions. A referenced directory only appears if it exists and is visible to the viewer."
    },
    "coach_plan": {
      "enum": [
        "demo",
        "screening",
        "2nd",
        "3rd",
        "closing",
        "job-specific",
        "other",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "screening",
      "description": "Coaching-plan stage this item belongs to, used by the coaching-plan progress view. Omit/null to leave it out of any plan. Options — `demo`: Demo session. | `screening`: Screening-interview practice. | `2nd`: Second-interview practice. | `3rd`: Third-interview practice. | `closing`: Closing / salary-negotiation practice. | `job-specific`: Job-specific coaching. | `other`: Anything that does not fit the other buckets.."
    },
    "content_md": {
      "type": [
        "string",
        "null"
      ],
      "example": "## Sales coaching\n\nPick a session to practise with.\n\n[chip:6 sessions] [chip:Beginner,tone=accent]\n\n[sessions:filter=objection-handling,limit=6]\n",
      "description": "Markdown for a custom directory page. When set (even as an empty string) the markdown replaces the default grid and decides the layout itself; null renders the plain grid of sub-directories and sessions. Alongside normal Markdown you can place these directives, each ALONE on its own line: `[plan-progress]` (the learner's coaching-plan progress), `[directory:<tag-id>]` (a card for one sub-directory), `[session:<interview-id>]` (a card for one session), `[sessions]` (every session in this directory), `[sessions:<term>]` (sessions matching a term), `[sessions:filter=<term>,limit=<n>]` (a filtered, capped list). A directive on a line with other text is rendered as ordinary text. Chips, callouts, cards, columns and buttons are available here too — full vocabulary: https://developer.jobmojito.com/cookbooks/format-content-with-markdown"
    },
    "parent_tag": {
      "type": [
        "string",
        "null"
      ],
      "example": "home-employee-en",
      "description": "Id of an existing directory to nest this new one under: the new id is appended to that directory's `tags_sub`. Omit to create a top-level directory (reachable via a direct link, or by adding it to another directory later)."
    },
    "visibility": {
      "enum": [
        "public",
        "merchant_public",
        "merchant_invite",
        "merchant_unlisted",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "merchant_public",
      "description": "Who can see the catalogue directory. Options — `public`: Shared across every merchant. Platform admins only — a merchant caller is rejected by row-level security. | `merchant_public`: Listed in the merchant's own catalogue — the normal choice. | `merchant_invite`: Owned by the merchant but not listed; reachable only for invited users. | `merchant_unlisted`: Owned by the merchant but not listed; reachable only via a direct link.."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "example": "Practice discovery, objection handling and closing.",
      "description": "Short description shown on the directory card."
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Merchant that owns the directory. Admin / sub-merchant callers only; otherwise taken from your token."
    },
    "translations": {
      "type": [
        "object",
        "null"
      ],
      "example": {
        "sk": {
          "name": "Obchodný koučing",
          "tags_interview_set_filter": [
            "sales-sk"
          ]
        }
      },
      "description": "Other language versions of the directory, keyed by mojito language code. The top-level fields are the default language (`mojito_language_code`); each version is a page of its own (name, Markdown, session filter, sub-directories) shown to learners who pick that language. A key may not equal `mojito_language_code`.",
      "additionalProperties": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Obchodný koučing",
            "minLength": 1,
            "description": "Page title and card name in this language."
          },
          "tags_sub": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "example": [
              "sales-coaching-objections-en",
              "sales-coaching-closing-en"
            ],
            "description": "Ids of the directories nested under this one, in display order. Replaces the whole list — send the full set, not just the additions. A referenced directory only appears if it exists and is visible to the viewer."
          },
          "content_md": {
            "type": [
              "string",
              "null"
            ],
            "example": "## Sales coaching\n\nPick a session to practise with.\n\n[chip:6 sessions] [chip:Beginner,tone=accent]\n\n[sessions:filter=objection-handling,limit=6]\n",
            "description": "Markdown for a custom directory page. When set (even as an empty string) the markdown replaces the default grid and decides the layout itself; null renders the plain grid of sub-directories and sessions. Alongside normal Markdown you can place these directives, each ALONE on its own line: `[plan-progress]` (the learner's coaching-plan progress), `[directory:<tag-id>]` (a card for one sub-directory), `[session:<interview-id>]` (a card for one session), `[sessions]` (every session in this directory), `[sessions:<term>]` (sessions matching a term), `[sessions:filter=<term>,limit=<n>]` (a filtered, capped list). A directive on a line with other text is rendered as ordinary text. Chips, callouts, cards, columns and buttons are available here too — full vocabulary: https://developer.jobmojito.com/cookbooks/format-content-with-markdown"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Card description in this language."
          },
          "cover_image_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cover image for this language. Omit to show the default language's cover."
          },
          "tags_interview_set_filter": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "example": [
              "sales",
              "objection-handling"
            ],
            "description": "Tag filter selecting which coaching sessions this directory lists: a session appears when its own `tags` contain EVERY tag here (an AND, not an OR). Only `active` coaching/persona sessions with visibility `public` or `merchant_public` are listed. Set the matching tags on the session with the create-interview / job-interview-update `tags` field."
          }
        },
        "additionalProperties": false
      }
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "cover_image_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cover image URL shown on the directory card."
    },
    "mojito_language_code": {
      "enum": [
        "ar",
        "bg",
        "zh",
        "hr",
        "cs",
        "da",
        "nl",
        "en",
        "fil",
        "fi",
        "fr",
        "de",
        "el",
        "hi",
        "hu",
        "id",
        "it",
        "ja",
        "ko",
        "ms",
        "no",
        "pl",
        "pt",
        "br",
        "ro",
        "ru",
        "sk",
        "es",
        "sv",
        "ta",
        "th",
        "tr",
        "uk",
        "vi",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "en",
      "description": "Language of the directory (one of the platform-languages.json codes). The catalogue groups directories by language; defaults to `en` when omitted."
    },
    "tags_interview_set_filter": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "example": [
        "sales",
        "objection-handling"
      ],
      "description": "Tag filter selecting which coaching sessions this directory lists: a session appears when its own `tags` contain EVERY tag here (an AND, not an OR). Only `active` coaching/persona sessions with visibility `public` or `merchant_public` are listed. Set the matching tags on the session with the create-interview / job-interview-update `tags` field."
    }
  }
}

create_interview

[Interviews] Create a new interview and auto-generate its question sequence from position data. The `interview_template_id` you pass also sets the modality (voice-only vs realtime/pre-recorded avatar) — see `list_avatars`. Creates a new interview / coaching / assessment definition, generates its description, questions and candidate expectations via AI, and provisions default steps. Optionally provisions an embed key.

destructive

Argument	Type	Description
code	string \| null	Optional external code/reference for the interview.
name*	string \| null	Interview / position name.
tags	array \| null	Free-form tags stored on the interview. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed.
type*	string \| null	Product type of the interview. Options — `interview`: Standard candidate interview for a role — answers are AI-scored and produce a hiring recommendation. \| `coaching`: Practice/coaching session — candidate-facing feedback to help them improve; not a hiring evaluation. Only available on the coaching portal, NOT the interview portal. \| `assessment`: Skills/knowledge assessment — evaluates competencies and is scored like an interview..
status

create_interview_from_questions

[Interviews] Create a new interview from an explicit array of questions. The AI rephrases your wording by default; pass `interview_tone="exact"` to have each question asked verbatim, which is what you want when the wording is a script (compliance, translated, or legally reviewed text). Creates a new interview definition set from a caller-provided array of questions, builds its default and generated steps, optionally activates it, and optionally creates an embed key.

destructive

Argument	Type	Description
code	string \| null	Optional external code/reference.
name*	string \| null	Interview/position name.
tags	array \| null	Free-form tags stored on the interview. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed.
type*	string \| null	Product type of the interview. Options — `interview`: Standard candidate interview for a role — answers are AI-scored and produce a hiring recommendation. \| `coaching`: Practice/coaching session — candidate-facing feedback to help them improve; not a hiring evaluation. Only available on the coaching portal, NOT the interview portal. \| `assessment`: Skills/knowledge assessment — evaluates competencies and is scored like an interview..

create_persona

[Interviews] Create a role-play persona: an avatar that plays a defined role in a free-form conversation instead of a scored Q&A interview. FIRST CHOOSE `portal`, because it selects between two different products: `portal="interview"` builds a SIMULATED PERSONA a recruiter invites candidates to — scored, billed to merchant credits, and listed with the recruiter's other results; `portal="coaching"` (THE DEFAULT) builds a coaching persona learners start themselves from the catalogue, paid per second from their own coaching minutes and never visible to recruiters. Pass `portal="interview"` explicitly for any hiring, screening or assessment use. Then set `persona_role_avatar`/`persona_role_user` for the roles and `opening_line` for the avatar's first spoken line (defaults to a generic 'Hello'). FIRST DECIDE `portal`. This endpoint creates two different products and the default is NOT the recruiter one: - `portal: "interview"` — an INTERVIEW ROLE-PLAY. Use this whenever the goal is to ASSESS or SCREEN candidates: hiring, assessments, sales role-plays for job applicants, anything a recruiter runs. Candidates are invited through the normal invitation flow, results appear in the recruiter's result list, it is billed against merchant credits, and attempts are capped via `interview_attempts` — exactly like an interview. - `portal: "coaching"` (THE DEFAULT) — a coaching persona for practice/training on the coaching portal. Consumed against the mentee's own coaching credits, self-started from the catalogue, and its results are NOT visible to recruiters. Omitting `portal` gives you this one, so pass `portal: "interview"` explicitly for any recruiting/assessment use case. The conversation itself behaves identically in both. The avatar plays a defined role in a free-form conversation instead of running a scored Q&A interview. No AI question/description generation runs; the persona role fields ARE the configuration. The session runs as: a welcome message → the avatar's OPENING LINE (the first thing it says, set via `opening_line`) → the candidate replies and the free-form role-play begins → a closing message. Because there is no question list, `opening_line` is how the avatar starts the scene — set it to a concrete in-character line; if omitted it defaults to a generic "Hello". Set `welcome_message` and `thank_you_message` too — omitting them leaves the generic platform defaults. Also set `candidate_expectations`: it is the yardstick the session is scored against. The four avatar prompts divide up as: `persona_avatar_who_is` (identity and what drives it), `persona_avatar_knowledge` (the private facts it may use), `persona_avatar_progress` (how the conversation is allowed to move forward, and what gates the later personal details), and `persona_avatar_end_conditions` (when to stop). Without `persona_avatar_progress` the avatar has no defined arc and tends to either concede immediately or never concede at all. Provisions the default conversational steps and optionally an embed key.

create_report

[Reports] Save a new custom report from a definition (schema jobmojito.report/v1). It is created as Only me: tell the user they can share it from the returned admin_url. Check the definition with preview_report first. Stores a new custom report. It is created as "Only me" (private to you); share it from the JobMojito admin. Returns its id, version and the admin link to open it. Check the definition with preview_report first.

destructive

Argument	Type	Description
definition*	object	A custom report: report-wide filters and up to 12 blocks. Read report-catalog first for the dataset, field and measure ids.
merchant_id	string \| null	Optional merchant to act on. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "definition"
  ],
  "properties": {
    "definition": {
      "type": "object",
      "example": {
        "title": "Weekly hiring pulse",
        "blocks": [
          {
            "id": "headline",
            "type": "kpi",
            "compare": "previous_period",
            "dataset": "interview_results",
            "measures": [
              "completed",
              "avg_score",
              "shortlisted"
            ]
          },
          {
            "id": "trend",
            "type": "line",
            "title": "Completed per week",
            "width": 8,
            "dataset": "interview_results",
            "measures": [
              "completed"
            ],
            "dimensions": [
              {
                "field": "date",
                "grain": "week"
              }
            ]
          },
          {
            "id": "by_position",
            "sort": [
              {
                "dir": "desc",
                "field": "completed"
              }
            ],
            "type": "table",
            "limit": 25,
            "title": "By position",
            "dataset": "interview_results",
            "measures": [
              "completed",
              "avg_score",
              "shortlisted"
            ],
            "dimensions": [
              "position"
            ]
          }
        ],
        "schema": "jobmojito.report/v1",
        "filters": {
          "period": {
            "preset": "last_30_days"
          }
        }
      },
      "required": [
        "schema",
        "title",
        "blocks"
      ],
      "properties": {
        "title": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 120,
          "minLength": 1
        },
        "blocks": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "required": [
              "id",
              "type"
            ],
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "by_position",
                "pattern": "^[A-Za-z0-9_-]{1,40}$"
              },
              "sort": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "required": [
                    "field"
                  ],
                  "properties": {
                    "dir": {
                      "enum": [
                        "asc",
                        "desc",
                        null
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "field": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^[a-z][a-z0-9_]{0,40}$",
                      "description": "A dimension or measure the block selects."
                    }
                  },
                  "additionalProperties": false
                },
                "maxItems": 3
              },
              "text": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 4000,
                "description": "Text block only: the note (plain text, line breaks kept)."
              },
              "type": {
                "enum": [
                  "kpi",
                  "table",
                  "bar",
                  "stacked_bar",
                  "line",
                  "funnel",
                  "text",
                  null
                ],
                "type": [
                  "string",
                  "null"
                ],
                "description": "kpi: one total per measure (no dimensions; add compare previous_period for a change). funnel: 2+ measures as steps (no dimensions). table: 0-2 dimensions. bar: 1-2 dimensions. stacked_bar: exactly 2 dimensions. line: first dimension a date. text: a note, only `text`."
              },
              "limit": {
                "type": [
                  "integer",
                  "null"
                ],
                "maximum": 500,
                "minimum": 1,
                "description": "Rows for a table / bar / line. Default 100 (line 500)."
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 120
              },
              "where": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "required": [
                    "field",
                    "op"
                  ],
                  "properties": {
                    "op": {
                      "enum": [
                        "eq",
                        "neq",
                        "in",
                        "not_in",
                        "gt",
                        "gte",
                        "lt",
                        "lte",
                        "between",
                        "is_empty",
                        "is_not_empty",
                        null
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "field": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^[a-z][a-z0-9_]{0,40}$",
                      "description": "A dimension of the block's dataset."
                    },
                    "value": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "number"
                        },
                        {
                          "type": "boolean"
                        },
                        {
                          "type": "array",
                          "items": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "number"
                              }
                            ]
                          }
                        }
                      ],
                      "description": "One value for eq / neq / gt / gte / lt / lte, a list for in / not_in, [low, high] for between, nothing for is_empty / is_not_empty."
                    }
                  },
                  "additionalProperties": false
                },
                "maxItems": 10
              },
              "width": {
                "type": [
                  "integer",
                  "null"
                ],
                "maximum": 12,
                "minimum": 1,
                "description": "Columns of a 12-column grid. Default 12."
              },
              "compare": {
                "enum": [
                  "previous_period",
                  null
                ],
                "type": [
                  "string",
                  "null"
                ],
                "description": "kpi / funnel only: also return the same numbers for the period before."
              },
              "dataset": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "interview_results",
                "description": "Dataset id from report-catalog. Not used by a text block."
              },
              "measures": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9_]{0,40}$"
                },
                "example": [
                  "completed",
                  "avg_score"
                ],
                "maxItems": 6,
                "minItems": 1,
                "description": "1 to 6 measure ids of the dataset."
              },
              "dimensions": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "anyOf": [
                    {
                      "type": "string",
                      "pattern": "^[a-z][a-z0-9_]{0,40}$"
                    },
                    {
                      "type": "object",
                      "required": [
                        "field"
                      ],
                      "properties": {
                        "field": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^[a-z][a-z0-9_]{0,40}$"
                        },
                        "grain": {
                          "enum": [
                            "day",
                            "week",
                            "month",
                            "quarter",
                            "year",
                            null
                          ],
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "For a date field: day (default), week, month, quarter or year."
                        }
                      },
                      "additionalProperties": false
                    }
                  ],
                  "description": "A dimension field id, or {\"field\", \"grain\"} for a date."
                },
                "maxItems": 2
              }
            },
            "additionalProperties": false
          },
          "maxItems": 12
        },
        "schema": {
          "enum": [
            "jobmojito.report/v1",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "description": "Always \"jobmojito.report/v1\"."
        },
        "filters": {
          "type": "object",
          "properties": {
            "period": {
              "anyOf": [
                {
                  "type": "object",
                  "required": [
                    "preset"
                  ],
                  "properties": {
                    "preset": {
                      "enum": [
                        "last_7_days",
                        "last_30_days",
                        "last_90_days",
                        "this_month",
                        "last_month",
                        "this_quarter",
                        "last_quarter",
                        "this_year",
                        "last_year",
                        "all_time",
                        null
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "required": [
                    "from",
                    "to"
                  ],
                  "properties": {
                    "to": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                    },
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                    }
                  },
                  "additionalProperties": false
                }
              ],
              "example": {
                "preset": "last_30_days"
              },
              "description": "Either a preset, or from and to dates (YYYY-MM-DD, both inclusive, UTC). Default: last_30_days."
            },
            "include_test": {
              "type": [
                "boolean",
                "null"
              ],
              "description": "Include test runs. Default false."
            },
            "position_ids": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "maxItems": 200,
              "description": "Positions to show (position ids from list_interviews). position_ids, interview_ids and without_position are one pick list: a row shows when it belongs to ANY pick. Nothing picked = all."
            },
            "interview_ids": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "maxItems": 200,
              "description": "Interviews to show (interview ids from list_interviews), combined with the other picks by OR. Nothing picked = all."
            },
            "without_position": {
              "type": [
                "boolean",
                "null"
              ],
              "description": "Also pick interviews that are not part of any position (stand-alone interviews, and coaching sessions). Combined with the other picks by OR."
            }
          },
          "description": "Filters for every block of the report. Each viewer can override them for themselves.",
          "additionalProperties": false
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 1000
        }
      },
      "description": "A custom report: report-wide filters and up to 12 blocks. Read report-catalog first for the dataset, field and measure ids.",
      "additionalProperties": false
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Optional merchant to act on. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

generate_interview_report

[Results] Generate an interview result report (HTML/PDF/JSON) for a completed interview. The report is decision-support material for a human reviewer, not an automated hiring decision. Generates an interview result report as a PDF (returns a signed URL), raw HTML, or structured JSON. Provide either `interview_result_id` for a single result or `interview_result_ids` for a combined multi-result report.

destructive

Argument	Type	Description
template	any
store_file	boolean \| null	When true (pdf only), persist the file to storage and return a signed URL.
export_type*	string \| null
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
interview_result_id	string \| null
interview_result_ids	array \| null	Generate a single combined report for multiple results.

generate_interview_url

[Interviews] Generate a signed public interview URL/token. Generates a public, token-signed URL for an existing interview, profile, or result. The required id fields depend on `type`.

destructive

Argument	Type	Description
type*	string \| null	Which kind of signed URL to generate.
hide_menu	any	Pass the string 'false' to show the navigation menu; any other value hides it (default).
merchant_id	string \| null	Override merchant id (admin / sub-merchant only).
interview_id	string \| null	Interview or position id. Required for interview-for-profile and interview-results-for-position.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
interview_result_id	string \| null	Interview result id. Required for interview-result-candidate and interview-result-talent-seeker.

get_catalogue_directory

[Coaching catalogue] Read one catalogue directory in full: its settings, its custom Markdown page (`content_md`), its resolved sub-directories, and the coaching sessions its tag filter currently matches — which is how you verify that a session's `tags` actually place it in this directory. Read before updating: `content_md`, `tags_sub` and `tags_interview_set_filter` are replaced wholesale, so you need the current value to extend it. Other language versions of the page are in `translations` (`languages` lists them, default first). Reads one catalogue directory in full: its settings, its custom Markdown page (`content_md`), the sub-directories it nests, and the coaching sessions its `tags_interview_set_filter` currently matches. Read a directory before updating it — `content_md`, `tags_sub` and `tags_interview_set_filter` are replaced wholesale by catalogue-tag-update, so you need the current value to extend rather than overwrite it.

read-only

Argument	Type	Description
id*	string	Id of the catalogue directory to read (the catalogue URL segment). The old id of a renamed directory also works; the response carries its current `id`.
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

get_documentation

Fetch the full content of a single JobMojito documentation page. Accepts a URL returned by `search_documentation`. For developer docs the clean Markdown (.md) variant is fetched automatically. Only developer.jobmojito.com and help.jobmojito.com URLs are allowed.

read-only

Argument	Type	Description
url*	string	The documentation page URL.
max_chars	integer	Truncate content to this many characters (default 20000).
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string",
      "description": "The documentation page URL."
    },
    "max_chars": {
      "type": "integer",
      "default": 20000,
      "description": "Truncate content to this many characters (default 20000)."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  },
  "additionalProperties": false
}

get_interview_definition

[Interviews] Get the definition/configuration of an interview (position), including its ordered `questions` array. The questions come back in the same format create_interview_from_questions accepts, so you can read an interview here, change the array, and send it to update_interview. Each question's `id` identifies it — keep the ids you did not mean to change. Retrieves the interview definition for a given interview-definition id or position id. Returns the compiled `calc_definition_json`, the ordered `questions` array (in the same format job-interview-create-from-array accepts, so it round-trips into job-interview-update) plus basic metadata. Access is subject to the caller's row-level security.

read-only

Argument	Type	Description
position_id*	string	Identifier of either an interview definition (single-stage) or a position definition (multi-stage). The function resolves whichever matches.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "position_id"
  ],
  "properties": {
    "position_id": {
      "type": "string",
      "format": "uuid",
      "example": "00000000-0000-0000-0000-000000000000",
      "minLength": 1,
      "description": "Identifier of either an interview definition (single-stage) or a position definition (multi-stage). The function resolves whichever matches."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

get_interview_result_details

[Results] Get full interview result details including transcript and scores. Scores are assistive output for a human reviewer. One result is a large record, so `view` controls how much of it comes back — the default (`standard`) omits only the raw machine assessment data. Returns an interview result with its full transcript and AI assessment. Optionally attaches signed recording URLs.

read-only

Argument	Type	Description
view	string	How much of the record to return. Handled by the MCP server, not the JobMojito API — it only narrows the response, never the query. - `summary`: scores, the overall AI analysis, and each question with the candidate's answer — no per-answer AI commentary, recording paths or raw assessment data. Use this to review or compare candidates. - `standard`: everything a human reviewer reads: the full transcript with per-answer analysis, scores and recordings, minus the raw machine assessment blobs. This is the default. - `full`: every field, including the per-answer raw assessment data — condensed: pronunciation and sentiment scores per recognised segment with the lowest-scoring words, reading/gaze statistics, STT reliability, proctor status and seconds per detected speaker. Word-, character- and frame-level arrays are left out (listed in `_omitted`). Only ask for this if you need those assessment details.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
interview_result_id

get_merchant_analytics

[Results] Get the merchant's daily event analytics. Daily event-count time-series for a merchant over a date range (the admin-portal analytics events graph), scoped to your token's merchant (or a merchant_id override). Optionally drilled to a single interview. Capped at 1000 records per page. Note: only day/event combinations with a non-zero count are returned — any day/event pair absent from the response should be treated as a count of 0 by the caller.

read-only

Argument	Type	Description
limit	integer	Maximum number of records to return (1–1000).
offset	integer	Number of records to skip from the start of the result set.
date_to*	string	End of the date range (inclusive), YYYY-MM-DD.
date_from*	string	Start of the date range (inclusive), YYYY-MM-DD.
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
interview_id	string	Optional interview (interview_def_set) or position (position_def_set) id to drill the event counts down. The type is detected automatically: a position aggregates the daily counts across every interview that makes up the position; an interview filters to that single definition.

get_merchant_credit_usage

[Results] Get the merchant's credit usage. Per-event credit-usage ledger for a merchant: every billable analytics event (interview, pre-screening, public avatar, simulation, …) that consumed credits, ordered most recent first. Scoped to your token's merchant, or a merchant_id override for admins / sub-merchant operators. The credits consumed by each event are in stats.credit_amount. Capped at 1000 records per page.

read-only

Argument	Type	Description
limit	integer	Maximum number of records to return (1–1000).
offset	integer	Number of records to skip from the start of the result set.
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
interview_id	string	Optional interview (interview_def_set) or position (position_def_set) id to drill the credit-usage ledger down to a single interview or position. The type is detected automatically: for a position the response combines pre-screening and interview-result credits across the whole position; for an interview it returns that interview's credit events (including simulations and report translations).
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

get_merchant_status

[Admin] Get a merchant status snapshot: credit balances, subscription, pending-work counts, candidate/result totals, and invitation headroom. Status snapshot for a merchant: interview-credit balances, subscription type/status, pending-work counts (undecided / ongoing / uncredited interviews), candidate & result totals with 14-day history, and invitation headroom. Scoped to your token's merchant (or a merchant_id override for admins / sub-merchant operators). Also echoes the caller's profile_id and default_merchant_id from the token, plus the effective merchant_id.

read-only

Argument	Type	Description
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

get_report

[Reports] Get a custom report's JSON definition, visibility, your access and its version. Read it before update_report: the definition is replaced whole and the version must match. The report's JSON definition, visibility, your access (owner, edit, view) and its version (needed to update it). People who can edit also get the unpublished draft, if any.

read-only

Argument	Type	Description
id*	string	Report id (from list_reports).
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Report id (from list_reports)."
    },
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

jobmojito_configuration

Show the interactive JobMojito merchant picker (UI). ALWAYS call this when the user wants to choose, switch, or set a merchant, or when a tool needs a `merchant_id` and none is selected. It renders a searchable picker with clickable options. Do NOT list merchants as text or ask the user to type a name — render this picker instead. After calling it, STOP and wait for the user's selection; then pass `merchant_id=<chosen id>` on every JobMojito call (omit it for the user's own account).

read-only

Argument	Type	Description
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  },
  "additionalProperties": false
}

list_avatars

[Admin] List available avatar/voice templates. Each item's `type` decides the interview modality: `interactive_elevenlabs` = voice-only (no video avatar); `interactive_spatius` = realtime interactive 3D avatar (rendered in the candidate's browser, 1.25 credits, no early stop); `interactive_heygen` = premium realtime interactive video avatar; `offline_heygen` = pre-recorded, non-interactive avatar. An item's `id` is the `interview_template_id` you pass to the create-interview tools, so pick the template whose type matches the experience you want. Note: `offline_elai` and `offline_synthesia` are legacy integrations that may still appear here but cannot be used to create new interviews. Rows are large, so this returns 15 at a time; page with `offset` while `pagination.has_more` is true, or narrow with `type`/`filter_text`. Paginated list of a merchant's avatar templates (the admin-portal avatars list), scoped to your token's merchant (or a merchant_id override). Capped at 1000 records per page.

read-only

Argument	Type	Description
type	string	Filter by avatar template type. Omit for all.
limit	integer	Maximum number of records to return (1–1000).
offset	integer	Number of records to skip from the start of the result set.
status	string	Filter by status. Omit for all except archived (see include_archived).
filter_text	string	Case-insensitive search on template name or voice language name.

list_candidates

[Candidates] List the merchant's candidates. Paginated list of a merchant's candidates (the admin-portal candidates list), scoped to your token's merchant (or a merchant_id override). Capped at 1000 records per page.

read-only

Argument	Type	Description
tab	string	Filter candidates by recent activity. Omit (or empty) to include all.
limit	integer	Maximum number of records to return (1–1000).
offset	integer	Number of records to skip from the start of the result set.
source	string	Filter by how the candidate entered: invited or self-registered. Omit for both.
order_by	string	Sort order of the result set.
filter_text	string	Search on candidate name, email, external id, phone and CV skills. Every word must match (case and accents ignored; longer words tolerate typos). Without order_by, the best matches come first.
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
filter_emoji

list_catalogue_directories

[Coaching catalogue] List the coaching-catalogue directories you can see (your merchant's own plus the platform-wide public ones). Start here to find a directory id, to pick a parent for a new one, or to walk the tree with `parent_tag`; `is_start_directory` marks the page the catalogue opens on. The custom Markdown page is not included — read it with get_catalogue_directory. Returns 25 at a time; page with `offset` while `pagination.has_more` is true. Paginated list of the coaching-catalogue directories visible to you: your merchant's own, plus the platform-wide `public` ones unless you set include_public=false. Use it to find a directory id before updating one, to pick a `parent_tag`, or to walk the tree with `parent_tag`. The custom Markdown page is not included — fetch it per directory with catalogue-tag-get.

read-only

Argument	Type	Description
limit	integer	Maximum number of records to return (1–1000).
offset	integer	Number of records to skip from the start of the result set.
status	string	Filter by lifecycle status. Omit to include every status you can see (deleted directories are never returned).
parent_tag	string	Return only the directories nested directly under this one (its `tags_sub`), in the parent's own order. Combine with the other filters to narrow further.
visibility	string	Filter by visibility.

list_interview_results

[Results] List the merchant's interview results. Rows carry the candidate's scores and recruiter risk flags, so this returns 20 at a time; page with `offset` while `pagination.has_more` is true, or narrow with `tab`/`interview_id`/`filter_text`. Paginated list of a merchant's interview results (the admin-portal results list), scoped to your token's merchant (or a merchant_id override). Capped at 1000 records per page.

read-only

Argument	Type	Description
tab	string	Filter by decision/completion state. Omit (or empty) to include all.
step	string	Filter by pipeline step type (pre-screening, interview or meeting). Omit for all.
type	string	Product type of results to list.
limit	integer	Maximum number of records to return (1–1000).
risks	string	Comma-separated list of recruiter-risk keys to filter by (matches any).
offset	integer	Number of records to skip from the start of the result set.
order_by	string	Sort order of the result set.
filter_text	string

list_interviews

[Interviews] List the merchant's interview definitions. Paginated list of a merchant's interview definitions (the admin-portal interview list), scoped to your token's merchant (or a merchant_id override). Capped at 1000 records per page.

read-only

Argument	Type	Description
type	string	Product type of interviews to list.
limit	integer	Maximum number of records to return (1–1000).
offset	integer	Number of records to skip from the start of the result set.
status	string	Filter by lifecycle status. Omit to include all statuses.
show_demo	string	Include demo/sample interviews.
filter_text	string	Case-insensitive search on the interview name.
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
show_public	string	Include interviews shared publicly across merchants (coaching/avatars).

list_languages

[Admin] List supported platform (mojito) languages: the `code` to pass as `mojito_language_code`, English/local names, SVG flag URL, per-interface enablement flags, and Azure speech accents. Returns all supported platform (mojito) languages: the mojito language code, English and local names, and an SVG flag image URL. Use the `code` as `mojito_language_code` when creating interviews or personas.

read-only

Argument	Type	Description
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

list_my_merchants

FALLBACK merchant list for clients WITHOUT UI support. Do NOT use this to choose or switch merchants when a UI is available — call `jobmojito_configuration` instead (it renders an interactive picker), and do not hand-format a merchant list as text. Use this tool only when the client cannot render MCP App UI. Returns the user's own account plus any sub-merchants; after a pick, pass `merchant_id=<chosen id>` on subsequent calls (OMIT for the own account).

read-only

Argument	Type	Description
search	string	Optional case-insensitive filter on sub-merchant name.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "default": "",
      "description": "Optional case-insensitive filter on sub-merchant name."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  },
  "additionalProperties": false
}

list_report_fields

[Reports] List what a custom report can use on this account: datasets (interview results, invitations, position pipeline, ATS pipeline, credits, coaching sessions - only those the account and your role include), their dimensions (group by / conditions, with allowed values) and measures. Call this first: a report definition may only use ids listed here. Custom reports are switched on per account by JobMojito; while they are off, every report tool is refused with 403 'Custom reports are not enabled for this account.' Tell the user to contact JobMojito rather than retrying. Everything a custom report may use on this account: the datasets (interview results, invitations, position pipeline, ATS pipeline, credits, coaching sessions - only those your account and role include), their dimensions (group by / filter) and measures (numbers), block types, condition operators and period presets. Read this before writing a report definition: ids not listed here are refused.

read-only

Argument	Type	Description
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

list_reports

[Reports] List custom reports you can open (yours, shared with you) and the JobMojito templates, with id, title, visibility, your access and version. Custom reports you can open on this account (yours, the ones shared with you) and the JobMojito templates. Pinned first, then most recently updated.

read-only

Argument	Type	Description
scope	string	all (default), mine, shared (by colleagues) or templates.
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "scope": {
      "enum": [
        "all",
        "mine",
        "shared",
        "templates"
      ],
      "type": "string",
      "default": "all",
      "description": "all (default), mine, shared (by colleagues) or templates."
    },
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

list_sub_merchants

[Admin] List sub-merchants under the merchant account. Paginated list of the sub-merchants the caller administers (the admin-portal sub-merchants list). Visibility is enforced by row-level security. Capped at 1000 records per page.

read-only

Argument	Type	Description
limit	integer	Maximum number of records to return (1–1000).
offset	integer	Number of records to skip from the start of the result set.
order_by	string	Sort order of the result set.
filter_text	string	Case-insensitive search on the sub-merchant name.
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 50,
      "example": 50,
      "maximum": 1000,
      "minimum": 1,
      "description": "Maximum number of records to return (1–1000)."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "example": 0,
      "minimum": 0,
      "description": "Number of records to skip from the start of the result set."
    },
    "order_by": {
      "enum": [
        "name",
        "created_at_newest",
        "created_at_oldest"
      ],
      "type": "string",
      "default": "created_at_newest",
      "example": "created_at_newest",
      "description": "Sort order of the result set."
    },
    "filter_text": {
      "type": "string",
      "description": "Case-insensitive search on the sub-merchant name."
    },
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

preview_report

[Reports] Validate a report definition against the catalogue and run it without saving anything. Use it before create_report / update_report: a block that is wrong comes back with ok=false and an error naming the field and the valid ids. Validates a report definition against the catalogue and runs it, without storing anything. Use it to check a definition before create_report or update_report. A 422 names the block and field that is wrong and lists the valid ids.

read-only

Argument	Type	Description
filters	any
block_id	string \| null	Run only this block.
definition*	object	A custom report: report-wide filters and up to 12 blocks. Read report-catalog first for the dataset, field and measure ids.
merchant_id	string \| null	Optional merchant to act on. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

register_users_for_interview

[Interviews] Register users/candidates for a specific interview and return their personal interview links. Registers (or updates) one or more candidate profiles for an interview and returns a one-time interview URL for each. Accepts a Supabase user JWT (merchant/admin) or the service key (merchant_id then required).

destructive

Argument	Type	Description
users*	array \| null	Candidates to register for the interview. Each gets a one-time interview URL.
is_test	any	When true (or the string "true"), mints a test token that can take a draft/unpublished interview and flags the result as a test. For a DRAFT interview it also recompiles the definition (interview_recalc_definition) first, so the test session includes the current questions/welcome. This makes it a single-call "trigger interview test".
hide_menu	any	When true (or the string "true"), the interview UI hides its menu (view_hm).
send_email	boolean \| null	Whether to send an invitation email to each registered candidate.
hide_iframe	any	When true (or the string "true"), the interview UI hides its iframe chrome (view_hi).
merchant_id	string \| null	Merchant id. Required when authenticating with the service key; for user tokens it is optional and only honored for admin / sub-merchant accounts.

report_technical_issue

[Feedback] Report a technical problem to JobMojito support. It opens a support conversation from the signed-in user's account (their e-mail), with their company and the interview or result ids given; support answers there. Describe what was done, what was expected and what happened (error text as shown). Confirm the wording with the user first; at most 5 a day. Reports a technical problem to JobMojito support. It opens a support conversation from your account (your e-mail), with your company and the ids you give; support answers there. At most 5 reports per user in 24 hours. Requires a user token (admin console session or MCP sign-in) of a merchant, merchant owner or admin.

destructive

Argument	Type	Description
result_id	string \| null	The interview result the problem is about, if any.
description*	string \| null	What went wrong: what you did, what you expected, what happened instead (error messages as shown), and since when. Plain text; blank lines separate paragraphs. Do not include passwords or API keys.
interview_id	string \| null	The interview (definition) the problem is about, if any.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

request_another_interview_attempt

[Results] Re-open a submitted interview result so the candidate can retry. Marks a submitted (active + completed) interview result as unsuccessful so the candidate can retake it. Resets the result to draft and clears the recruiter decision.

destructive

Argument	Type	Description
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
interview_result_id*	string \| null	The interview result to reopen for another attempt.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "interview_result_id"
  ],
  "properties": {
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "interview_result_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "93c98d21-e04d-4a84-9afa-ed154cf73636",
      "minLength": 1,
      "description": "The interview result to reopen for another attempt."
    }
  }
}

run_report

[Reports] Run a saved custom report and return each block's rows (aggregated numbers, at most 500 rows per block). Optional `filters` JSON overrides the period / positions / interviews for this run only. Report numbers are decision-support material for a human reviewer. Runs every block of a saved report and returns its rows. Filters start from the report's defaults, then your own saved filters, then `filters` if you pass it. Each block runs on its own: a block that fails returns ok=false with an error while the others still return data. Numbers are aggregated; no block returns more than 500 rows.

read-only

Argument	Type	Description
id*	string	Report id (from list_reports).
draft	string	Run the unpublished draft instead (only if you can edit the report).
filters	string	Optional JSON ReportFilters to apply on top, e.g. {"period":{"preset":"last_month"}}.
block_id	string	Run only this block.
merchant_id	string	Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

search_documentation

Search ALL JobMojito documentation. This is the single entry point. One call searches both documentation sources in parallel and returns a merged, source-labeled list — you do not need to choose a source or call a separate tool: • "developer" — developer.jobmojito.com: API reference, request/response schemas, tables, webhooks, code examples, integration guides. • "help" — help.jobmojito.com: recruiter, candidate, and administrator product guides (how the platform behaves for end users). Use this whenever you need to understand how a feature, endpoint, field, or workflow works — including before calling an action tool you're unsure about. Then call `get_documentation(url)` with a returned URL to read the full page.

read-only

Argument	Type	Description
limit	integer	Max results per source (1-25).
query*	string	Natural-language search query or keywords.
source	string	"all" (default), "developer", or "help" to restrict the search.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 8,
      "description": "Max results per source (1-25)."
    },
    "query": {
      "type": "string",
      "description": "Natural-language search query or keywords."
    },
    "source": {
      "type": "string",
      "default": "all",
      "description": "\"all\" (default), \"developer\", or \"help\" to restrict the search."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  },
  "additionalProperties": false
}

set_interview_state

[Interviews] Change the state of an interview/position (e.g. open, closed). Changes the lifecycle status of an interview or position (draft, active, archived, preparing, completed, deleted) and/or manages its embed key. Provide at least one of `status` or `is_embedded`.

destructive

Argument	Type	Description
status	string \| null	New lifecycle status to apply.
is_embedded	boolean \| null	Controls iframe embedding of the interview on an external page. When true, ensures an embed key exists (returns embed_id/embed_signing_key, used to authenticate/sign the iframe embed). When false, removes the embed keys (disables embedding). Where it runs depends on the type: interviews, assessments and interview role-plays embed on the interview portal (`https://<interview portal domain>/embed?embed_id=...`); coaching sessions and coaching personas embed on the consumer (coaching) portal (`https://<coaching portal domain>/embed?embed_id=...`, a link built on the interview portal is forwarded there). A signed coaching embed (name, email, signature) signs the visitor in as a learner of that portal, and the session is charged to the merchant's interview credits on completion, not to the learner's coaching credits; it cannot start while the merchant has none.
position_id*	string \| null	Interview definition id or position id whose state should change.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

submit_feature_request

[Feedback] Send a feature request to the JobMojito product team. It is posted on the public feature request board under the signed-in user's name, where they get status updates; the company is not named. Write a short title and a description of the need and why (no candidate data or company names). Confirm the wording with the user before submitting; at most 5 a day. Sends a feature request to the JobMojito product team. It is posted on the public feature request board under your name (from your account e-mail), where you get status updates and others can vote on it; your company is not named. At most 5 requests per user in 24 hours. Requires a user token (admin console session or MCP sign-in) of a merchant, merchant owner or admin.

destructive

Argument	Type	Description
title*	string \| null	A short summary of the feature, shown as the post title.
description*	string \| null	What the user needs and why: the problem, how they work around it today, who it would help. Plain text; blank lines separate paragraphs. The board is public: do not include candidate data, company names or other personal information.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

Input schema (JSON)

update_catalogue_directory

[Coaching catalogue] Update a coaching catalogue directory: rename it, change which sessions it lists (`tags_interview_set_filter`), re-order its sub-directories (`tags_sub`), author its custom Markdown page (`content_md`), or add, replace or remove a language version (`translations`, per language; null removes one). Only the fields you send are changed. Coaching-platform feature. Updates a directory (page) of the coaching portal catalogue. Only the fields present in the request body are written — everything else keeps its current value, and sending null clears a nullable field. Use it to rename a directory, re-point which sessions it lists (`tags_interview_set_filter`), re-order or replace its sub-directories (`tags_sub`), author its custom Markdown page (`content_md`), or add, replace and remove its other language versions (`translations`).

destructive

Argument	Type	Description
id*	string \| null	Id of the directory to update (the catalogue URL segment). The id itself is not changed here — rename a directory in the admin catalogue editor, which moves every link to it.
name	string \| null	Display name of the directory.
status	string \| null	Lifecycle status of the catalogue directory. Options — `draft`: Not published — the directory exists but is not served to visitors. \| `active`: Published and served in the catalogue. \| `archived`: Retired — kept for reference but no longer served..
tags_sub	array \| null	Ids of the directories nested under this one, in display order. Replaces the whole list — send the full set, not just the additions. A referenced directory only appears if it exists and is visible to the viewer.

update_interview

[Interviews] Update the configuration of an existing interview/position: name, description, avatar template, recording, scoring, tags and the rest of the create-time settings. Only the fields you send are changed. To change the questions, send `questions` — the WHOLE list you want the interview to end up with, in order, in the format get_interview_definition returns. OMIT `questions` and the existing questions are left completely alone; there is no way to change one question on its own, so read the interview first, edit that array, and send it back. Resending an unchanged array does nothing. Not updated by this tool at all: the welcome and thank-you messages and the instructional-video screen (stored as steps, not questions), and the language, which the existing questions are already written in. Use `tags` to place a coaching session into a catalogue directory. MULTI-STAGE POSITIONS: some per-interview settings do not exist at position level and are rejected with a 422 naming the field — `candidate_expectations_json` is the one seen in practice. Read the position with get_interview_definition, then update the individual stage you mean instead of sending that field to the position. Updates the configuration of an existing interview (single-stage) or position (multi-stage). Only the fields present in the request body are written — everything else keeps its current value, and sending null clears a nullable field. The question list is only touched when you send `questions`; omit that field and the questions are left exactly as they are. When sent, it must be the complete list and is applied as a diff against what is stored (matched on external_id, then id, then identical content), so unchanged questions keep their existing records, edited ones are unlinked and re-created, and dropped ones are unlinked — and re-sending the array job-interview-get returned changes nothing. See the field description, and `questions_diff` in the response for what was decided. Questions of an interview that is already `active` can only be changed on interactive avatar templates, where re-publishing is instant; on the offline (pre-rendered video) templates set the interview back to `draft` first. The welcome / thank-you messages and the instructional-video screen are stored as steps rather than questions and are never changed here. `mojito_language_code` cannot be changed — the existing questions and rendered videos are in the original language — so create a new interview to change language. A multi-stage position only carries the shared identity fields (name, code, location, description, description_long, cover_image_url, department, salary, available_till, recruiter, status, visibility, hiring_for_company); sending an interview-only field for a position is a 422.

update_report

[Reports] Replace a custom report's definition (send the whole definition and the version from get_report). On a report shared with other people the change is saved as a draft that the owner publishes in the admin; a private report updates at once. Replaces the definition of a report you own or may edit. Send the version you read; if someone changed the report since, you get 409 and should get it again. A report shared with others keeps your change as a draft until it is published in the admin, so viewers never see a half-finished report.

destructive

Argument	Type	Description
id*	string \| null	Report id (from list_reports).
target	string \| null	published (default) or draft. A private report always publishes. Through the MCP server a shared report always gets a draft that its owner publishes in the admin.
version*	integer \| null	The version you read (get_report / list_reports). A stale version is refused with 409.
definition*	any
merchant_id	string \| null	Optional merchant to act on. Admins and sub-merchant operators only; other callers always use their token's merchant.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.

upload_knowledge_base_document

[Knowledge base] Upload and process a knowledge base document (multipart form-data). Uploads a document to a knowledge base store and queues it for processing. Accepts the file either as multipart/form-data (binary `file`) or as application/json (base64 `file`).

destructive

Argument	Type	Description
file*	string \| null	The document file (binary).
name	string \| null	Document name (with extension). Falls back to the uploaded file name for multipart.
merchant_id	string \| null	Override merchant id (admin / sub-merchant only).
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
knowledge_base_store_id*	string \| null	The knowledge base store to add the document to.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "knowledge_base_store_id",
    "file"
  ],
  "properties": {
    "file": {
      "type": [
        "string",
        "null"
      ],
      "format": "binary",
      "description": "The document file (binary)."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Document name (with extension). Falls back to the uploaded file name for multipart."
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Override merchant id (admin / sub-merchant only)."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "knowledge_base_store_id": {
      "type": [
        "string",
        "null"
      ],
      "example": "d9d6f121-1230-48fd-b3a7-8b5a1e8db052",
      "minLength": 1,
      "description": "The knowledge base store to add the document to."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "name",
    "location",
    "interview_template_id",
    "mojito_language_code",
    "status",
    "type",
    "visibility"
  ],
  "properties": {
    "code": {
      "type": [
        "string",
        "null"
      ],
      "example": "my code",
      "description": "Optional external code/reference for the interview."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Project manager",
      "minLength": 1,
      "description": "Interview / position name."
    },
    "tags": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "example": [
        "interview-practice",
        "sales"
      ],
      "description": "Free-form tags stored on the interview. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed."
    },
    "type": {
      "enum": [
        "interview",
        "coaching",
        "assessment",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "interview",
      "description": "Product type of the interview. Options — `interview`: Standard candidate interview for a role — answers are AI-scored and produce a hiring recommendation. | `coaching`: Practice/coaching session — candidate-facing feedback to help them improve; not a hiring evaluation. Only available on the coaching portal, NOT the interview portal. | `assessment`: Skills/knowledge assessment — evaluates competencies and is scored like an interview.."
    },
    "status": {
      "enum": [
        "draft",
        "active",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "active",
      "description": "Lifecycle status of the interview. Options — `draft`: Created but not published — not visible to candidates and cannot be run yet. Use to stage an interview before going live. | `active`: Published and live — candidates can run it.."
    },
    "location": {
      "type": [
        "string",
        "null"
      ],
      "example": "remote",
      "minLength": 1,
      "description": "Job location — a city/country, or `remote`. Required and must not be empty: when the job description gives no location, pass `Not specified`."
    },
    "recording": {
      "enum": [
        "audio_first_5_answers",
        "audio_all",
        "video_all",
        "video_first_5_answers",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "video_all",
      "description": "Cheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Video options also record the candidate. Omit/null to disable. Options — `audio_first_5_answers`: Audio-only cheating detection, first 5 answers only. | `audio_all`: Audio-only cheating detection on every answer. | `video_all`: Audio + video cheating detection on every answer (candidate is recorded for all answers). | `video_first_5_answers`: Audio + video cheating detection, first 5 answers only.."
    },
    "visibility": {
      "enum": [
        "merchant_public",
        "merchant_invite",
        "merchant_unlisted",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "merchant_public",
      "description": "Who can discover and access the interview. Options — `merchant_public`: Listed on the merchant's public interview list — anyone with the merchant link can find and start it. | `merchant_invite`: Invite-only — only candidates explicitly invited (by email/link) can access it; not listed anywhere. | `merchant_unlisted`: Reachable only via a direct link — not listed anywhere; share the link manually.."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "example": "Backend role focused on Python, async APIs, and AWS.",
      "description": "Short, two-sentence job description shown to the candidate. Provide it to use it as-is; leave it null/blank and it is AI-generated from the position name and any other context."
    },
    "environment": {
      "enum": [
        "production",
        "uat",
        "development",
        "demo",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "production",
      "description": "Which of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. | `uat`: User-acceptance testing - an isolated environment for pre-release verification. | `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. | `demo`: Demonstrations and sales trials.."
    },
    "is_embedded": {
      "type": [
        "boolean",
        "null"
      ],
      "example": false,
      "description": "Set true when the interview will be embedded as an iframe on an external page. Provisions an embed key and returns embed_id / embed_signing_key, which are used to authenticate/sign the iframe embed. Where it runs depends on the type: interviews, assessments and interview role-plays embed on the interview portal (`https://<interview portal domain>/embed?embed_id=...`); coaching sessions and coaching personas embed on the consumer (coaching) portal (`https://<coaching portal domain>/embed?embed_id=...`, a link built on the interview portal is forwarded there). A signed coaching embed (name, email, signature) signs the visitor in as a learner of that portal, and the session is charged to the merchant's interview credits on completion, not to the learner's coaching credits; it cannot start while the merchant has none."
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Merchant id. Admin / sub-merchant callers only; otherwise taken from your token."
    },
    "result_view": {
      "enum": [
        "none",
        "minimal",
        "minimal_with_score",
        "advanced",
        "full",
        "full_expand_scores",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "full",
      "description": "Result screen shown to the candidate after finishing. With any value other than `none`, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Options — `none`: No results screen at all — the interview is submitted immediately when the candidate finishes (no feedback, intro video, transcript edit or manual submit step). | `minimal`: Minimal results layout, no score shown. | `minimal_with_score`: Minimal results layout including the overall score. | `advanced`: Advanced results layout with more detail. | `full`: Full results layout with all sections. | `full_expand_scores`: Full results with every score breakdown expanded.."
    },
    "max_duration": {
      "type": [
        "number",
        "null"
      ],
      "example": 1200,
      "description": "Maximum interview duration in seconds. Scopes how many questions are generated (see interview_length) and is stored on the interview as the live session limit and the basis for the credit multiplier. Defaults to 1200 (20 minutes) when omitted."
    },
    "max_followups": {
      "type": [
        "integer",
        "null"
      ],
      "example": 2,
      "maximum": 999,
      "minimum": 0,
      "description": "Maximum number of AI follow-up questions. 0 disables follow-ups; presets are 0-3 (none/low/normal/high) and custom values start at 4; null uses the template default (Normal)."
    },
    "custom_scoring": {
      "type": [
        "object",
        "null"
      ],
      "description": "Custom result-scoring overrides merged with defaults and template overrides.",
      "additionalProperties": {}
    },
    "interview_tone": {
      "enum": [
        "relaxed",
        "simple",
        "professional",
        "persuasive",
        "exact",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "professional",
      "description": "Interview tone — configures the AI avatar's speaking style and the tone of the AI-generated questions and follow-ups. Case-insensitive; omit to default to relaxed. Options — `relaxed`: Friendly and conversational tone that helps candidates feel at ease. | `simple`: Plain language at CEFR A2 level — short sentences and simple words. | `professional`: Formal and business-like approach suitable for senior roles. | `persuasive`: Engaging style that encourages candidates to elaborate. | `exact`: Asks the questions exactly as provided, without rephrasing — for interviews built from your own questions (create_interview_from_questions) where the wording is a script.."
    },
    "interview_type": {
      "enum": [
        "pre-screening",
        "pre-screening-with-test-questions",
        "second-interview",
        "remote-freelancer-verification",
        "strength-based-interview",
        "potential-based-interview",
        "process-verification-from-knowledge-base",
        "knockout-screening",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "pre-screening-with-test-questions",
      "description": "Interview style — configures the AI avatar and shapes both the AI-generated questions and the follow-up questions asked during the interview. Defaults to pre-screening when omitted. Options — `pre-screening`: Pre-screening — quick qualification check focusing on basic requirements and availability. | `pre-screening-with-test-questions`: Pre-screening with test questions — pre-screening plus practical questions to test relevant skills. | `second-interview`: Second round interview — deeper dive for candidates who passed initial screening. | `remote-freelancer-verification`: Remote worker verification — verify remote work capabilities and communication skills. | `strength-based-interview`: Strength-based interview — focus on what candidates enjoy and excel at to predict job satisfaction. | `potential-based-interview`: Potential-based interview — assess learning ability and growth potential rather than past experience. | `process-verification-from-knowledge-base`: Knowledge Base interview — generate questions from your knowledge base documents. | `knockout-screening`: Knock-out screening — a short (about 5 minute) check of the role's must-haves with closed questions; ends early, politely, when a must-have is clearly not met. On creation it defaults custom_scoring.early_stop to true (where the avatar supports early stop) and max_followups to 1 unless you send them.."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "cover_image_url": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://example.com/cover.png",
      "description": "Cover image URL."
    },
    "seniority_level": {
      "enum": [
        "entry-level",
        "intermediate",
        "senior",
        "managerial",
        "director",
        "executive",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "senior",
      "description": "Target seniority level for the role; auto-detected from the job description when omitted. Options — `entry-level`: Early-career or graduate roles. | `intermediate`: Some experience required. | `senior`: Experienced professional. | `managerial`: Team or department lead. | `director`: Director-level responsibility. | `executive`: C-suite or executive role.."
    },
    "welcome_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom welcome message shown to the candidate."
    },
    "description_long": {
      "type": [
        "string",
        "null"
      ],
      "description": "Full job description in Markdown (Job Purpose, Responsibilities, Required & Preferred Qualifications). Provide it to use it as-is; leave it null/blank and it is AI-generated (interview and assessment types only). Rendered as Markdown on the candidate-facing position page, including chips, callouts, cards, columns and buttons — formatting guide: https://developer.jobmojito.com/cookbooks/format-content-with-markdown"
    },
    "interview_length": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        },
        {}
      ],
      "example": 8,
      "description": "Number of questions to generate (1-40). Also capped by max_duration, which allows one question per 2 minutes: 20 min -> 10 questions, 30 min -> 15, 45 min -> 22, 60 min -> 30, 80 min -> 40. Asking for more than the cap is not an error — you get the cap, and the response reports the real count in questions_generated. Omit this field to let the AI pick 5-8."
    },
    "interview_salary": {
      "type": [
        "string",
        "null"
      ],
      "example": "$80k - $100k",
      "description": "Salary range shown for the position."
    },
    "thank_you_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom thank-you message shown after the interview."
    },
    "additional_context": {
      "type": [
        "object",
        "null"
      ],
      "description": "Arbitrary additional context object merged into AI generation.",
      "additionalProperties": {}
    },
    "hiring_for_company": {
      "type": [
        "object",
        "null"
      ],
      "example": {
        "name": "undisclosed"
      },
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ],
          "example": "Unimo Enterprises",
          "description": "End-employer name. Omit/null when hiring for yourself, 'undisclosed' for an unnamed external client, or the client's company name."
        },
        "sector": {
          "type": [
            "string",
            "null"
          ],
          "example": "Logistics and Supply Chain",
          "description": "Industry / sector of the end employer."
        },
        "location": {
          "type": [
            "string",
            "null"
          ],
          "example": "Sri Lanka",
          "description": "Primary location of the end employer."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "example": "Unimo Enterprises is a leading logistics and supply chain solutions provider.",
          "description": "Short description of the end employer, used as background context by the agent."
        },
        "company_size": {
          "type": [
            "string",
            "null"
          ],
          "example": "100-200",
          "description": "Approximate headcount of the end employer."
        }
      },
      "description": "Who the position is really for. Omit/null (or an object with name null/blank) when hiring for yourself; { name: 'undisclosed' } for an unnamed external client; or { name: '<company>' } plus optional description/location/sector/company_size for a named client. Stored in creation_parameters.hiring_for_company."
    },
    "interview_attempts": {
      "type": [
        "number",
        "null"
      ],
      "example": 1,
      "maximum": 20,
      "minimum": 1,
      "description": "Allowed candidate attempts (1-20)."
    },
    "instructional_video": {
      "type": [
        "boolean",
        "null"
      ],
      "example": true,
      "description": "Show an instructional video before approval. Defaults to false."
    },
    "interview_department": {
      "type": [
        "string",
        "null"
      ],
      "example": "Engineering",
      "description": "Department the position belongs to."
    },
    "mojito_language_code": {
      "enum": [
        "ar",
        "bg",
        "zh",
        "hr",
        "cs",
        "da",
        "nl",
        "en",
        "fil",
        "fi",
        "fr",
        "de",
        "el",
        "hi",
        "hu",
        "id",
        "it",
        "ja",
        "ko",
        "ms",
        "no",
        "pl",
        "pt",
        "br",
        "ro",
        "ru",
        "sk",
        "es",
        "sv",
        "ta",
        "th",
        "tr",
        "uk",
        "vi",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "en",
      "description": "Platform language code used for the interview. Must be one of the platform-languages.json codes."
    },
    "recruiter_profile_id": {
      "type": [
        "string",
        "null"
      ],
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant."
    },
    "interview_template_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "baa3bf7c-6926-46fd-9005-16738a31f72d",
      "minLength": 1,
      "description": "Id of the interview template to base this interview on."
    },
    "candidate_expectations": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-text candidate expectations folded into AI generation."
    },
    "include_closing_prompt": {
      "type": [
        "boolean",
        "null"
      ],
      "example": true,
      "description": "Include a closing prompt. Defaults to true."
    },
    "pdf_export_auto_config": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "files": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include uploaded candidate files."
        },
        "template": {
          "enum": [
            "classic",
            "modern",
            "one_pager",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "description": "Report layout: classic, modern, or one_pager. Omit for the merchant default (modern when unset)."
        },
        "analytics": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include analytics."
        },
        "transcript": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the interview transcript."
        },
        "contact_details": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include candidate contact details."
        },
        "answer_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include per-answer recordings."
        },
        "ai_scoring_rubric": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the AI scoring rubric."
        },
        "group_by_question": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Group transcript answers by expected question."
        },
        "session_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the full-session recording."
        },
        "mojito_language_code": {
          "enum": [
            "ar",
            "bg",
            "zh",
            "hr",
            "cs",
            "da",
            "nl",
            "en",
            "fil",
            "fi",
            "fr",
            "de",
            "el",
            "hi",
            "hu",
            "id",
            "it",
            "ja",
            "ko",
            "ms",
            "no",
            "pl",
            "pt",
            "br",
            "ro",
            "ru",
            "sk",
            "es",
            "sv",
            "ta",
            "th",
            "tr",
            "uk",
            "vi",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "example": "en",
          "description": "Report language code (a platform-languages.json code)."
        },
        "ai_recruiter_assessment": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the AI recruiter assessment."
        }
      },
      "description": "Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export."
    },
    "recording_full_session": {
      "enum": [
        "audio_all",
        "video_all",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "video_all",
      "description": "Full interview-session recording (includes the avatar and voice) produced as a single file. Independent of `recording`. Omit/null to disable. Options — `audio_all`: Record the whole session audio (avatar + candidate voice) into a single file. Adds +0.2 credits. | `video_all`: Record the whole session video + audio (avatar + candidate) into a single file. Adds +0.4 credits.."
    },
    "required_pronunciation": {
      "type": [
        "boolean",
        "null"
      ],
      "example": false,
      "description": "Require pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false."
    },
    "knowledge_base_store_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Knowledge base store id to source additional context from."
    },
    "questions_random_subset": {
      "type": [
        "number",
        "null"
      ],
      "example": 0.5,
      "maximum": 0.9,
      "minimum": 0.01,
      "description": "Ask only a random subset of the questions, expressed as a fraction between 0.01 and 0.9 (e.g. 0.5 = 50%). null asks all questions."
    },
    "include_rapport_question": {
      "type": [
        "boolean",
        "null"
      ],
      "example": true,
      "description": "Include an opening rapport question. Defaults to false."
    },
    "interview_available_till": {
      "type": [
        "string",
        "null"
      ],
      "example": "2026-12-31",
      "description": "ISO date/time after which the interview is no longer available to candidates. null keeps it always available."
    },
    "use_enhanced_expectations": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Reserved flag passed through to generation."
    },
    "candidate_video_introduction": {
      "enum": [
        "optional",
        "required",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "optional",
      "description": "Whether a candidate video introduction is optional or required."
    },
    "interview_conversation_speed": {
      "enum": [
        "slower",
        "normal",
        "faster",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "normal",
      "description": "Conversation pace of the AI avatar. Omit/null keeps the template default pace. Options — `slower`: The avatar speaks more slowly — easier to follow for non-native speakers. | `normal`: Default speaking pace. | `faster`: The avatar speaks more quickly for a snappier conversation.."
    },
    "result_enable_edit_transcript": {
      "type": [
        "boolean",
        "null"
      ],
      "example": true,
      "description": "Allow editing the transcript on the result view. Defaults to true."
    },
    "instructional_video_custom_text": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom narration text for the instructional video."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "name",
    "location",
    "interview_template_id",
    "mojito_language_code",
    "description",
    "status",
    "type",
    "visibility",
    "questions"
  ],
  "properties": {
    "code": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional external code/reference."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Project manager",
      "minLength": 1,
      "description": "Interview/position name."
    },
    "tags": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "example": [
        "interview-practice",
        "sales"
      ],
      "description": "Free-form tags stored on the interview. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed."
    },
    "type": {
      "enum": [
        "interview",
        "coaching",
        "assessment",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "interview",
      "description": "Product type of the interview. Options — `interview`: Standard candidate interview for a role — answers are AI-scored and produce a hiring recommendation. | `coaching`: Practice/coaching session — candidate-facing feedback to help them improve; not a hiring evaluation. Only available on the coaching portal, NOT the interview portal. | `assessment`: Skills/knowledge assessment — evaluates competencies and is scored like an interview.."
    },
    "status": {
      "enum": [
        "draft",
        "active",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "active",
      "description": "Lifecycle status of the interview. Options — `draft`: Created but not published — not visible to candidates and cannot be run yet. Use to stage an interview before going live. | `active`: Published and live — candidates can run it.."
    },
    "location": {
      "type": [
        "string",
        "null"
      ],
      "example": "remote",
      "minLength": 1,
      "description": "Job location — a city/country, or `remote`. Required and must not be empty: when the job description gives no location, pass `Not specified`."
    },
    "questions": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "required": [
          "question"
        ],
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identifier for this question. job-interview-get returns the question's real id here; send it back to job-interview-update so an unchanged question keeps its existing record (and with it its answer rules and any rendered avatar video). Also the handle another question references via conditional_question_main_id. On job-interview-create-from-array it is a caller-local value, only needed for those references."
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional label/tag stored on the question."
          },
          "duration": {
            "type": [
              "number",
              "null"
            ],
            "description": "Answer duration in seconds for this question."
          },
          "question": {
            "type": [
              "string",
              "null"
            ],
            "description": "The question text shown to the candidate."
          },
          "is_expert": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Expert listening question (view 'with listening expert')."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "External identifier stored on the question. job-interview-update matches on this first, so an ATS that owns stable ids can send its own array and have the diff line up without round-tripping our ids."
          },
          "external_data": {
            "type": [
              "object",
              "null"
            ],
            "description": "Arbitrary JSON metadata stored on the question.",
            "additionalProperties": {}
          },
          "is_conditional": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Conditional follow-up question (view 'with listening conditional'). Use with conditional_question_main_id."
          },
          "knowledge_base_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Knowledge-base store id (uuid) the question draws context from."
          },
          "is_multiple_choice": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Multiple-choice question (view 'multiple choice')."
          },
          "is_without_scoring": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Question is asked but not scored (view 'without scoring')."
          },
          "mojito_language_code": {
            "enum": [
              "ar",
              "bg",
              "zh",
              "hr",
              "cs",
              "da",
              "nl",
              "en",
              "fil",
              "fi",
              "fr",
              "de",
              "el",
              "hi",
              "hu",
              "id",
              "it",
              "ja",
              "ko",
              "ms",
              "no",
              "pl",
              "pt",
              "br",
              "ro",
              "ru",
              "sk",
              "es",
              "sv",
              "ta",
              "th",
              "tr",
              "uk",
              "vi",
              null
            ],
            "type": [
              "string",
              "null"
            ],
            "example": "en",
            "description": "Per-question language override (one of the platform-languages.json codes). Inherits the interview language when omitted."
          },
          "question_alternatives": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Alternative phrasings for the question."
          },
          "candidate_expectations_json": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "weak": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                },
                "description": "Baseline requirements every viable candidate should meet (table stakes)."
              },
              "strong": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                },
                "description": "High-bar requirements only standout candidates clear."
              },
              "moderate": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                },
                "description": "Requirements expected of a solid, competent candidate."
              }
            },
            "description": "Per-question candidate expectations, bucketed by requirement level (weak/moderate/strong). Extra keys are preserved."
          },
          "conditional_question_main_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "For a conditional question, the id (the \"id\" field above) of the parent question in this same array that triggers it. The parent must appear earlier in the array than the conditional question referencing it."
          },
          "is_candidate_asking_recruiter": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Candidate-asks-recruiter prompt (view 'candidate asking recruiter')."
          }
        },
        "additionalProperties": {}
      },
      "minItems": 1,
      "description": "Ordered list of interview questions to create as steps."
    },
    "recording": {
      "enum": [
        "audio_first_5_answers",
        "audio_all",
        "video_all",
        "video_first_5_answers",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "video_all",
      "description": "Cheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Video options also record the candidate. Omit/null to disable. Options — `audio_first_5_answers`: Audio-only cheating detection, first 5 answers only. | `audio_all`: Audio-only cheating detection on every answer. | `video_all`: Audio + video cheating detection on every answer (candidate is recorded for all answers). | `video_first_5_answers`: Audio + video cheating detection, first 5 answers only.."
    },
    "visibility": {
      "enum": [
        "merchant_public",
        "merchant_invite",
        "merchant_unlisted",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "merchant_public",
      "description": "Who can discover and access the interview. Options — `merchant_public`: Listed on the merchant's public interview list — anyone with the merchant link can find and start it. | `merchant_invite`: Invite-only — only candidates explicitly invited (by email/link) can access it; not listed anywhere. | `merchant_unlisted`: Reachable only via a direct link — not listed anywhere; share the link manually.."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "example": "Project manager role",
      "minLength": 1,
      "description": "Short interview description."
    },
    "environment": {
      "enum": [
        "production",
        "uat",
        "development",
        "demo",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "production",
      "description": "Which of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. | `uat`: User-acceptance testing - an isolated environment for pre-release verification. | `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. | `demo`: Demonstrations and sales trials.."
    },
    "is_embedded": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Set true when the interview will be embedded as an iframe on an external page. Creates an embed key and returns embed_id/embed_signing_key, used to authenticate/sign the iframe embed."
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Target merchant id (admins / sub-merchant only)."
    },
    "result_view": {
      "enum": [
        "none",
        "minimal",
        "minimal_with_score",
        "advanced",
        "full",
        "full_expand_scores",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "full",
      "description": "Result screen shown to the candidate after finishing. With any value other than `none`, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Options — `none`: No results screen at all — the interview is submitted immediately when the candidate finishes (no feedback, intro video, transcript edit or manual submit step). | `minimal`: Minimal results layout, no score shown. | `minimal_with_score`: Minimal results layout including the overall score. | `advanced`: Advanced results layout with more detail. | `full`: Full results layout with all sections. | `full_expand_scores`: Full results with every score breakdown expanded.."
    },
    "max_followups": {
      "type": [
        "integer",
        "null"
      ],
      "example": 2,
      "maximum": 999,
      "minimum": 0,
      "description": "Maximum number of AI follow-up questions. 0 disables follow-ups; presets are 0-3 (none/low/normal/high) and custom values start at 4; null uses the template default (Normal)."
    },
    "custom_scoring": {
      "type": [
        "object",
        "null"
      ],
      "description": "Custom scoring overrides merged with defaults.",
      "additionalProperties": {}
    },
    "interview_tone": {
      "enum": [
        "relaxed",
        "simple",
        "professional",
        "persuasive",
        "exact",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "professional",
      "description": "Tone — configures the AI avatar's speaking style and the follow-up questions it generates; the base `questions` you supply are not affected. Case-insensitive; omit to default to relaxed. Options — `relaxed`: Friendly and conversational tone that helps candidates feel at ease. | `simple`: Plain language at CEFR A2 level — short sentences and simple words. | `professional`: Formal and business-like approach suitable for senior roles. | `persuasive`: Engaging style that encourages candidates to elaborate. | `exact`: Asks the questions exactly as provided, without rephrasing — for interviews built from your own questions (create_interview_from_questions) where the wording is a script.."
    },
    "interview_type": {
      "enum": [
        "pre-screening",
        "pre-screening-with-test-questions",
        "second-interview",
        "remote-freelancer-verification",
        "strength-based-interview",
        "potential-based-interview",
        "process-verification-from-knowledge-base",
        "knockout-screening",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "pre-screening-with-test-questions",
      "description": "Interview style — configures the AI avatar and the follow-up questions it generates during the interview. The base `questions` you supply are used as-is and are NOT affected by this setting. Options — `pre-screening`: Pre-screening — quick qualification check focusing on basic requirements and availability. | `pre-screening-with-test-questions`: Pre-screening with test questions — pre-screening plus practical questions to test relevant skills. | `second-interview`: Second round interview — deeper dive for candidates who passed initial screening. | `remote-freelancer-verification`: Remote worker verification — verify remote work capabilities and communication skills. | `strength-based-interview`: Strength-based interview — focus on what candidates enjoy and excel at to predict job satisfaction. | `potential-based-interview`: Potential-based interview — assess learning ability and growth potential rather than past experience. | `process-verification-from-knowledge-base`: Knowledge Base interview — generate questions from your knowledge base documents. | `knockout-screening`: Knock-out screening — a short (about 5 minute) check of the role's must-haves with closed questions; ends early, politely, when a must-have is clearly not met. On creation it defaults custom_scoring.early_stop to true (where the avatar supports early stop) and max_followups to 1 unless you send them.."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "cover_image_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cover image URL."
    },
    "seniority_level": {
      "enum": [
        "entry-level",
        "intermediate",
        "senior",
        "managerial",
        "director",
        "executive",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "senior",
      "description": "Target seniority level for the role; auto-detected from the job description when omitted. Options — `entry-level`: Early-career or graduate roles. | `intermediate`: Some experience required. | `senior`: Experienced professional. | `managerial`: Team or department lead. | `director`: Director-level responsibility. | `executive`: C-suite or executive role.."
    },
    "welcome_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom welcome message."
    },
    "description_long": {
      "type": [
        "string",
        "null"
      ],
      "description": "Long-form interview description. Rendered as Markdown on the candidate-facing position page, including chips, callouts, cards, columns and buttons — formatting guide: https://developer.jobmojito.com/cookbooks/format-content-with-markdown"
    },
    "interview_salary": {
      "type": [
        "string",
        "null"
      ],
      "example": "$80k - $100k",
      "description": "Salary range shown for the position."
    },
    "thank_you_message": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom thank-you message."
    },
    "additional_context": {
      "type": [
        "object",
        "null"
      ],
      "description": "Extra context forwarded to expectation generation.",
      "additionalProperties": {}
    },
    "hiring_for_company": {
      "type": [
        "object",
        "null"
      ],
      "example": {
        "name": "undisclosed"
      },
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ],
          "example": "Unimo Enterprises",
          "description": "End-employer name. Omit/null when hiring for yourself, 'undisclosed' for an unnamed external client, or the client's company name."
        },
        "sector": {
          "type": [
            "string",
            "null"
          ],
          "example": "Logistics and Supply Chain",
          "description": "Industry / sector of the end employer."
        },
        "location": {
          "type": [
            "string",
            "null"
          ],
          "example": "Sri Lanka",
          "description": "Primary location of the end employer."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "example": "Unimo Enterprises is a leading logistics and supply chain solutions provider.",
          "description": "Short description of the end employer, used as background context by the agent."
        },
        "company_size": {
          "type": [
            "string",
            "null"
          ],
          "example": "100-200",
          "description": "Approximate headcount of the end employer."
        }
      },
      "description": "Who the position is really for. Omit/null (or an object with name null/blank) when hiring for yourself; { name: 'undisclosed' } for an unnamed external client; or { name: '<company>' } plus optional description/location/sector/company_size for a named client. Stored in creation_parameters.hiring_for_company."
    },
    "interview_attempts": {
      "type": [
        "number",
        "null"
      ],
      "example": 1,
      "description": "Allowed attempts, 1-20."
    },
    "instructional_video": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Enable an instructional video before approval."
    },
    "interview_department": {
      "type": [
        "string",
        "null"
      ],
      "example": "Engineering",
      "description": "Department the position belongs to."
    },
    "mojito_language_code": {
      "enum": [
        "ar",
        "bg",
        "zh",
        "hr",
        "cs",
        "da",
        "nl",
        "en",
        "fil",
        "fi",
        "fr",
        "de",
        "el",
        "hi",
        "hu",
        "id",
        "it",
        "ja",
        "ko",
        "ms",
        "no",
        "pl",
        "pt",
        "br",
        "ro",
        "ru",
        "sk",
        "es",
        "sv",
        "ta",
        "th",
        "tr",
        "uk",
        "vi",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "en",
      "description": "Platform language code (one of the platform-languages.json codes); must also resolve to a supported language with an Azure speech mapping."
    },
    "recruiter_profile_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant."
    },
    "disable_deduplication": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "When true, skip step deduplication on insert."
    },
    "interview_template_id": {
      "type": [
        "string",
        "null"
      ],
      "example": "46b98d37-1557-4391-beca-03037ead19f2",
      "minLength": 1,
      "description": "Id of the interview template to use. Must reference an existing interview_templates row."
    },
    "candidate_expectations": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-text candidate expectations."
    },
    "pdf_export_auto_config": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "files": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include uploaded candidate files."
        },
        "template": {
          "enum": [
            "classic",
            "modern",
            "one_pager",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "description": "Report layout: classic, modern, or one_pager. Omit for the merchant default (modern when unset)."
        },
        "analytics": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include analytics."
        },
        "transcript": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the interview transcript."
        },
        "contact_details": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include candidate contact details."
        },
        "answer_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include per-answer recordings."
        },
        "ai_scoring_rubric": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the AI scoring rubric."
        },
        "group_by_question": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Group transcript answers by expected question."
        },
        "session_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the full-session recording."
        },
        "mojito_language_code": {
          "enum": [
            "ar",
            "bg",
            "zh",
            "hr",
            "cs",
            "da",
            "nl",
            "en",
            "fil",
            "fi",
            "fr",
            "de",
            "el",
            "hi",
            "hu",
            "id",
            "it",
            "ja",
            "ko",
            "ms",
            "no",
            "pl",
            "pt",
            "br",
            "ro",
            "ru",
            "sk",
            "es",
            "sv",
            "ta",
            "th",
            "tr",
            "uk",
            "vi",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "example": "en",
          "description": "Report language code (a platform-languages.json code)."
        },
        "ai_recruiter_assessment": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the AI recruiter assessment."
        }
      },
      "description": "Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export."
    },
    "recording_full_session": {
      "enum": [
        "audio_all",
        "video_all",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "video_all",
      "description": "Full interview-session recording (includes the avatar and voice) produced as a single file. Independent of `recording`. Omit/null to disable. Options — `audio_all`: Record the whole session audio (avatar + candidate voice) into a single file. Adds +0.2 credits. | `video_all`: Record the whole session video + audio (avatar + candidate) into a single file. Adds +0.4 credits.."
    },
    "required_pronunciation": {
      "type": [
        "boolean",
        "null"
      ],
      "example": false,
      "description": "Require pronunciation assessment (restricts to pronunciation-capable languages). Defaults to false."
    },
    "knowledge_base_store_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional knowledge base store id; validated for existence."
    },
    "questions_random_subset": {
      "type": [
        "number",
        "null"
      ],
      "description": "Fraction of questions to randomly ask, between 0.01 and 0.9."
    },
    "interview_available_till": {
      "type": [
        "string",
        "null"
      ],
      "example": "2026-12-31",
      "description": "ISO date/time after which the interview is no longer available to candidates. null keeps it always available."
    },
    "candidate_expectations_json": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "weak": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "Baseline requirements every viable candidate should meet (table stakes)."
        },
        "strong": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "High-bar requirements only standout candidates clear."
        },
        "moderate": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "Requirements expected of a solid, competent candidate."
        }
      },
      "description": "Pre-generated candidate expectations, bucketed by requirement level (weak/moderate/strong); auto-generated when omitted for type=interview. Extra keys are preserved."
    },
    "candidate_video_introduction": {
      "enum": [
        "optional",
        "required",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "description": "Whether a candidate video introduction is optional or required."
    },
    "interview_conversation_speed": {
      "enum": [
        "slower",
        "normal",
        "faster",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "normal",
      "description": "Conversation pace of the AI avatar. Omit/null keeps the template default pace. Options — `slower`: The avatar speaks more slowly — easier to follow for non-native speakers. | `normal`: Default speaking pace. | `faster`: The avatar speaks more quickly for a snappier conversation.."
    },
    "result_enable_edit_transcript": {
      "type": [
        "boolean",
        "null"
      ],
      "example": true,
      "description": "Allow editing the transcript on the result view. Defaults to true."
    },
    "instructional_video_custom_text": {
      "type": [
        "string",
        "null"
      ],
      "description": "Custom text for the instructional video."
    }
  }
}

Argument	Type	Description
code	string \| null	Optional external code/reference for the persona.
name*	string \| null	Persona / session name.
tags	array \| null	Free-form tags stored on the persona. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed.
portal	string \| null	REQUIRED IN PRACTICE — pick deliberately; the default is the coaching product, not the recruiting one. `interview`: an interview role-play. Choose this for ANY recruiting or assessment use case (screening candidates, hiring, sales role-plays for applicants). Candidates are invited through the normal invitation flow, results are visible to the recruiter alongside ordinary interview results, it is billed against your merchant credits on the same basis as an interview, and attempts are capped (see `interview_attempts`). \| `coaching` (DEFAULT when omitted): the classic coaching persona for practice/training. Runs on the coaching portal, is consumed against the mentee's own coaching credits, is started by the mentee from the catalogue or a shared link, and its results are NOT visible to recruiters. The conversation itself behaves identically in both cases — only the portal, billing, visibility and attempt limits differ.
status*	string \| null	Lifecycle status of the interview. Options — `draft`: Created but not published — not visible to candidates and cannot be run yet. Use to stage an interview before going live. \| `active`: Published and live — candidates can run it..
recording	string \| null	Cheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Video options also record the candidate. Omit/null to disable. Options — `audio_first_5_answers`: Audio-only cheating detection, first 5 answers only. \| `audio_all`: Audio-only cheating detection on every answer. \| `video_all`: Audio + video cheating detection on every answer (candidate is recorded for all answers). \| `video_first_5_answers`: Audio + video cheating detection, first 5 answers only..
visibility*	string \| null	Who can discover and access the interview. Options — `merchant_public`: Listed on the merchant's public interview list — anyone with the merchant link can find and start it. \| `merchant_invite`: Invite-only — only candidates explicitly invited (by email/link) can access it; not listed anywhere. \| `merchant_unlisted`: Reachable only via a direct link — not listed anywhere; share the link manually..
description	string \| null	Short persona description shown to the candidate on the pre-session poster. Candidate-visible — keep it to max 2 sentences. Unlike job-interview-create, personas run no AI generation, so this is never auto-generated: leave it null/blank and the poster simply shows no description; set it to frame the scene.
environment	string \| null	Which of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. \| `uat`: User-acceptance testing - an isolated environment for pre-release verification. \| `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. \| `demo`: Demonstrations and sales trials..
is_embedded	boolean \| null	Set true when the persona will be embedded as an iframe on an external page. Provisions an embed key and returns embed_id / embed_signing_key, used to sign the iframe link. Where it runs depends on the type: interviews, assessments and interview role-plays embed on the interview portal (`https://<interview portal domain>/embed?embed_id=...`); coaching sessions and coaching personas embed on the consumer (coaching) portal (`https://<coaching portal domain>/embed?embed_id=...`, a link built on the interview portal is forwarded there). A signed coaching embed (name, email, signature) signs the visitor in as a learner of that portal, and the session is charged to the merchant's interview credits on completion, not to the learner's coaching credits; it cannot start while the merchant has none.
merchant_id	string \| null	Merchant id. Admin / sub-merchant callers only; otherwise taken from your token.
result_view	string \| null	Result screen shown to the candidate after finishing. With any value other than `none`, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Options — `none`: No results screen at all — the interview is submitted immediately when the candidate finishes (no feedback, intro video, transcript edit or manual submit step). \| `minimal`: Minimal results layout, no score shown. \| `minimal_with_score`: Minimal results layout including the overall score. \| `advanced`: Advanced results layout with more detail. \| `full`: Full results layout with all sections. \| `full_expand_scores`: Full results with every score breakdown expanded..
max_duration	number \| null	Maximum conversation duration in seconds. Defaults to 1200 (20 min) when omitted.
opening_line	string \| null	The avatar's opening line — the FIRST thing it says out loud when the session starts, before the candidate has said anything. This is a literal spoken line, NOT a description: write the exact words the avatar should say, in character and consistent with persona_role_avatar. For an escalated scenario it should already convey that state (e.g. an angry customer opens angrily). If omitted, the platform inserts a generic default ("Hello"), which is usually a weak opener — set this for anything other than a neutral greeting.
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
cover_image_url	string \| null	Cover image URL.
welcome_message	string \| null	Custom welcome message spoken to the candidate before the role-play starts — set it; omitting it leaves a generic platform default. This is the scene-setting message; the avatar's first in-character line is `opening_line`, which comes after it.
persona_role_user*	string \| null	The role the candidate (mentee) plays. Candidate-visible — shown on the pre-session poster as 'Your role', so write it as candidate-facing setup and keep it to max 2 sentences. Example: 'is to be a sales person trying to sell an additional product to the customer'.
thank_you_message	string \| null	Custom thank-you message shown after the session — set it; omitting it leaves a generic platform default.
interview_attempts	number \| null	Allowed candidate attempts (1-20), defaulting to 3. Only meaningful when `portal` is `interview`; coaching personas are unlimited. A recruiter can still grant an extra attempt afterwards.
interview_location	string \| null	Optional location label shown for the session.
persona_role_avatar*	string \| null	The role the AI avatar plays. Candidate-visible — shown on the pre-session poster as 'Role of the agent', so write it as candidate-facing setup and keep it to max 2 sentences. Example: 'is to act as a happy customer responding to questions'.
mojito_language_code*	string \| null	Platform language code used for the conversation. Must be one of the platform-languages.json codes.
recruiter_profile_id	string \| null	Profile id of the recruiter owning this persona. Must be a merchant/merchant_owner/admin profile of the same merchant.
interview_template_id*	string \| null	Id of the interview template (avatar) the persona uses.
persona_avatar_who_is	string \| null	Who the avatar represents: name, role, context, personality, woven with what drives them underneath (motive, fear, what they refuse until heard, what they do not know until told). One continuous description; no labelled subsections.
candidate_expectations	string \| null	Mentee assessment goals — free-text describing what the candidate is expected to achieve (max 2100 chars).
recording_full_session	string \| null	Full interview-session recording (includes the avatar and voice) produced as a single file. Independent of `recording`. Omit/null to disable. Options — `audio_all`: Record the whole session audio (avatar + candidate voice) into a single file. Adds +0.2 credits. \| `video_all`: Record the whole session video + audio (avatar + candidate) into a single file. Adds +0.4 credits..
persona_avatar_progress	string \| null	How the conversation moves forward — one plain-text value starting with `Mode: turning point` (resistance) or `Mode: steps` (difficult conversation protocol), then the labelled lines for that mode (Initial hold / Unlocks when / … or Framework / Steps / …), including a Gates line: do not share later personal details from persona_avatar_knowledge until progress is earned.
persona_avatar_knowledge	string \| null	Private facts the avatar can use (numbers, dates, names, objections), plus any personal details shareable only after progress and only if natural — timing written inline, not as labelled subsections. Those personal details are never required for the goal.
candidate_video_introduction	string \| null	Whether a candidate video introduction is optional or required.
interview_conversation_speed	string \| null	Conversation pace of the AI avatar. Omit/null keeps the template default pace. Options — `slower`: The avatar speaks more slowly — easier to follow for non-native speakers. \| `normal`: Default speaking pace. \| `faster`: The avatar speaks more quickly for a snappier conversation..
persona_avatar_end_conditions	string \| null	When the avatar should end the session. Prefer referring to persona_avatar_progress: wrap up when progress is complete (turning point unlocked and a plan accepted, or steps "Done when" reached), or when the conversation has clearly broken down.

Input schema (JSON)

{
  "type": "object",
  "required": [
    "name",
    "interview_template_id",
    "mojito_language_code",
    "status",
    "visibility",
    "persona_role_avatar",
    "persona_role_user"
  ],
  "properties": {
    "code": {
      "type": [
        "string",
        "null"
      ],
      "example": "my code",
      "description": "Optional external code/reference for the persona."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Difficult customer role-play",
      "minLength": 1,
      "description": "Persona / session name."
    },
    "tags": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "example": [
        "interview-practice",
        "sales"
      ],
      "description": "Free-form tags stored on the persona. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed."
    },
    "portal": {
      "enum": [
        "coaching",
        "interview",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "interview",
      "description": "REQUIRED IN PRACTICE — pick deliberately; the default is the coaching product, not the recruiting one. `interview`: an interview role-play. Choose this for ANY recruiting or assessment use case (screening candidates, hiring, sales role-plays for applicants). Candidates are invited through the normal invitation flow, results are visible to the recruiter alongside ordinary interview results, it is billed against your merchant credits on the same basis as an interview, and attempts are capped (see `interview_attempts`). | `coaching` (DEFAULT when omitted): the classic coaching persona for practice/training. Runs on the coaching portal, is consumed against the mentee's own coaching credits, is started by the mentee from the catalogue or a shared link, and its results are NOT visible to recruiters. The conversation itself behaves identically in both cases — only the portal, billing, visibility and attempt limits differ."
    },
    "status": {
      "enum": [
        "draft",
        "active",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "active",
      "description": "Lifecycle status of the interview. Options — `draft`: Created but not published — not visible to candidates and cannot be run yet. Use to stage an interview before going live. | `active`: Published and live — candidates can run it.."
    },
    "recording": {
      "enum": [
        "audio_first_5_answers",
        "audio_all",
        "video_all",
        "video_first_5_answers",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "video_all",
      "description": "Cheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Video options also record the candidate. Omit/null to disable. Options — `audio_first_5_answers`: Audio-only cheating detection, first 5 answers only. | `audio_all`: Audio-only cheating detection on every answer. | `video_all`: Audio + video cheating detection on every answer (candidate is recorded for all answers). | `video_first_5_answers`: Audio + video cheating detection, first 5 answers only.."
    },
    "visibility": {
      "enum": [
        "merchant_public",
        "merchant_invite",
        "merchant_unlisted",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "merchant_public",
      "description": "Who can discover and access the interview. Options — `merchant_public`: Listed on the merchant's public interview list — anyone with the merchant link can find and start it. | `merchant_invite`: Invite-only — only candidates explicitly invited (by email/link) can access it; not listed anywhere. | `merchant_unlisted`: Reachable only via a direct link — not listed anywhere; share the link manually.."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "example": "A quick sales role-play with an unhappy customer. Your goal is to resolve their complaint and keep the account.",
      "description": "Short persona description shown to the candidate on the pre-session poster. Candidate-visible — keep it to max 2 sentences. Unlike job-interview-create, personas run no AI generation, so this is never auto-generated: leave it null/blank and the poster simply shows no description; set it to frame the scene."
    },
    "environment": {
      "enum": [
        "production",
        "uat",
        "development",
        "demo",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "production",
      "description": "Which of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. | `uat`: User-acceptance testing - an isolated environment for pre-release verification. | `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. | `demo`: Demonstrations and sales trials.."
    },
    "is_embedded": {
      "type": [
        "boolean",
        "null"
      ],
      "example": false,
      "description": "Set true when the persona will be embedded as an iframe on an external page. Provisions an embed key and returns embed_id / embed_signing_key, used to sign the iframe link. Where it runs depends on the type: interviews, assessments and interview role-plays embed on the interview portal (`https://<interview portal domain>/embed?embed_id=...`); coaching sessions and coaching personas embed on the consumer (coaching) portal (`https://<coaching portal domain>/embed?embed_id=...`, a link built on the interview portal is forwarded there). A signed coaching embed (name, email, signature) signs the visitor in as a learner of that portal, and the session is charged to the merchant's interview credits on completion, not to the learner's coaching credits; it cannot start while the merchant has none."
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Merchant id. Admin / sub-merchant callers only; otherwise taken from your token."
    },
    "result_view": {
      "enum": [
        "none",
        "minimal",
        "minimal_with_score",
        "advanced",
        "full",
        "full_expand_scores",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "full",
      "description": "Result screen shown to the candidate after finishing. With any value other than `none`, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Options — `none`: No results screen at all — the interview is submitted immediately when the candidate finishes (no feedback, intro video, transcript edit or manual submit step). | `minimal`: Minimal results layout, no score shown. | `minimal_with_score`: Minimal results layout including the overall score. | `advanced`: Advanced results layout with more detail. | `full`: Full results layout with all sections. | `full_expand_scores`: Full results with every score breakdown expanded.."
    },
    "max_duration": {
      "type": [
        "number",
        "null"
      ],
      "example": 1200,
      "description": "Maximum conversation duration in seconds. Defaults to 1200 (20 min) when omitted."
    },
    "opening_line": {
      "type": [
        "string",
        "null"
      ],
      "example": "Oh, finally — someone actually comes over! I've been waiting for ages. Are you going to help me or not?",
      "description": "The avatar's opening line — the FIRST thing it says out loud when the session starts, before the candidate has said anything. This is a literal spoken line, NOT a description: write the exact words the avatar should say, in character and consistent with persona_role_avatar. For an escalated scenario it should already convey that state (e.g. an angry customer opens angrily). If omitted, the platform inserts a generic default (\"Hello\"), which is usually a weak opener — set this for anything other than a neutral greeting."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "cover_image_url": {
      "type": [
        "string",
        "null"
      ],
      "example": "https://example.com/cover.png",
      "description": "Cover image URL."
    },
    "welcome_message": {
      "type": [
        "string",
        "null"
      ],
      "example": "Welcome! You are about to speak with a customer who is unhappy about a recent price increase.",
      "description": "Custom welcome message spoken to the candidate before the role-play starts — set it; omitting it leaves a generic platform default. This is the scene-setting message; the avatar's first in-character line is `opening_line`, which comes after it."
    },
    "persona_role_user": {
      "type": [
        "string",
        "null"
      ],
      "example": "is to be a sales person trying to sell an additional product to the customer",
      "minLength": 1,
      "description": "The role the candidate (mentee) plays. Candidate-visible — shown on the pre-session poster as 'Your role', so write it as candidate-facing setup and keep it to max 2 sentences. Example: 'is to be a sales person trying to sell an additional product to the customer'."
    },
    "thank_you_message": {
      "type": [
        "string",
        "null"
      ],
      "example": "Thanks — your role-play has been recorded and will be reviewed by the hiring team.",
      "description": "Custom thank-you message shown after the session — set it; omitting it leaves a generic platform default."
    },
    "interview_attempts": {
      "type": [
        "number",
        "null"
      ],
      "example": 3,
      "maximum": 20,
      "minimum": 1,
      "description": "Allowed candidate attempts (1-20), defaulting to 3. Only meaningful when `portal` is `interview`; coaching personas are unlimited. A recruiter can still grant an extra attempt afterwards."
    },
    "interview_location": {
      "type": [
        "string",
        "null"
      ],
      "example": "remote",
      "description": "Optional location label shown for the session."
    },
    "persona_role_avatar": {
      "type": [
        "string",
        "null"
      ],
      "example": "is to act as a happy customer responding to questions",
      "minLength": 1,
      "description": "The role the AI avatar plays. Candidate-visible — shown on the pre-session poster as 'Role of the agent', so write it as candidate-facing setup and keep it to max 2 sentences. Example: 'is to act as a happy customer responding to questions'."
    },
    "mojito_language_code": {
      "enum": [
        "ar",
        "bg",
        "zh",
        "hr",
        "cs",
        "da",
        "nl",
        "en",
        "fil",
        "fi",
        "fr",
        "de",
        "el",
        "hi",
        "hu",
        "id",
        "it",
        "ja",
        "ko",
        "ms",
        "no",
        "pl",
        "pt",
        "br",
        "ro",
        "ru",
        "sk",
        "es",
        "sv",
        "ta",
        "th",
        "tr",
        "uk",
        "vi",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "en",
      "description": "Platform language code used for the conversation. Must be one of the platform-languages.json codes."
    },
    "recruiter_profile_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Profile id of the recruiter owning this persona. Must be a merchant/merchant_owner/admin profile of the same merchant."
    },
    "interview_template_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "baa3bf7c-6926-46fd-9005-16738a31f72d",
      "minLength": 1,
      "description": "Id of the interview template (avatar) the persona uses."
    },
    "persona_avatar_who_is": {
      "type": [
        "string",
        "null"
      ],
      "description": "Who the avatar represents: name, role, context, personality, woven with what drives them underneath (motive, fear, what they refuse until heard, what they do not know until told). One continuous description; no labelled subsections."
    },
    "candidate_expectations": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 2100,
      "description": "Mentee assessment goals — free-text describing what the candidate is expected to achieve (max 2100 chars)."
    },
    "recording_full_session": {
      "enum": [
        "audio_all",
        "video_all",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "video_all",
      "description": "Full interview-session recording (includes the avatar and voice) produced as a single file. Independent of `recording`. Omit/null to disable. Options — `audio_all`: Record the whole session audio (avatar + candidate voice) into a single file. Adds +0.2 credits. | `video_all`: Record the whole session video + audio (avatar + candidate) into a single file. Adds +0.4 credits.."
    },
    "persona_avatar_progress": {
      "type": [
        "string",
        "null"
      ],
      "example": "Mode: turning point\nInitial hold: ...\nUnlocks when: ...\nAfter unlock: ...\nHard limits: ...\nNo goalposts: ...\nGates: ...",
      "description": "How the conversation moves forward — one plain-text value starting with `Mode: turning point` (resistance) or `Mode: steps` (difficult conversation protocol), then the labelled lines for that mode (Initial hold / Unlocks when / … or Framework / Steps / …), including a Gates line: do not share later personal details from persona_avatar_knowledge until progress is earned."
    },
    "persona_avatar_knowledge": {
      "type": [
        "string",
        "null"
      ],
      "description": "Private facts the avatar can use (numbers, dates, names, objections), plus any personal details shareable only after progress and only if natural — timing written inline, not as labelled subsections. Those personal details are never required for the goal."
    },
    "candidate_video_introduction": {
      "enum": [
        "optional",
        "required",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "optional",
      "description": "Whether a candidate video introduction is optional or required."
    },
    "interview_conversation_speed": {
      "enum": [
        "slower",
        "normal",
        "faster",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "normal",
      "description": "Conversation pace of the AI avatar. Omit/null keeps the template default pace. Options — `slower`: The avatar speaks more slowly — easier to follow for non-native speakers. | `normal`: Default speaking pace. | `faster`: The avatar speaks more quickly for a snappier conversation.."
    },
    "persona_avatar_end_conditions": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the avatar should end the session. Prefer referring to persona_avatar_progress: wrap up when progress is complete (turning point unlocked and a plan accepted, or steps \"Done when\" reached), or when the conversation has clearly broken down."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "export_type"
  ],
  "properties": {
    "template": {
      "allOf": [
        {
          "enum": [
            "classic",
            "modern",
            "one_pager"
          ],
          "type": "string",
          "example": "modern",
          "description": "Report layout for this export. Same values as the top-level `template`; the top-level field wins when both are given. Kept here so a saved auto-export configuration carries its template."
        },
        {
          "description": "Report layout: `classic`, `modern` or `one_pager`. Omit for the merchant default (modern when unset)."
        }
      ]
    },
    "store_file": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "When true (pdf only), persist the file to storage and return a signed URL."
    },
    "export_type": {
      "enum": [
        "pdf",
        "html",
        "json",
        null
      ],
      "type": [
        "string",
        "null"
      ]
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "interview_result_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "93c98d21-e04d-4a84-9afa-ed154cf73636"
    },
    "interview_result_ids": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "description": "Generate a single combined report for multiple results."
    },
    "export_features_result": {
      "type": "object",
      "properties": {
        "files": {
          "type": [
            "boolean",
            "null"
          ],
          "default": true,
          "description": "Include the candidate's uploaded files (resume and cover letter) as signed page URLs."
        },
        "template": {
          "enum": [
            "classic",
            "modern",
            "one_pager"
          ],
          "type": "string",
          "example": "modern",
          "description": "Report layout for this export. Same values as the top-level `template`; the top-level field wins when both are given. Kept here so a saved auto-export configuration carries its template."
        },
        "analytics": {
          "type": [
            "boolean",
            "null"
          ],
          "default": true,
          "description": "Include speech analytics for each answer (speech accuracy, fluency, recognition confidence, sentiment, cadence / words-per-minute)."
        },
        "transcript": {
          "type": [
            "boolean",
            "null"
          ],
          "default": true,
          "description": "Include the full interview transcript: each question, the candidate answer, and the per-answer AI analysis."
        },
        "contact_details": {
          "type": [
            "boolean",
            "null"
          ],
          "default": true,
          "description": "Include the candidate's contact details (email, LinkedIn, phone number, physical address)."
        },
        "answer_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "default": false,
          "description": "Include a signed recording URL (audio/video) for each individual answer."
        },
        "ai_scoring_rubric": {
          "type": [
            "boolean",
            "null"
          ],
          "default": false,
          "description": "Include the AI scoring rubric — the candidate-expectation buckets (strong / moderate / weak). Only takes effect when ai_recruiter_assessment is also true."
        },
        "group_by_question": {
          "type": [
            "boolean",
            "null"
          ],
          "default": false,
          "description": "Group answers under their expected questions (instead of chronological order), including questions that were not reached."
        },
        "session_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "default": false,
          "description": "Include the full interview session recording and the video introduction as signed URLs."
        },
        "mojito_language_code": {
          "enum": [
            "ar",
            "bg",
            "zh",
            "hr",
            "cs",
            "da",
            "nl",
            "en",
            "fil",
            "fi",
            "fr",
            "de",
            "el",
            "hi",
            "hu",
            "id",
            "it",
            "ja",
            "ko",
            "ms",
            "no",
            "pl",
            "pt",
            "br",
            "ro",
            "ru",
            "sk",
            "es",
            "sv",
            "ta",
            "th",
            "tr",
            "uk",
            "vi",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "example": "en",
          "description": "Report language. Optional: if omitted, the report uses each result's own language code. If provided and it differs from the result's language, the report content is translated, which costs 0.1 credit per result."
        },
        "ai_recruiter_assessment": {
          "type": [
            "boolean",
            "null"
          ],
          "default": true,
          "description": "Include the AI recruiter assessment: resume analysis, overall AI analysis, and the why-hire / why-not-hire summaries."
        }
      }
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "interview_result_id"
  ],
  "properties": {
    "view": {
      "enum": [
        "summary",
        "standard",
        "full"
      ],
      "type": "string",
      "default": "standard",
      "description": "How much of the record to return. Handled by the MCP server, not the JobMojito API — it only narrows the response, never the query.\n\n- `summary`: scores, the overall AI analysis, and each question with the candidate's answer — no per-answer AI commentary, recording paths or raw assessment data. Use this to review or compare candidates.\n- `standard`: everything a human reviewer reads: the full transcript with per-answer analysis, scores and recordings, minus the raw machine assessment blobs. This is the default.\n- `full`: every field, including the per-answer raw assessment data — condensed: pronunciation and sentiment scores per recognised segment with the lowest-scoring words, reading/gaze statistics, STT reliability, proctor status and seconds per detected speaker. Word-, character- and frame-level arrays are left out (listed in `_omitted`). Only ask for this if you need those assessment details."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "interview_result_id": {
      "type": "string",
      "format": "uuid",
      "example": "93c98d21-e04d-4a84-9afa-ed154cf73636",
      "minLength": 1,
      "description": "The interview result to fetch the transcript and details for."
    },
    "get_signed_recordings": {
      "enum": [
        "true",
        "false"
      ],
      "type": "string",
      "default": "false",
      "example": "false",
      "description": "When true, includes short-lived signed recording URLs for the session, the video introduction, and each transcript answer."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "date_from",
    "date_to"
  ],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 50,
      "example": 50,
      "maximum": 1000,
      "minimum": 1,
      "description": "Maximum number of records to return (1–1000)."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "example": 0,
      "minimum": 0,
      "description": "Number of records to skip from the start of the result set."
    },
    "date_to": {
      "type": "string",
      "example": "2026-01-01",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "End of the date range (inclusive), YYYY-MM-DD."
    },
    "date_from": {
      "type": "string",
      "example": "2026-01-01",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Start of the date range (inclusive), YYYY-MM-DD."
    },
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "interview_id": {
      "type": "string",
      "format": "uuid",
      "description": "Optional interview (interview_def_set) or position (position_def_set) id to drill the event counts down. The type is detected automatically: a position aggregates the daily counts across every interview that makes up the position; an interview filters to that single definition."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "type": {
      "enum": [
        "interactive_heygen",
        "interactive_elevenlabs",
        "interactive_spatius",
        "offline_heygen",
        "offline_elai",
        "offline_synthesia"
      ],
      "type": "string",
      "example": "interactive_heygen",
      "description": "Filter by avatar template type. Omit for all."
    },
    "limit": {
      "type": "integer",
      "default": 15,
      "example": 50,
      "maximum": 1000,
      "minimum": 1,
      "description": "Maximum number of records to return (1–1000)."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "example": 0,
      "minimum": 0,
      "description": "Number of records to skip from the start of the result set."
    },
    "status": {
      "enum": [
        "active",
        "draft",
        "archived",
        "deleted"
      ],
      "type": "string",
      "example": "active",
      "description": "Filter by status. Omit for all except archived (see include_archived)."
    },
    "filter_text": {
      "type": "string",
      "description": "Case-insensitive search on template name or voice language name."
    },
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "include_public": {
      "enum": [
        "true",
        "false"
      ],
      "type": "string",
      "default": "false",
      "example": "false",
      "description": "Also include public templates shared across merchants, in addition to this merchant's own."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "include_archived": {
      "enum": [
        "true",
        "false"
      ],
      "type": "string",
      "default": "false",
      "example": "false",
      "description": "Include archived templates (excluded by default)."
    },
    "mojito_language_code": {
      "enum": [
        "ar",
        "bg",
        "zh",
        "hr",
        "cs",
        "da",
        "nl",
        "en",
        "fil",
        "fi",
        "fr",
        "de",
        "el",
        "hi",
        "hu",
        "id",
        "it",
        "ja",
        "ko",
        "ms",
        "no",
        "pl",
        "pt",
        "br",
        "ro",
        "ru",
        "sk",
        "es",
        "sv",
        "ta",
        "th",
        "tr",
        "uk",
        "vi"
      ],
      "type": "string",
      "example": "en",
      "description": "Filter by platform language code. Omit for all languages."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "tab": {
      "enum": [
        "interview",
        "pre-screening",
        "no-action",
        "leads",
        ""
      ],
      "type": "string",
      "example": "interview",
      "description": "Filter candidates by recent activity. Omit (or empty) to include all."
    },
    "limit": {
      "type": "integer",
      "default": 50,
      "example": 50,
      "maximum": 1000,
      "minimum": 1,
      "description": "Maximum number of records to return (1–1000)."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "example": 0,
      "minimum": 0,
      "description": "Number of records to skip from the start of the result set."
    },
    "source": {
      "enum": [
        "invited",
        "registered"
      ],
      "type": "string",
      "example": "registered",
      "description": "Filter by how the candidate entered: invited or self-registered. Omit for both."
    },
    "order_by": {
      "enum": [
        "name_accending",
        "name_decending",
        "created_at_newest",
        "created_at_oldest"
      ],
      "type": "string",
      "default": "created_at_newest",
      "example": "created_at_newest",
      "description": "Sort order of the result set."
    },
    "filter_text": {
      "type": "string",
      "description": "Search on candidate name, email, external id, phone and CV skills. Every word must match (case and accents ignored; longer words tolerate typos). Without order_by, the best matches come first."
    },
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "filter_emoji": {
      "type": "string",
      "description": "Filter by the candidate emoji marker."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "limit": {
      "type": "integer",
      "default": 25,
      "example": 50,
      "maximum": 1000,
      "minimum": 1,
      "description": "Maximum number of records to return (1–1000)."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "example": 0,
      "minimum": 0,
      "description": "Number of records to skip from the start of the result set."
    },
    "status": {
      "enum": [
        "draft",
        "active",
        "archived"
      ],
      "type": "string",
      "example": "active",
      "description": "Filter by lifecycle status. Omit to include every status you can see (deleted directories are never returned)."
    },
    "parent_tag": {
      "type": "string",
      "description": "Return only the directories nested directly under this one (its `tags_sub`), in the parent's own order. Combine with the other filters to narrow further."
    },
    "visibility": {
      "enum": [
        "public",
        "merchant_public",
        "merchant_invite",
        "merchant_unlisted"
      ],
      "type": "string",
      "example": "merchant_public",
      "description": "Filter by visibility."
    },
    "filter_text": {
      "type": "string",
      "description": "Case-insensitive search on the directory id, name and description."
    },
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "include_public": {
      "enum": [
        "true",
        "false"
      ],
      "type": "string",
      "default": "true",
      "example": "true",
      "description": "Include the platform-wide `public` directories shared across merchants."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "mojito_language_code": {
      "enum": [
        "ar",
        "bg",
        "zh",
        "hr",
        "cs",
        "da",
        "nl",
        "en",
        "fil",
        "fi",
        "fr",
        "de",
        "el",
        "hi",
        "hu",
        "id",
        "it",
        "ja",
        "ko",
        "ms",
        "no",
        "pl",
        "pt",
        "br",
        "ro",
        "ru",
        "sk",
        "es",
        "sv",
        "ta",
        "th",
        "tr",
        "uk",
        "vi"
      ],
      "type": "string",
      "example": "en",
      "description": "Filter by language: directories whose default language or one of whose language versions is this one. Omit for all languages."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "tab": {
      "enum": [
        "decided-rejected",
        "undecided",
        "shortlist",
        "decided-selected",
        "completed",
        "incomplete",
        "archived-interview",
        "public_avatar",
        "archived-public_avatar",
        ""
      ],
      "type": "string",
      "example": "undecided",
      "description": "Filter by decision/completion state. Omit (or empty) to include all."
    },
    "step": {
      "enum": [
        "pre-screening",
        "interview",
        "meeting"
      ],
      "type": "string",
      "example": "interview",
      "description": "Filter by pipeline step type (pre-screening, interview or meeting). Omit for all."
    },
    "type": {
      "enum": [
        "interview",
        "coaching",
        "assessment",
        "public_avatar",
        "persona",
        "persona_interview"
      ],
      "type": "string",
      "default": "interview",
      "example": "interview",
      "description": "Product type of results to list."
    },
    "limit": {
      "type": "integer",
      "default": 20,
      "example": 50,
      "maximum": 1000,
      "minimum": 1,
      "description": "Maximum number of records to return (1–1000)."
    },
    "risks": {
      "type": "string",
      "description": "Comma-separated list of recruiter-risk keys to filter by (matches any)."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "example": 0,
      "minimum": 0,
      "description": "Number of records to skip from the start of the result set."
    },
    "order_by": {
      "enum": [
        "score",
        "created_at_newest",
        "created_at_oldest",
        "updated_at_newest"
      ],
      "type": "string",
      "default": "created_at_newest",
      "example": "created_at_newest",
      "description": "Sort order of the result set."
    },
    "filter_text": {
      "type": "string",
      "description": "Case-insensitive search on candidate name or email."
    },
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "filter_emoji": {
      "type": "string",
      "description": "Filter by the candidate emoji marker."
    },
    "interview_id": {
      "type": "string",
      "format": "uuid",
      "description": "Filter to a single interview definition id."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "profile_interview_id": {
      "type": "string",
      "format": "uuid",
      "description": "Filter to a single candidate (profile_interview) id."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [],
  "properties": {
    "type": {
      "enum": [
        "interview",
        "coaching",
        "assessment",
        "public_avatar",
        "persona",
        "persona_interview"
      ],
      "type": "string",
      "default": "interview",
      "example": "interview",
      "description": "Product type of interviews to list."
    },
    "limit": {
      "type": "integer",
      "default": 50,
      "example": 50,
      "maximum": 1000,
      "minimum": 1,
      "description": "Maximum number of records to return (1–1000)."
    },
    "offset": {
      "type": "integer",
      "default": 0,
      "example": 0,
      "minimum": 0,
      "description": "Number of records to skip from the start of the result set."
    },
    "status": {
      "enum": [
        "draft",
        "active",
        "archived",
        "deleted",
        "preparing",
        "completed"
      ],
      "type": "string",
      "example": "active",
      "description": "Filter by lifecycle status. Omit to include all statuses."
    },
    "show_demo": {
      "enum": [
        "true",
        "false"
      ],
      "type": "string",
      "default": "false",
      "example": "false",
      "description": "Include demo/sample interviews."
    },
    "filter_text": {
      "type": "string",
      "description": "Case-insensitive search on the interview name."
    },
    "merchant_id": {
      "type": "string",
      "format": "uuid",
      "example": "28106cba-1c27-4e53-b149-32113e5e8e31",
      "description": "Optional merchant to scope to. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "show_public": {
      "enum": [
        "true",
        "false"
      ],
      "type": "string",
      "default": "false",
      "example": "false",
      "description": "Include interviews shared publicly across merchants (coaching/avatars)."
    },
    "filter_emoji": {
      "type": "string",
      "description": "Filter by the interview emoji marker."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

{
  "type": "object",
  "required": [
    "definition"
  ],
  "properties": {
    "filters": {
      "allOf": [
        {
          "type": "object",
          "properties": {
            "period": {
              "anyOf": [
                {
                  "type": "object",
                  "required": [
                    "preset"
                  ],
                  "properties": {
                    "preset": {
                      "enum": [
                        "last_7_days",
                        "last_30_days",
                        "last_90_days",
                        "this_month",
                        "last_month",
                        "this_quarter",
                        "last_quarter",
                        "this_year",
                        "last_year",
                        "all_time",
                        null
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "required": [
                    "from",
                    "to"
                  ],
                  "properties": {
                    "to": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                    },
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                    }
                  },
                  "additionalProperties": false
                }
              ],
              "example": {
                "preset": "last_30_days"
              },
              "description": "Either a preset, or from and to dates (YYYY-MM-DD, both inclusive, UTC). Default: last_30_days."
            },
            "include_test": {
              "type": [
                "boolean",
                "null"
              ],
              "description": "Include test runs. Default false."
            },
            "position_ids": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "maxItems": 200,
              "description": "Positions to show (position ids from list_interviews). position_ids, interview_ids and without_position are one pick list: a row shows when it belongs to ANY pick. Nothing picked = all."
            },
            "interview_ids": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "maxItems": 200,
              "description": "Interviews to show (interview ids from list_interviews), combined with the other picks by OR. Nothing picked = all."
            },
            "without_position": {
              "type": [
                "boolean",
                "null"
              ],
              "description": "Also pick interviews that are not part of any position (stand-alone interviews, and coaching sessions). Combined with the other picks by OR."
            }
          },
          "description": "Filters for every block of the report. Each viewer can override them for themselves.",
          "additionalProperties": false
        },
        {
          "description": "Applied on top of definition.filters."
        }
      ]
    },
    "block_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Run only this block."
    },
    "definition": {
      "type": "object",
      "example": {
        "title": "Weekly hiring pulse",
        "blocks": [
          {
            "id": "headline",
            "type": "kpi",
            "compare": "previous_period",
            "dataset": "interview_results",
            "measures": [
              "completed",
              "avg_score",
              "shortlisted"
            ]
          },
          {
            "id": "trend",
            "type": "line",
            "title": "Completed per week",
            "width": 8,
            "dataset": "interview_results",
            "measures": [
              "completed"
            ],
            "dimensions": [
              {
                "field": "date",
                "grain": "week"
              }
            ]
          },
          {
            "id": "by_position",
            "sort": [
              {
                "dir": "desc",
                "field": "completed"
              }
            ],
            "type": "table",
            "limit": 25,
            "title": "By position",
            "dataset": "interview_results",
            "measures": [
              "completed",
              "avg_score",
              "shortlisted"
            ],
            "dimensions": [
              "position"
            ]
          }
        ],
        "schema": "jobmojito.report/v1",
        "filters": {
          "period": {
            "preset": "last_30_days"
          }
        }
      },
      "required": [
        "schema",
        "title",
        "blocks"
      ],
      "properties": {
        "title": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 120,
          "minLength": 1
        },
        "blocks": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "required": [
              "id",
              "type"
            ],
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "by_position",
                "pattern": "^[A-Za-z0-9_-]{1,40}$"
              },
              "sort": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "required": [
                    "field"
                  ],
                  "properties": {
                    "dir": {
                      "enum": [
                        "asc",
                        "desc",
                        null
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "field": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^[a-z][a-z0-9_]{0,40}$",
                      "description": "A dimension or measure the block selects."
                    }
                  },
                  "additionalProperties": false
                },
                "maxItems": 3
              },
              "text": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 4000,
                "description": "Text block only: the note (plain text, line breaks kept)."
              },
              "type": {
                "enum": [
                  "kpi",
                  "table",
                  "bar",
                  "stacked_bar",
                  "line",
                  "funnel",
                  "text",
                  null
                ],
                "type": [
                  "string",
                  "null"
                ],
                "description": "kpi: one total per measure (no dimensions; add compare previous_period for a change). funnel: 2+ measures as steps (no dimensions). table: 0-2 dimensions. bar: 1-2 dimensions. stacked_bar: exactly 2 dimensions. line: first dimension a date. text: a note, only `text`."
              },
              "limit": {
                "type": [
                  "integer",
                  "null"
                ],
                "maximum": 500,
                "minimum": 1,
                "description": "Rows for a table / bar / line. Default 100 (line 500)."
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 120
              },
              "where": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "required": [
                    "field",
                    "op"
                  ],
                  "properties": {
                    "op": {
                      "enum": [
                        "eq",
                        "neq",
                        "in",
                        "not_in",
                        "gt",
                        "gte",
                        "lt",
                        "lte",
                        "between",
                        "is_empty",
                        "is_not_empty",
                        null
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "field": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^[a-z][a-z0-9_]{0,40}$",
                      "description": "A dimension of the block's dataset."
                    },
                    "value": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "number"
                        },
                        {
                          "type": "boolean"
                        },
                        {
                          "type": "array",
                          "items": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "number"
                              }
                            ]
                          }
                        }
                      ],
                      "description": "One value for eq / neq / gt / gte / lt / lte, a list for in / not_in, [low, high] for between, nothing for is_empty / is_not_empty."
                    }
                  },
                  "additionalProperties": false
                },
                "maxItems": 10
              },
              "width": {
                "type": [
                  "integer",
                  "null"
                ],
                "maximum": 12,
                "minimum": 1,
                "description": "Columns of a 12-column grid. Default 12."
              },
              "compare": {
                "enum": [
                  "previous_period",
                  null
                ],
                "type": [
                  "string",
                  "null"
                ],
                "description": "kpi / funnel only: also return the same numbers for the period before."
              },
              "dataset": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "interview_results",
                "description": "Dataset id from report-catalog. Not used by a text block."
              },
              "measures": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9_]{0,40}$"
                },
                "example": [
                  "completed",
                  "avg_score"
                ],
                "maxItems": 6,
                "minItems": 1,
                "description": "1 to 6 measure ids of the dataset."
              },
              "dimensions": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "anyOf": [
                    {
                      "type": "string",
                      "pattern": "^[a-z][a-z0-9_]{0,40}$"
                    },
                    {
                      "type": "object",
                      "required": [
                        "field"
                      ],
                      "properties": {
                        "field": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^[a-z][a-z0-9_]{0,40}$"
                        },
                        "grain": {
                          "enum": [
                            "day",
                            "week",
                            "month",
                            "quarter",
                            "year",
                            null
                          ],
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "For a date field: day (default), week, month, quarter or year."
                        }
                      },
                      "additionalProperties": false
                    }
                  ],
                  "description": "A dimension field id, or {\"field\", \"grain\"} for a date."
                },
                "maxItems": 2
              }
            },
            "additionalProperties": false
          },
          "maxItems": 12
        },
        "schema": {
          "enum": [
            "jobmojito.report/v1",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "description": "Always \"jobmojito.report/v1\"."
        },
        "filters": {
          "type": "object",
          "properties": {
            "period": {
              "anyOf": [
                {
                  "type": "object",
                  "required": [
                    "preset"
                  ],
                  "properties": {
                    "preset": {
                      "enum": [
                        "last_7_days",
                        "last_30_days",
                        "last_90_days",
                        "this_month",
                        "last_month",
                        "this_quarter",
                        "last_quarter",
                        "this_year",
                        "last_year",
                        "all_time",
                        null
                      ],
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "additionalProperties": false
                },
                {
                  "type": "object",
                  "required": [
                    "from",
                    "to"
                  ],
                  "properties": {
                    "to": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                    },
                    "from": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                    }
                  },
                  "additionalProperties": false
                }
              ],
              "example": {
                "preset": "last_30_days"
              },
              "description": "Either a preset, or from and to dates (YYYY-MM-DD, both inclusive, UTC). Default: last_30_days."
            },
            "include_test": {
              "type": [
                "boolean",
                "null"
              ],
              "description": "Include test runs. Default false."
            },
            "position_ids": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "maxItems": 200,
              "description": "Positions to show (position ids from list_interviews). position_ids, interview_ids and without_position are one pick list: a row shows when it belongs to ANY pick. Nothing picked = all."
            },
            "interview_ids": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string",
                "format": "uuid"
              },
              "maxItems": 200,
              "description": "Interviews to show (interview ids from list_interviews), combined with the other picks by OR. Nothing picked = all."
            },
            "without_position": {
              "type": [
                "boolean",
                "null"
              ],
              "description": "Also pick interviews that are not part of any position (stand-alone interviews, and coaching sessions). Combined with the other picks by OR."
            }
          },
          "description": "Filters for every block of the report. Each viewer can override them for themselves.",
          "additionalProperties": false
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "maxLength": 1000
        }
      },
      "description": "A custom report: report-wide filters and up to 12 blocks. Read report-catalog first for the dataset, field and measure ids.",
      "additionalProperties": false
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Optional merchant to act on. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "users",
    "interview_id"
  ],
  "properties": {
    "users": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Peter Parker",
            "description": "Display name of the candidate."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "example": "[email protected]",
            "description": "Email used to identify and invite the candidate. Validated per item, not request-level."
          },
          "phone": {
            "type": [
              "string",
              "null"
            ],
            "example": "+421903123456",
            "description": "Optional mobile number in international format (E.164, e.g. +421903123456). Enables SMS / WhatsApp invitation and reminder notifications when the interview has candidate_notification_channel set. Never overwrites a phone already stored on the candidate."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "example": "abcd",
            "description": "Optional caller-supplied id, stored on the candidate profile."
          }
        }
      },
      "example": [
        {
          "name": "Peter Parker",
          "email": "[email protected]",
          "external_id": "abcd"
        },
        {
          "name": "Mary Jane Watson",
          "email": "[email protected]"
        }
      ],
      "description": "Candidates to register for the interview. Each gets a one-time interview URL."
    },
    "is_test": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string"
        },
        {}
      ],
      "description": "When true (or the string \"true\"), mints a test token that can take a draft/unpublished interview and flags the result as a test. For a DRAFT interview it also recompiles the definition (interview_recalc_definition) first, so the test session includes the current questions/welcome. This makes it a single-call \"trigger interview test\"."
    },
    "hide_menu": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string"
        },
        {}
      ],
      "description": "When true (or the string \"true\"), the interview UI hides its menu (view_hm)."
    },
    "send_email": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Whether to send an invitation email to each registered candidate."
    },
    "hide_iframe": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string"
        },
        {}
      ],
      "description": "When true (or the string \"true\"), the interview UI hides its iframe chrome (view_hi)."
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "b5201178-46dd-4a20-a1af-7ffd647f834b",
      "description": "Merchant id. Required when authenticating with the service key; for user tokens it is optional and only honored for admin / sub-merchant accounts."
    },
    "interview_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "04e09fa5-3fb8-4236-b37d-fca2bcd1cb66",
      "minLength": 1,
      "description": "Interview definition (interview_def_set) or position (position_def_set) id to register users for."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

{
  "type": "object",
  "required": [
    "description"
  ],
  "properties": {
    "result_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "The interview result the problem is about, if any."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "example": "The PDF report of a finished interview stays empty since this morning. Other results open fine.",
      "maxLength": 4000,
      "minLength": 10,
      "description": "What went wrong: what you did, what you expected, what happened instead (error messages as shown), and since when. Plain text; blank lines separate paragraphs. Do not include passwords or API keys."
    },
    "interview_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "The interview (definition) the problem is about, if any."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "position_id"
  ],
  "properties": {
    "status": {
      "enum": [
        "draft",
        "active",
        "archived",
        "deleted",
        "preparing",
        "completed",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "description": "New lifecycle status to apply."
    },
    "is_embedded": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Controls iframe embedding of the interview on an external page. When true, ensures an embed key exists (returns embed_id/embed_signing_key, used to authenticate/sign the iframe embed). When false, removes the embed keys (disables embedding). Where it runs depends on the type: interviews, assessments and interview role-plays embed on the interview portal (`https://<interview portal domain>/embed?embed_id=...`); coaching sessions and coaching personas embed on the consumer (coaching) portal (`https://<coaching portal domain>/embed?embed_id=...`, a link built on the interview portal is forwarded there). A signed coaching embed (name, email, signature) signs the visitor in as a learner of that portal, and the session is charged to the merchant's interview credits on completion, not to the learner's coaching credits; it cannot start while the merchant has none."
    },
    "position_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "00000000-0000-0000-0000-000000000000",
      "minLength": 1,
      "description": "Interview definition id or position id whose state should change."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

{
  "type": "object",
  "required": [
    "title",
    "description"
  ],
  "properties": {
    "title": {
      "type": [
        "string",
        "null"
      ],
      "example": "Export all results of a position as one CSV",
      "maxLength": 120,
      "minLength": 5,
      "description": "A short summary of the feature, shown as the post title."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "example": "We review applications in a spreadsheet every Friday. Today we export each interview separately; one CSV per position would save an hour a week.",
      "maxLength": 4000,
      "minLength": 10,
      "description": "What the user needs and why: the problem, how they work around it today, who it would help. Plain text; blank lines separate paragraphs. The board is public: do not include candidate data, company names or other personal information."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id"
  ],
  "properties": {
    "id": {
      "type": [
        "string",
        "null"
      ],
      "example": "sales-coaching-en",
      "pattern": "^[a-z0-9]+(?:(?:-|_)+[a-z0-9]+)*$",
      "minLength": 1,
      "description": "Id of the directory to update (the catalogue URL segment). The id itself is not changed here — rename a directory in the admin catalogue editor, which moves every link to it."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Sales coaching",
      "minLength": 1,
      "description": "Display name of the directory."
    },
    "status": {
      "enum": [
        "draft",
        "active",
        "archived",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "active",
      "description": "Lifecycle status of the catalogue directory. Options — `draft`: Not published — the directory exists but is not served to visitors. | `active`: Published and served in the catalogue. | `archived`: Retired — kept for reference but no longer served.."
    },
    "tags_sub": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "example": [
        "sales-coaching-objections-en",
        "sales-coaching-closing-en"
      ],
      "description": "Ids of the directories nested under this one, in display order. Replaces the whole list — send the full set, not just the additions. A referenced directory only appears if it exists and is visible to the viewer."
    },
    "coach_plan": {
      "enum": [
        "demo",
        "screening",
        "2nd",
        "3rd",
        "closing",
        "job-specific",
        "other",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "screening",
      "description": "Coaching-plan stage this item belongs to, used by the coaching-plan progress view. Omit/null to leave it out of any plan. Options — `demo`: Demo session. | `screening`: Screening-interview practice. | `2nd`: Second-interview practice. | `3rd`: Third-interview practice. | `closing`: Closing / salary-negotiation practice. | `job-specific`: Job-specific coaching. | `other`: Anything that does not fit the other buckets.."
    },
    "content_md": {
      "type": [
        "string",
        "null"
      ],
      "example": "## Sales coaching\n\nPick a session to practise with.\n\n[chip:6 sessions] [chip:Beginner,tone=accent]\n\n[sessions:filter=objection-handling,limit=6]\n",
      "description": "Markdown for the custom directory page. Sending null removes the custom page and restores the default grid; sending a string replaces the whole page. Directives, each ALONE on its own line: `[plan-progress]`, `[directory:<tag-id>]`, `[session:<interview-id>]`, `[sessions]`, `[sessions:<term>]`, `[sessions:filter=<term>,limit=<n>]`. Chips, callouts, cards, columns and buttons are available too — formatting guide: https://developer.jobmojito.com/cookbooks/format-content-with-markdown"
    },
    "visibility": {
      "enum": [
        "public",
        "merchant_public",
        "merchant_invite",
        "merchant_unlisted",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "merchant_public",
      "description": "Who can see the catalogue directory. Options — `public`: Shared across every merchant. Platform admins only — a merchant caller is rejected by row-level security. | `merchant_public`: Listed in the merchant's own catalogue — the normal choice. | `merchant_invite`: Owned by the merchant but not listed; reachable only for invited users. | `merchant_unlisted`: Owned by the merchant but not listed; reachable only via a direct link.."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Short description shown on the directory card."
    },
    "translations": {
      "type": [
        "object",
        "null"
      ],
      "example": {
        "sk": {
          "name": "Obchodný koučing",
          "tags_interview_set_filter": [
            "sales-sk"
          ]
        }
      },
      "description": "The directory's OTHER language versions, keyed by mojito language code. The top-level fields are the default language (`mojito_language_code`); each version here is a page of its own with its own name, Markdown, session filter and sub-directories, shown to learners who pick that language in the catalogue (falling back to English, then the default). A key may not equal `mojito_language_code`. Only the languages you send change: an object replaces that version, null removes it. Send `translations: null` to remove every version.",
      "additionalProperties": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Obchodný koučing",
            "minLength": 1,
            "description": "Page title and card name in this language."
          },
          "tags_sub": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "example": [
              "sales-coaching-objections-en",
              "sales-coaching-closing-en"
            ],
            "description": "Ids of the directories nested under this one, in display order. Replaces the whole list — send the full set, not just the additions. A referenced directory only appears if it exists and is visible to the viewer."
          },
          "content_md": {
            "type": [
              "string",
              "null"
            ],
            "example": "## Sales coaching\n\nPick a session to practise with.\n\n[chip:6 sessions] [chip:Beginner,tone=accent]\n\n[sessions:filter=objection-handling,limit=6]\n",
            "description": "Markdown for a custom directory page. When set (even as an empty string) the markdown replaces the default grid and decides the layout itself; null renders the plain grid of sub-directories and sessions. Alongside normal Markdown you can place these directives, each ALONE on its own line: `[plan-progress]` (the learner's coaching-plan progress), `[directory:<tag-id>]` (a card for one sub-directory), `[session:<interview-id>]` (a card for one session), `[sessions]` (every session in this directory), `[sessions:<term>]` (sessions matching a term), `[sessions:filter=<term>,limit=<n>]` (a filtered, capped list). A directive on a line with other text is rendered as ordinary text. Chips, callouts, cards, columns and buttons are available here too — full vocabulary: https://developer.jobmojito.com/cookbooks/format-content-with-markdown"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Card description in this language."
          },
          "cover_image_url": {
            "type": [
              "string",
              "null"
            ],
            "description": "Cover image for this language. Omit to show the default language's cover."
          },
          "tags_interview_set_filter": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "example": [
              "sales",
              "objection-handling"
            ],
            "description": "Tag filter selecting which coaching sessions this directory lists: a session appears when its own `tags` contain EVERY tag here (an AND, not an OR). Only `active` coaching/persona sessions with visibility `public` or `merchant_public` are listed. Set the matching tags on the session with the create-interview / job-interview-update `tags` field."
          }
        },
        "additionalProperties": false
      }
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "cover_image_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cover image URL shown on the directory card. null clears it."
    },
    "mojito_language_code": {
      "enum": [
        "ar",
        "bg",
        "zh",
        "hr",
        "cs",
        "da",
        "nl",
        "en",
        "fil",
        "fi",
        "fr",
        "de",
        "el",
        "hi",
        "hu",
        "id",
        "it",
        "ja",
        "ko",
        "ms",
        "no",
        "pl",
        "pt",
        "br",
        "ro",
        "ru",
        "sk",
        "es",
        "sv",
        "ta",
        "th",
        "tr",
        "uk",
        "vi",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "en",
      "description": "Language of the directory (one of the platform-languages.json codes). The catalogue groups directories by language."
    },
    "tags_interview_set_filter": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "example": [
        "sales",
        "objection-handling"
      ],
      "description": "Tag filter selecting which coaching sessions this directory lists: a session appears when its own `tags` contain EVERY tag here (an AND, not an OR). Only `active` coaching/persona sessions with visibility `public` or `merchant_public` are listed. Set the matching tags on the session with the create-interview / job-interview-update `tags` field."
    }
  }
}

Argument	Type	Description
code	string \| null	External code/reference. Blank is stored as null.
name	string \| null	Interview / position name.
tags	array \| null	Free-form tags stored on the interview. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed.
type	string \| null	Product type of the interview. Changing it also re-derives `type_credit` (null for interview/assessment, otherwise interview_coach_manager) unless you send `type_credit` explicitly. Single-stage interviews only.
status	string \| null	New lifecycle status. Applied through the same interview_set_status routine as job-interview-set-state (which is also where you manage the iframe embed key).
location	string \| null	Interview location (column `interview_location`). Blank is stored as null.
questions	array \| null	OPTIONAL. Omit this field entirely and the interview's questions are left exactly as they are — this endpoint only touches questions when you send the array. When you do send it, send the COMPLETE list you want the interview to end up with, in order, in the same format job-interview-create-from-array accepts and job-interview-get returns: there is no way to change a single question on its own, so read the interview, edit that array, and send the whole thing back. An empty array is rejected. It is applied as a DIFF, not a replace, so resending the array job-interview-get gave you changes nothing at all. Each entry is matched against what is stored — first on `external_id`, then on `id`, then on identical content — and: an entry matching an unchanged question keeps that question exactly as it is, including its answer rules and any rendered avatar video; an entry matching a question whose content differs unlinks the old question and creates a new one in its place (fields you omit are carried over from the old one); an entry matching nothing is created; and a stored question no entry matches is unlinked. `questions_diff` in the response reports exactly what was decided. Questions are shared records, so nothing is ever deleted — removing one only unlinks it from this interview, and an edit is always unlink-old + create-new so the change cannot leak into another interview reusing the same question. The welcome, thank-you and instructional-video steps are not part of this array and are left in place. Single-stage interviews only; for a multi-stage position, update its interview stages individually.
recording	string \| null	Cheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Video options also record the candidate. Omit/null to disable. Options — `audio_first_5_answers`: Audio-only cheating detection, first 5 answers only. \| `audio_all`: Audio-only cheating detection on every answer. \| `video_all`: Audio + video cheating detection on every answer (candidate is recorded for all answers). \| `video_first_5_answers`: Audio + video cheating detection, first 5 answers only..
coach_plan	string \| null	Coaching-plan stage this item belongs to, used by the coaching-plan progress view. Omit/null to leave it out of any plan. Options — `demo`: Demo session. \| `screening`: Screening-interview practice. \| `2nd`: Second-interview practice. \| `3rd`: Third-interview practice. \| `closing`: Closing / salary-negotiation practice. \| `job-specific`: Job-specific coaching. \| `other`: Anything that does not fit the other buckets..
visibility	string \| null	Who can discover and access the interview. Options — `merchant_public`: Listed on the merchant's public interview list — anyone with the merchant link can find and start it. \| `merchant_invite`: Invite-only — only candidates explicitly invited (by email/link) can access it; not listed anywhere. \| `merchant_unlisted`: Reachable only via a direct link — not listed anywhere; share the link manually..
description	string \| null	Short interview description.
environment	string \| null	Which of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. \| `uat`: User-acceptance testing - an isolated environment for pre-release verification. \| `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. \| `demo`: Demonstrations and sales trials..
position_id*	string \| null	Id of the interview definition (single-stage) or position definition (multi-stage) to update. The same id you pass to job-interview-get.
result_view	string \| null	Result screen shown to the candidate after finishing. With any value other than `none`, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Options — `none`: No results screen at all — the interview is submitted immediately when the candidate finishes (no feedback, intro video, transcript edit or manual submit step). \| `minimal`: Minimal results layout, no score shown. \| `minimal_with_score`: Minimal results layout including the overall score. \| `advanced`: Advanced results layout with more detail. \| `full`: Full results layout with all sections. \| `full_expand_scores`: Full results with every score breakdown expanded..
type_credit	string \| null	Credit bucket the session draws from. Only meaningful for candidate-paid coaching/persona sessions; hiring interviews and assessments are merchant-billed and carry null. Options — `resume_check`: Resume-check credits. \| `interview_coach_starter`: Coaching credits — starter tier. \| `interview_coach_contributor`: Coaching credits — contributor tier. \| `interview_coach_manager`: Coaching credits — manager tier. \| `cover_letter`: Cover-letter credits..
max_duration	number \| null	Live session limit in seconds. Also the basis for the credit multiplier.
max_followups	integer \| null	Maximum number of AI follow-up questions. 0 disables follow-ups; presets are 0-3 (none/low/normal/high) and custom values start at 4; null uses the template default (Normal).
custom_scoring	object \| null	Result-scoring overrides (max_score, early_stop, speech_cadence, ai_pronunciation, sentiment_analysis, ai_assessment_answer, ai_assessment_resume, ai_assessment_session). Merged onto the stored configuration, so keys you omit keep their current value.
interview_tone	string \| null	Tone — configures the AI avatar's speaking style and the follow-up questions it generates. Stored in creation_parameters; existing questions are NOT regenerated. Case-insensitive; omit to default to relaxed. Options — `relaxed`: Friendly and conversational tone that helps candidates feel at ease. \| `simple`: Plain language at CEFR A2 level — short sentences and simple words. \| `professional`: Formal and business-like approach suitable for senior roles. \| `persuasive`: Engaging style that encourages candidates to elaborate. \| `exact`: Asks the questions exactly as provided, without rephrasing — for interviews built from your own questions (create_interview_from_questions) where the wording is a script..
interview_type	string \| null	Interview style — configures the AI avatar and the follow-up questions it generates during the interview. Stored in creation_parameters; existing questions are NOT regenerated. Options — `pre-screening`: Pre-screening — quick qualification check focusing on basic requirements and availability. \| `pre-screening-with-test-questions`: Pre-screening with test questions — pre-screening plus practical questions to test relevant skills. \| `second-interview`: Second round interview — deeper dive for candidates who passed initial screening. \| `remote-freelancer-verification`: Remote worker verification — verify remote work capabilities and communication skills. \| `strength-based-interview`: Strength-based interview — focus on what candidates enjoy and excel at to predict job satisfaction. \| `potential-based-interview`: Potential-based interview — assess learning ability and growth potential rather than past experience. \| `process-verification-from-knowledge-base`: Knowledge Base interview — generate questions from your knowledge base documents. \| `knockout-screening`: Knock-out screening — a short (about 5 minute) check of the role's must-haves with closed questions; ends early, politely, when a must-have is clearly not met. On creation it defaults custom_scoring.early_stop to true (where the avatar supports early stop) and max_followups to 1 unless you send them..
conversation_id	string	Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request.
cover_image_url	string \| null	Cover image URL.
seniority_level	string \| null	Target seniority level for the role; auto-detected from the job description when omitted. Options — `entry-level`: Early-career or graduate roles. \| `intermediate`: Some experience required. \| `senior`: Experienced professional. \| `managerial`: Team or department lead. \| `director`: Director-level responsibility. \| `executive`: C-suite or executive role..
description_long	string \| null	Long-form interview description (column `interview_description_long`). Rendered as Markdown on the candidate-facing position page, including chips, callouts, cards, columns and buttons — formatting guide: https://developer.jobmojito.com/cookbooks/format-content-with-markdown
interview_salary	string \| null	Salary range shown for the position. Blank is stored as null.
hiring_for_company	object \| null	Who the position is really for. null (or an object with name null/blank) means hiring for yourself; { name: 'undisclosed' } for an unnamed external client; or { name: '<company>' } plus optional description/location/sector/company_size. Stored in creation_parameters.hiring_for_company.
interview_attempts	number \| null	Allowed candidate attempts (1-20). Stored as result_scoring.max_retries.
country_availability	object \| null	Which countries the interview / position is open to on the candidate portal, judged by the IP address the candidate opens it from (an unknown location only passes when countries_allowed / countries_allowed_eu are empty). From a closed country it is left out of the portal listings, and a direct link shows "not available in your region". Invited candidates (register_users / invite links) and candidates who already started keep access; API and MCP calls themselves are never restricted. Null = not used, every country.
interview_department	string \| null	Department the position belongs to. Blank is stored as null.
recruiter_profile_id	string \| null	Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant. null clears it.
interview_template_id	string \| null	Id of the interview template (avatar/voice) to use. Must reference an existing interview_templates row. Also decides the modality — see list_avatars / merchant-avatar-list.
candidate_expectations	string \| null	Free-text candidate expectations.
pdf_export_auto_config	object \| null	Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export.
recording_full_session	string \| null	Full interview-session recording (includes the avatar and voice) produced as a single file. Independent of `recording`. Omit/null to disable. Options — `audio_all`: Record the whole session audio (avatar + candidate voice) into a single file. Adds +0.2 credits. \| `video_all`: Record the whole session video + audio (avatar + candidate) into a single file. Adds +0.4 credits..
required_pronunciation	boolean \| null	Require pronunciation assessment (restricts to pronunciation-capable languages).
knowledge_base_store_id	string \| null	Knowledge base store id the interview draws context from; validated for existence. null unlinks it.
questions_random_subset	number \| null	Ask only a random subset of the questions, as a fraction between 0.01 and 0.9. null asks all questions.
interview_available_till	string \| null	ISO date/time after which the interview is no longer available to candidates. null keeps it always available.
candidate_expectations_json	object \| null	Structured candidate expectations (the scoring rubric), bucketed by requirement level (weak/moderate/strong). null clears the rubric. Extra keys are preserved.
candidate_video_introduction	string \| null	Whether a candidate video introduction is hidden, optional or required. null is treated like hidden.
interview_conversation_speed	string \| null	Conversation pace of the AI avatar. Omit/null keeps the template default pace. Options — `slower`: The avatar speaks more slowly — easier to follow for non-native speakers. \| `normal`: Default speaking pace. \| `faster`: The avatar speaks more quickly for a snappier conversation..
result_enable_edit_transcript	boolean \| null	Allow editing the transcript on the result view.
candidate_notification_channel	string \| null	SMS / WhatsApp notifications to the candidate, sent alongside the e-mails: "reminders" = with both e-mail reminders (day 1 and day 3); "last_reminder" = only with the final day-3 reminder; "all" = invitation, both reminders and the pre-screening-accepted step. null switches them off. WhatsApp is tried first, SMS when the number is not on WhatsApp. Available on paid plans (Starter and above) and needs a phone number on the candidate.
regenerate_candidate_expectations	boolean \| null	Re-derive the interview-level `candidate_expectations_json` scoring rubric from the resulting question list, the way job-interview-create-from-array derives it at creation time. Only applies when `questions` is sent, the interview type is `interview`, and `candidate_expectations_json` is not also being set explicitly (an explicit value wins).

Input schema (JSON)

{
  "type": "object",
  "required": [
    "position_id"
  ],
  "properties": {
    "code": {
      "type": [
        "string",
        "null"
      ],
      "description": "External code/reference. Blank is stored as null."
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "example": "Project manager",
      "description": "Interview / position name."
    },
    "tags": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "example": [
        "interview-practice",
        "sales"
      ],
      "description": "Free-form tags stored on the interview. Tags are also the coaching-catalogue mapping key: a catalogue directory (see the catalogue-tag-create / catalogue-tag-update endpoints) lists a coaching or persona session when the session's tags contain EVERY tag in that directory's `tags_interview_set_filter`. Only `active` sessions with visibility `public` or `merchant_public` are listed."
    },
    "type": {
      "enum": [
        "interview",
        "coaching",
        "assessment",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "interview",
      "description": "Product type of the interview. Changing it also re-derives `type_credit` (null for interview/assessment, otherwise interview_coach_manager) unless you send `type_credit` explicitly. Single-stage interviews only."
    },
    "status": {
      "enum": [
        "draft",
        "active",
        "archived",
        "deleted",
        "preparing",
        "completed",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "active",
      "description": "New lifecycle status. Applied through the same interview_set_status routine as job-interview-set-state (which is also where you manage the iframe embed key)."
    },
    "location": {
      "type": [
        "string",
        "null"
      ],
      "example": "remote",
      "description": "Interview location (column `interview_location`). Blank is stored as null."
    },
    "questions": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "required": [
          "question"
        ],
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identifier for this question. job-interview-get returns the question's real id here; send it back to job-interview-update so an unchanged question keeps its existing record (and with it its answer rules and any rendered avatar video). Also the handle another question references via conditional_question_main_id. On job-interview-create-from-array it is a caller-local value, only needed for those references."
          },
          "label": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional label/tag stored on the question."
          },
          "duration": {
            "type": [
              "number",
              "null"
            ],
            "description": "Answer duration in seconds for this question."
          },
          "question": {
            "type": [
              "string",
              "null"
            ],
            "description": "The question text shown to the candidate."
          },
          "is_expert": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Expert listening question (view 'with listening expert')."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "External identifier stored on the question. job-interview-update matches on this first, so an ATS that owns stable ids can send its own array and have the diff line up without round-tripping our ids."
          },
          "external_data": {
            "type": [
              "object",
              "null"
            ],
            "description": "Arbitrary JSON metadata stored on the question.",
            "additionalProperties": {}
          },
          "is_conditional": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Conditional follow-up question (view 'with listening conditional'). Use with conditional_question_main_id."
          },
          "knowledge_base_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Knowledge-base store id (uuid) the question draws context from."
          },
          "is_multiple_choice": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Multiple-choice question (view 'multiple choice')."
          },
          "is_without_scoring": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Question is asked but not scored (view 'without scoring')."
          },
          "mojito_language_code": {
            "enum": [
              "ar",
              "bg",
              "zh",
              "hr",
              "cs",
              "da",
              "nl",
              "en",
              "fil",
              "fi",
              "fr",
              "de",
              "el",
              "hi",
              "hu",
              "id",
              "it",
              "ja",
              "ko",
              "ms",
              "no",
              "pl",
              "pt",
              "br",
              "ro",
              "ru",
              "sk",
              "es",
              "sv",
              "ta",
              "th",
              "tr",
              "uk",
              "vi",
              null
            ],
            "type": [
              "string",
              "null"
            ],
            "example": "en",
            "description": "Per-question language override (one of the platform-languages.json codes). Inherits the interview language when omitted."
          },
          "question_alternatives": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Alternative phrasings for the question."
          },
          "candidate_expectations_json": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "weak": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                },
                "description": "Baseline requirements every viable candidate should meet (table stakes)."
              },
              "strong": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                },
                "description": "High-bar requirements only standout candidates clear."
              },
              "moderate": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "string"
                },
                "description": "Requirements expected of a solid, competent candidate."
              }
            },
            "description": "Per-question candidate expectations, bucketed by requirement level (weak/moderate/strong). Extra keys are preserved."
          },
          "conditional_question_main_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "For a conditional question, the id (the \"id\" field above) of the parent question in this same array that triggers it. The parent must appear earlier in the array than the conditional question referencing it."
          },
          "is_candidate_asking_recruiter": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Candidate-asks-recruiter prompt (view 'candidate asking recruiter')."
          }
        },
        "additionalProperties": {}
      },
      "minItems": 1,
      "description": "OPTIONAL. Omit this field entirely and the interview's questions are left exactly as they are — this endpoint only touches questions when you send the array. When you do send it, send the COMPLETE list you want the interview to end up with, in order, in the same format job-interview-create-from-array accepts and job-interview-get returns: there is no way to change a single question on its own, so read the interview, edit that array, and send the whole thing back. An empty array is rejected. It is applied as a DIFF, not a replace, so resending the array job-interview-get gave you changes nothing at all. Each entry is matched against what is stored — first on `external_id`, then on `id`, then on identical content — and: an entry matching an unchanged question keeps that question exactly as it is, including its answer rules and any rendered avatar video; an entry matching a question whose content differs unlinks the old question and creates a new one in its place (fields you omit are carried over from the old one); an entry matching nothing is created; and a stored question no entry matches is unlinked. `questions_diff` in the response reports exactly what was decided. Questions are shared records, so nothing is ever deleted — removing one only unlinks it from this interview, and an edit is always unlink-old + create-new so the change cannot leak into another interview reusing the same question. The welcome, thank-you and instructional-video steps are not part of this array and are left in place. Single-stage interviews only; for a multi-stage position, update its interview stages individually."
    },
    "recording": {
      "enum": [
        "audio_first_5_answers",
        "audio_all",
        "video_all",
        "video_first_5_answers",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "video_all",
      "description": "Cheating/proctoring detection mode for candidate answers — this is NOT a full session recording. Video options also record the candidate. Omit/null to disable. Options — `audio_first_5_answers`: Audio-only cheating detection, first 5 answers only. | `audio_all`: Audio-only cheating detection on every answer. | `video_all`: Audio + video cheating detection on every answer (candidate is recorded for all answers). | `video_first_5_answers`: Audio + video cheating detection, first 5 answers only.."
    },
    "coach_plan": {
      "enum": [
        "demo",
        "screening",
        "2nd",
        "3rd",
        "closing",
        "job-specific",
        "other",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "screening",
      "description": "Coaching-plan stage this item belongs to, used by the coaching-plan progress view. Omit/null to leave it out of any plan. Options — `demo`: Demo session. | `screening`: Screening-interview practice. | `2nd`: Second-interview practice. | `3rd`: Third-interview practice. | `closing`: Closing / salary-negotiation practice. | `job-specific`: Job-specific coaching. | `other`: Anything that does not fit the other buckets.."
    },
    "visibility": {
      "enum": [
        "merchant_public",
        "merchant_invite",
        "merchant_unlisted",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "merchant_public",
      "description": "Who can discover and access the interview. Options — `merchant_public`: Listed on the merchant's public interview list — anyone with the merchant link can find and start it. | `merchant_invite`: Invite-only — only candidates explicitly invited (by email/link) can access it; not listed anywhere. | `merchant_unlisted`: Reachable only via a direct link — not listed anywhere; share the link manually.."
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Short interview description."
    },
    "environment": {
      "enum": [
        "production",
        "uat",
        "development",
        "demo",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "production",
      "description": "Which of your webhook environments results from this interview are delivered to. Defaults to production. Options — `production`: Live hiring. Results reach the webhooks configured as production. This is the default when the field is omitted. | `uat`: User-acceptance testing - an isolated environment for pre-release verification. | `development`: Development/testing. Use for interviews created by a test or preview app so their results never reach the production webhook. | `demo`: Demonstrations and sales trials.."
    },
    "position_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "example": "00000000-0000-0000-0000-000000000000",
      "minLength": 1,
      "description": "Id of the interview definition (single-stage) or position definition (multi-stage) to update. The same id you pass to job-interview-get."
    },
    "result_view": {
      "enum": [
        "none",
        "minimal",
        "minimal_with_score",
        "advanced",
        "full",
        "full_expand_scores",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "full",
      "description": "Result screen shown to the candidate after finishing. With any value other than `none`, the candidate sees a results screen where they can provide feedback, record an intro video and edit the transcript, and must then submit the result; the value sets how much score/result detail is shown. Options — `none`: No results screen at all — the interview is submitted immediately when the candidate finishes (no feedback, intro video, transcript edit or manual submit step). | `minimal`: Minimal results layout, no score shown. | `minimal_with_score`: Minimal results layout including the overall score. | `advanced`: Advanced results layout with more detail. | `full`: Full results layout with all sections. | `full_expand_scores`: Full results with every score breakdown expanded.."
    },
    "type_credit": {
      "enum": [
        "resume_check",
        "interview_coach_starter",
        "interview_coach_contributor",
        "interview_coach_manager",
        "cover_letter",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "interview_coach_manager",
      "description": "Credit bucket the session draws from. Only meaningful for candidate-paid coaching/persona sessions; hiring interviews and assessments are merchant-billed and carry null. Options — `resume_check`: Resume-check credits. | `interview_coach_starter`: Coaching credits — starter tier. | `interview_coach_contributor`: Coaching credits — contributor tier. | `interview_coach_manager`: Coaching credits — manager tier. | `cover_letter`: Cover-letter credits.."
    },
    "max_duration": {
      "type": [
        "number",
        "null"
      ],
      "example": 1200,
      "description": "Live session limit in seconds. Also the basis for the credit multiplier."
    },
    "max_followups": {
      "type": [
        "integer",
        "null"
      ],
      "example": 2,
      "maximum": 999,
      "minimum": 0,
      "description": "Maximum number of AI follow-up questions. 0 disables follow-ups; presets are 0-3 (none/low/normal/high) and custom values start at 4; null uses the template default (Normal)."
    },
    "custom_scoring": {
      "type": [
        "object",
        "null"
      ],
      "description": "Result-scoring overrides (max_score, early_stop, speech_cadence, ai_pronunciation, sentiment_analysis, ai_assessment_answer, ai_assessment_resume, ai_assessment_session). Merged onto the stored configuration, so keys you omit keep their current value.",
      "additionalProperties": {}
    },
    "interview_tone": {
      "enum": [
        "relaxed",
        "simple",
        "professional",
        "persuasive",
        "exact",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "professional",
      "description": "Tone — configures the AI avatar's speaking style and the follow-up questions it generates. Stored in creation_parameters; existing questions are NOT regenerated. Case-insensitive; omit to default to relaxed. Options — `relaxed`: Friendly and conversational tone that helps candidates feel at ease. | `simple`: Plain language at CEFR A2 level — short sentences and simple words. | `professional`: Formal and business-like approach suitable for senior roles. | `persuasive`: Engaging style that encourages candidates to elaborate. | `exact`: Asks the questions exactly as provided, without rephrasing — for interviews built from your own questions (create_interview_from_questions) where the wording is a script.."
    },
    "interview_type": {
      "enum": [
        "pre-screening",
        "pre-screening-with-test-questions",
        "second-interview",
        "remote-freelancer-verification",
        "strength-based-interview",
        "potential-based-interview",
        "process-verification-from-knowledge-base",
        "knockout-screening",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "pre-screening-with-test-questions",
      "description": "Interview style — configures the AI avatar and the follow-up questions it generates during the interview. Stored in creation_parameters; existing questions are NOT regenerated. Options — `pre-screening`: Pre-screening — quick qualification check focusing on basic requirements and availability. | `pre-screening-with-test-questions`: Pre-screening with test questions — pre-screening plus practical questions to test relevant skills. | `second-interview`: Second round interview — deeper dive for candidates who passed initial screening. | `remote-freelancer-verification`: Remote worker verification — verify remote work capabilities and communication skills. | `strength-based-interview`: Strength-based interview — focus on what candidates enjoy and excel at to predict job satisfaction. | `potential-based-interview`: Potential-based interview — assess learning ability and growth potential rather than past experience. | `process-verification-from-knowledge-base`: Knowledge Base interview — generate questions from your knowledge base documents. | `knockout-screening`: Knock-out screening — a short (about 5 minute) check of the role's must-haves with closed questions; ends early, politely, when a must-have is clearly not met. On creation it defaults custom_scoring.early_stop to true (where the avatar supports early stop) and max_followups to 1 unless you send them.."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    },
    "cover_image_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cover image URL."
    },
    "seniority_level": {
      "enum": [
        "entry-level",
        "intermediate",
        "senior",
        "managerial",
        "director",
        "executive",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "senior",
      "description": "Target seniority level for the role; auto-detected from the job description when omitted. Options — `entry-level`: Early-career or graduate roles. | `intermediate`: Some experience required. | `senior`: Experienced professional. | `managerial`: Team or department lead. | `director`: Director-level responsibility. | `executive`: C-suite or executive role.."
    },
    "description_long": {
      "type": [
        "string",
        "null"
      ],
      "description": "Long-form interview description (column `interview_description_long`). Rendered as Markdown on the candidate-facing position page, including chips, callouts, cards, columns and buttons — formatting guide: https://developer.jobmojito.com/cookbooks/format-content-with-markdown"
    },
    "interview_salary": {
      "type": [
        "string",
        "null"
      ],
      "example": "$80k - $100k",
      "description": "Salary range shown for the position. Blank is stored as null."
    },
    "hiring_for_company": {
      "type": [
        "object",
        "null"
      ],
      "example": {
        "name": "undisclosed"
      },
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ],
          "example": "Unimo Enterprises",
          "description": "End-employer name. Omit/null when hiring for yourself, 'undisclosed' for an unnamed external client, or the client's company name."
        },
        "sector": {
          "type": [
            "string",
            "null"
          ],
          "example": "Logistics and Supply Chain",
          "description": "Industry / sector of the end employer."
        },
        "location": {
          "type": [
            "string",
            "null"
          ],
          "example": "Sri Lanka",
          "description": "Primary location of the end employer."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "example": "Unimo Enterprises is a leading logistics and supply chain solutions provider.",
          "description": "Short description of the end employer, used as background context by the agent."
        },
        "company_size": {
          "type": [
            "string",
            "null"
          ],
          "example": "100-200",
          "description": "Approximate headcount of the end employer."
        }
      },
      "description": "Who the position is really for. null (or an object with name null/blank) means hiring for yourself; { name: 'undisclosed' } for an unnamed external client; or { name: '<company>' } plus optional description/location/sector/company_size. Stored in creation_parameters.hiring_for_company."
    },
    "interview_attempts": {
      "type": [
        "number",
        "null"
      ],
      "example": 1,
      "maximum": 20,
      "minimum": 1,
      "description": "Allowed candidate attempts (1-20). Stored as result_scoring.max_retries."
    },
    "country_availability": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "countries_allowed": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$"
          },
          "example": [
            "PH",
            "IN"
          ],
          "description": "Available ONLY to candidates in these countries (ISO 3166-1 alpha-2)."
        },
        "countries_blocked": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$"
          },
          "example": [
            "US"
          ],
          "description": "NOT available to candidates in these countries (ISO 3166-1 alpha-2). Wins over the allowed side."
        },
        "countries_allowed_eu": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Adds every EU country (plus EEA and Switzerland) to countries_allowed."
        },
        "countries_blocked_eu": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Adds every EU country (plus EEA and Switzerland) to countries_blocked."
        }
      },
      "description": "Which countries the interview / position is open to on the candidate portal, judged by the IP address the candidate opens it from (an unknown location only passes when countries_allowed / countries_allowed_eu are empty). From a closed country it is left out of the portal listings, and a direct link shows \"not available in your region\". Invited candidates (register_users / invite links) and candidates who already started keep access; API and MCP calls themselves are never restricted. Null = not used, every country."
    },
    "interview_department": {
      "type": [
        "string",
        "null"
      ],
      "example": "Engineering",
      "description": "Department the position belongs to. Blank is stored as null."
    },
    "recruiter_profile_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Profile id of the recruiter owning this interview. Must be a merchant/merchant_owner/admin profile of the same merchant. null clears it."
    },
    "interview_template_id": {
      "type": [
        "string",
        "null"
      ],
      "example": "46b98d37-1557-4391-beca-03037ead19f2",
      "minLength": 1,
      "description": "Id of the interview template (avatar/voice) to use. Must reference an existing interview_templates row. Also decides the modality — see list_avatars / merchant-avatar-list."
    },
    "candidate_expectations": {
      "type": [
        "string",
        "null"
      ],
      "description": "Free-text candidate expectations."
    },
    "pdf_export_auto_config": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "files": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include uploaded candidate files."
        },
        "template": {
          "enum": [
            "classic",
            "modern",
            "one_pager",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "description": "Report layout: classic, modern, or one_pager. Omit for the merchant default (modern when unset)."
        },
        "analytics": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include analytics."
        },
        "transcript": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the interview transcript."
        },
        "contact_details": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include candidate contact details."
        },
        "answer_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include per-answer recordings."
        },
        "ai_scoring_rubric": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the AI scoring rubric."
        },
        "group_by_question": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Group transcript answers by expected question."
        },
        "session_recording": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the full-session recording."
        },
        "mojito_language_code": {
          "enum": [
            "ar",
            "bg",
            "zh",
            "hr",
            "cs",
            "da",
            "nl",
            "en",
            "fil",
            "fi",
            "fr",
            "de",
            "el",
            "hi",
            "hu",
            "id",
            "it",
            "ja",
            "ko",
            "ms",
            "no",
            "pl",
            "pt",
            "br",
            "ro",
            "ru",
            "sk",
            "es",
            "sv",
            "ta",
            "th",
            "tr",
            "uk",
            "vi",
            null
          ],
          "type": [
            "string",
            "null"
          ],
          "example": "en",
          "description": "Report language code (a platform-languages.json code)."
        },
        "ai_recruiter_assessment": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Include the AI recruiter assessment."
        }
      },
      "description": "Auto-generate a candidate PDF report with these options once the interview completes. null disables auto-export."
    },
    "recording_full_session": {
      "enum": [
        "audio_all",
        "video_all",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "video_all",
      "description": "Full interview-session recording (includes the avatar and voice) produced as a single file. Independent of `recording`. Omit/null to disable. Options — `audio_all`: Record the whole session audio (avatar + candidate voice) into a single file. Adds +0.2 credits. | `video_all`: Record the whole session video + audio (avatar + candidate) into a single file. Adds +0.4 credits.."
    },
    "required_pronunciation": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Require pronunciation assessment (restricts to pronunciation-capable languages)."
    },
    "knowledge_base_store_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Knowledge base store id the interview draws context from; validated for existence. null unlinks it."
    },
    "questions_random_subset": {
      "type": [
        "number",
        "null"
      ],
      "example": 0.5,
      "maximum": 0.9,
      "minimum": 0.01,
      "description": "Ask only a random subset of the questions, as a fraction between 0.01 and 0.9. null asks all questions."
    },
    "interview_available_till": {
      "type": [
        "string",
        "null"
      ],
      "example": "2026-12-31",
      "description": "ISO date/time after which the interview is no longer available to candidates. null keeps it always available."
    },
    "candidate_expectations_json": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "weak": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "Baseline requirements every viable candidate should meet (table stakes)."
        },
        "strong": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "High-bar requirements only standout candidates clear."
        },
        "moderate": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "description": "Requirements expected of a solid, competent candidate."
        }
      },
      "description": "Structured candidate expectations (the scoring rubric), bucketed by requirement level (weak/moderate/strong). null clears the rubric. Extra keys are preserved."
    },
    "candidate_video_introduction": {
      "enum": [
        "hidden",
        "optional",
        "required",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "description": "Whether a candidate video introduction is hidden, optional or required. null is treated like hidden."
    },
    "interview_conversation_speed": {
      "enum": [
        "slower",
        "normal",
        "faster",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "example": "normal",
      "description": "Conversation pace of the AI avatar. Omit/null keeps the template default pace. Options — `slower`: The avatar speaks more slowly — easier to follow for non-native speakers. | `normal`: Default speaking pace. | `faster`: The avatar speaks more quickly for a snappier conversation.."
    },
    "result_enable_edit_transcript": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Allow editing the transcript on the result view."
    },
    "candidate_notification_channel": {
      "enum": [
        "reminders",
        "last_reminder",
        "all",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "description": "SMS / WhatsApp notifications to the candidate, sent alongside the e-mails: \"reminders\" = with both e-mail reminders (day 1 and day 3); \"last_reminder\" = only with the final day-3 reminder; \"all\" = invitation, both reminders and the pre-screening-accepted step. null switches them off. WhatsApp is tried first, SMS when the number is not on WhatsApp. Available on paid plans (Starter and above) and needs a phone number on the candidate."
    },
    "regenerate_candidate_expectations": {
      "type": [
        "boolean",
        "null"
      ],
      "example": false,
      "description": "Re-derive the interview-level `candidate_expectations_json` scoring rubric from the resulting question list, the way job-interview-create-from-array derives it at creation time. Only applies when `questions` is sent, the interview type is `interview`, and `candidate_expectations_json` is not also being set explicitly (an explicit value wins)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "required": [
    "id",
    "version",
    "definition"
  ],
  "properties": {
    "id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Report id (from list_reports)."
    },
    "target": {
      "enum": [
        "published",
        "draft",
        null
      ],
      "type": [
        "string",
        "null"
      ],
      "description": "published (default) or draft. A private report always publishes. Through the MCP server a shared report always gets a draft that its owner publishes in the admin."
    },
    "version": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "description": "The version you read (get_report / list_reports). A stale version is refused with 409."
    },
    "definition": {
      "allOf": [
        {
          "type": "object",
          "example": {
            "title": "Weekly hiring pulse",
            "blocks": [
              {
                "id": "headline",
                "type": "kpi",
                "compare": "previous_period",
                "dataset": "interview_results",
                "measures": [
                  "completed",
                  "avg_score",
                  "shortlisted"
                ]
              },
              {
                "id": "trend",
                "type": "line",
                "title": "Completed per week",
                "width": 8,
                "dataset": "interview_results",
                "measures": [
                  "completed"
                ],
                "dimensions": [
                  {
                    "field": "date",
                    "grain": "week"
                  }
                ]
              },
              {
                "id": "by_position",
                "sort": [
                  {
                    "dir": "desc",
                    "field": "completed"
                  }
                ],
                "type": "table",
                "limit": 25,
                "title": "By position",
                "dataset": "interview_results",
                "measures": [
                  "completed",
                  "avg_score",
                  "shortlisted"
                ],
                "dimensions": [
                  "position"
                ]
              }
            ],
            "schema": "jobmojito.report/v1",
            "filters": {
              "period": {
                "preset": "last_30_days"
              }
            }
          },
          "required": [
            "schema",
            "title",
            "blocks"
          ],
          "properties": {
            "title": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 120,
              "minLength": 1
            },
            "blocks": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "object",
                "required": [
                  "id",
                  "type"
                ],
                "properties": {
                  "id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "by_position",
                    "pattern": "^[A-Za-z0-9_-]{1,40}$"
                  },
                  "sort": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "field"
                      ],
                      "properties": {
                        "dir": {
                          "enum": [
                            "asc",
                            "desc",
                            null
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "field": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^[a-z][a-z0-9_]{0,40}$",
                          "description": "A dimension or measure the block selects."
                        }
                      },
                      "additionalProperties": false
                    },
                    "maxItems": 3
                  },
                  "text": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 4000,
                    "description": "Text block only: the note (plain text, line breaks kept)."
                  },
                  "type": {
                    "enum": [
                      "kpi",
                      "table",
                      "bar",
                      "stacked_bar",
                      "line",
                      "funnel",
                      "text",
                      null
                    ],
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "kpi: one total per measure (no dimensions; add compare previous_period for a change). funnel: 2+ measures as steps (no dimensions). table: 0-2 dimensions. bar: 1-2 dimensions. stacked_bar: exactly 2 dimensions. line: first dimension a date. text: a note, only `text`."
                  },
                  "limit": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "maximum": 500,
                    "minimum": 1,
                    "description": "Rows for a table / bar / line. Default 100 (line 500)."
                  },
                  "title": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 120
                  },
                  "where": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "field",
                        "op"
                      ],
                      "properties": {
                        "op": {
                          "enum": [
                            "eq",
                            "neq",
                            "in",
                            "not_in",
                            "gt",
                            "gte",
                            "lt",
                            "lte",
                            "between",
                            "is_empty",
                            "is_not_empty",
                            null
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "field": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^[a-z][a-z0-9_]{0,40}$",
                          "description": "A dimension of the block's dataset."
                        },
                        "value": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "number"
                            },
                            {
                              "type": "boolean"
                            },
                            {
                              "type": "array",
                              "items": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "number"
                                  }
                                ]
                              }
                            }
                          ],
                          "description": "One value for eq / neq / gt / gte / lt / lte, a list for in / not_in, [low, high] for between, nothing for is_empty / is_not_empty."
                        }
                      },
                      "additionalProperties": false
                    },
                    "maxItems": 10
                  },
                  "width": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "maximum": 12,
                    "minimum": 1,
                    "description": "Columns of a 12-column grid. Default 12."
                  },
                  "compare": {
                    "enum": [
                      "previous_period",
                      null
                    ],
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "kpi / funnel only: also return the same numbers for the period before."
                  },
                  "dataset": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "example": "interview_results",
                    "description": "Dataset id from report-catalog. Not used by a text block."
                  },
                  "measures": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "string",
                      "pattern": "^[a-z][a-z0-9_]{0,40}$"
                    },
                    "example": [
                      "completed",
                      "avg_score"
                    ],
                    "maxItems": 6,
                    "minItems": 1,
                    "description": "1 to 6 measure ids of the dataset."
                  },
                  "dimensions": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "anyOf": [
                        {
                          "type": "string",
                          "pattern": "^[a-z][a-z0-9_]{0,40}$"
                        },
                        {
                          "type": "object",
                          "required": [
                            "field"
                          ],
                          "properties": {
                            "field": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "pattern": "^[a-z][a-z0-9_]{0,40}$"
                            },
                            "grain": {
                              "enum": [
                                "day",
                                "week",
                                "month",
                                "quarter",
                                "year",
                                null
                              ],
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "For a date field: day (default), week, month, quarter or year."
                            }
                          },
                          "additionalProperties": false
                        }
                      ],
                      "description": "A dimension field id, or {\"field\", \"grain\"} for a date."
                    },
                    "maxItems": 2
                  }
                },
                "additionalProperties": false
              },
              "maxItems": 12
            },
            "schema": {
              "enum": [
                "jobmojito.report/v1",
                null
              ],
              "type": [
                "string",
                "null"
              ],
              "description": "Always \"jobmojito.report/v1\"."
            },
            "filters": {
              "type": "object",
              "properties": {
                "period": {
                  "anyOf": [
                    {
                      "type": "object",
                      "required": [
                        "preset"
                      ],
                      "properties": {
                        "preset": {
                          "enum": [
                            "last_7_days",
                            "last_30_days",
                            "last_90_days",
                            "this_month",
                            "last_month",
                            "this_quarter",
                            "last_quarter",
                            "this_year",
                            "last_year",
                            "all_time",
                            null
                          ],
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "required": [
                        "from",
                        "to"
                      ],
                      "properties": {
                        "to": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                        },
                        "from": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                        }
                      },
                      "additionalProperties": false
                    }
                  ],
                  "example": {
                    "preset": "last_30_days"
                  },
                  "description": "Either a preset, or from and to dates (YYYY-MM-DD, both inclusive, UTC). Default: last_30_days."
                },
                "include_test": {
                  "type": [
                    "boolean",
                    "null"
                  ],
                  "description": "Include test runs. Default false."
                },
                "position_ids": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "maxItems": 200,
                  "description": "Positions to show (position ids from list_interviews). position_ids, interview_ids and without_position are one pick list: a row shows when it belongs to ANY pick. Nothing picked = all."
                },
                "interview_ids": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "maxItems": 200,
                  "description": "Interviews to show (interview ids from list_interviews), combined with the other picks by OR. Nothing picked = all."
                },
                "without_position": {
                  "type": [
                    "boolean",
                    "null"
                  ],
                  "description": "Also pick interviews that are not part of any position (stand-alone interviews, and coaching sessions). Combined with the other picks by OR."
                }
              },
              "description": "Filters for every block of the report. Each viewer can override them for themselves.",
              "additionalProperties": false
            },
            "description": {
              "type": [
                "string",
                "null"
              ],
              "maxLength": 1000
            }
          },
          "description": "A custom report: report-wide filters and up to 12 blocks. Read report-catalog first for the dataset, field and measure ids.",
          "additionalProperties": false
        },
        {
          "description": "The whole new definition (it replaces the old one)."
        }
      ]
    },
    "merchant_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Optional merchant to act on. Admins and sub-merchant operators only; other callers always use their token's merchant."
    },
    "conversation_id": {
      "type": "string",
      "description": "Pass the exact conversation_id from the server's previous response, unchanged. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it. Keep passing the same conversation_id for the rest of the conversation, including after later user messages or on a different task; do not reset it when the user starts a new request."
    }
  }
}