JobMojito

[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.

[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.

[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.

[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, billed to their own coaching credits 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.

[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.

[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`.

[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.

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.

[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.

[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.

[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.

[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.

[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.

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).

[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.

[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.

[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.

[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.

[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.

[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.

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).

[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.

[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).

[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.

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.

[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`.

[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`).

[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.

[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`).