# JobMojito Developer / Agent

> AI Interview and assessment conversational platform documentation

- [Welcome to the JobMojito API](https://developer.jobmojito.com/welcome.md): Build AI-powered interviews, assessments and candidate pre-screening into your own product with the JobMojito API and webhooks.
- [How the API works](https://developer.jobmojito.com/how-the-api-works.md): Base URL, request and response format, error model, credits, and the full list of JobMojito API endpoints.
- [How credits work](https://developer.jobmojito.com/how-credits-work.md): JobMojito runs on consumption-based credits. See what each interview, add-on and pre-screen costs, and how billing works.
- [Authentication](https://developer.jobmojito.com/authentication.md): Authenticate JobMojito API requests with a bearer token in the Authorization header.
- [Webhooks](https://developer.jobmojito.com/webhooks.md): Receive real-time interview events at your own endpoint, with at-least-once guaranteed delivery and automatic retries.
- [Create a new interview](https://developer.jobmojito.com/api-reference/interviews/create-a-new-interview.md): 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.
- [Create an interview from an array of questions](https://developer.jobmojito.com/api-reference/interviews/create-an-interview-from-an-array-of-questions.md): 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.
- [Create an interview for a candidate and return an access token URL](https://developer.jobmojito.com/api-reference/interviews/create-an-interview-for-a-candidate-and-return-an-access-token-url.md): Creates (or resolves an existing) position and interview for a merchant, enrols the candidate, runs pre-screening, and returns a tokenised interview URL. Position fields are required only when position_def_set_id is not provided.
- [Create a role-play — coaching persona or interview-portal role-play (choose with `portal`)](https://developer.jobmojito.com/api-reference/interviews/create-a-role-play-—-coaching-persona-or-interview-portal-role-play-choose-with-`portal`.md): 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…
- [Get interview definition](https://developer.jobmojito.com/api-reference/interviews/get-interview-definition.md): 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 s…
- [Update an interview or position](https://developer.jobmojito.com/api-reference/interviews/update-an-interview-or-position.md): 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…
- [Set interview state](https://developer.jobmojito.com/api-reference/interviews/set-interview-state.md): 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`.
- [Generate a signed interview URL](https://developer.jobmojito.com/api-reference/interviews/generate-a-signed-interview-url.md): Generates a public, token-signed URL for an existing interview, profile, or result. The required id fields depend on `type`.
- [Register users for an interview](https://developer.jobmojito.com/api-reference/interviews/register-users-for-an-interview.md): 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).
- [List interview definitions](https://developer.jobmojito.com/api-reference/interviews/list-interview-definitions.md): 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.
- [Create a coaching catalogue directory](https://developer.jobmojito.com/api-reference/coaching-catalogue/create-a-coaching-catalogue-directory.md): 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…
- [Update a coaching catalogue directory](https://developer.jobmojito.com/api-reference/coaching-catalogue/update-a-coaching-catalogue-directory.md): 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-o…
- [Get a coaching catalogue directory](https://developer.jobmojito.com/api-reference/coaching-catalogue/get-a-coaching-catalogue-directory.md): 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…
- [List coaching catalogue directories](https://developer.jobmojito.com/api-reference/coaching-catalogue/list-coaching-catalogue-directories.md): 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 pa…
- [Get interview result details with transcript](https://developer.jobmojito.com/api-reference/results/get-interview-result-details-with-transcript.md): Returns an interview result with its full transcript and AI assessment. Optionally attaches signed recording URLs.
- [Generate an interview report](https://developer.jobmojito.com/api-reference/results/generate-an-interview-report.md): 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.
- [Request another interview attempt](https://developer.jobmojito.com/api-reference/results/request-another-interview-attempt.md): 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.
- [List interview results](https://developer.jobmojito.com/api-reference/results/list-interview-results.md): 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.
- [Get daily event analytics](https://developer.jobmojito.com/api-reference/results/get-daily-event-analytics.md): 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 ar…
- [Get merchant credit usage](https://developer.jobmojito.com/api-reference/results/get-merchant-credit-usage.md): 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…
- [List candidates](https://developer.jobmojito.com/api-reference/candidates/list-candidates.md): 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.
- [Upload a knowledge base document](https://developer.jobmojito.com/api-reference/knowledge-base/upload-a-knowledge-base-document.md): 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`).
- [Create or update a pre-screening position](https://developer.jobmojito.com/api-reference/resume-&-form-verification/create-or-update-a-pre-screening-position.md): Creates a new pre-screening position (and optionally activates it) or, when update_position_def_set_id is provided, updates an existing pre-screening position. Only merchant_owner, merchant, or admin users may call this.
- [Run pre-screening on a plaintext resume](https://developer.jobmojito.com/api-reference/resume-&-form-verification/run-pre-screening-on-a-plaintext-resume.md): Stores a plaintext candidate resume, runs AI pre-screening against the position definition, records the result and returns the AI recommendation and analysis. If the candidate is not in the pre-screening candidate_action state, an early `{ decision_status, message }` object is returned with HTTP 200…
- [Pre-screen a candidate from a binary resume upload](https://developer.jobmojito.com/api-reference/resume-&-form-verification/pre-screen-a-candidate-from-a-binary-resume-upload.md): Accepts a multipart/form-data upload with candidate details and a binary resume file, converts the resume to text, runs AI pre-screening against the position, stores the result, and returns the decision.
- [Invite admin / merchant-team or coaching users](https://developer.jobmojito.com/api-reference/admin/invite-admin-merchant-team-or-coaching-users.md): Invites people to a merchant account and emails each one an invitation. Use it to add **admin / merchant-team users** who manage the recruiting dashboard (`merchant_owner`, `merchant`, `merchant_selection`), **coaching-portal users** (`user`, `mentor`), or **interview candidates** (`candidate`). Can…
- [List sub-merchants](https://developer.jobmojito.com/api-reference/admin/list-sub-merchants.md): 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.
- [List avatar templates](https://developer.jobmojito.com/api-reference/admin/list-avatar-templates.md): 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.
- [Get merchant status](https://developer.jobmojito.com/api-reference/admin/get-merchant-status.md): 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-…
- [List platform languages](https://developer.jobmojito.com/api-reference/admin/list-platform-languages.md): 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.
- [Interview result submitted](https://developer.jobmojito.com/api-reference/webhooks/interview-result-submitted.md): Sent when an interview or assessment is submitted by the candidate (the result is finalized and AI-scored). If the interview is configured to generate a PDF report, this event is delayed until the report is ready so `pdf_export_url` is included. Also re-sent when a result field changes afterwards (s…
- [Interview answers collected](https://developer.jobmojito.com/api-reference/webhooks/interview-answers-collected.md): Sent when the candidate finishes the interview and their raw answers are collected, before final AI scoring.
- [Interview failed](https://developer.jobmojito.com/api-reference/webhooks/interview-failed.md): Sent when an interview does not complete successfully — failed, abandoned, or terminated with no speech detected. The scoring and AI-analysis fields (score, ai_analysis*, ai_analysis_recruiter_score, recruiter decision, pdf_export_url) are typically empty/null for this event, since the interview did…
- [Overview](https://developer.jobmojito.com/cookbooks.md): Task-oriented, end-to-end guides for the most common JobMojito workflows.
- [Invite candidates](https://developer.jobmojito.com/cookbooks/invite-candidates.md): Generate signed interview links or send branded email invitations for an interview.
- [Create an interview](https://developer.jobmojito.com/cookbooks/create-an-interview.md): Generate an AI interview from a job position, from your own questions, or in one shot for a candidate.
- [Review results](https://developer.jobmojito.com/cookbooks/review-results.md): List completed interviews, read full transcripts and AI assessments, and export reports.
- [Pre-screen candidates](https://developer.jobmojito.com/cookbooks/pre-screen-candidates.md): Score a résumé against a position before inviting the candidate to a full interview.
- [Manage knowledge base](https://developer.jobmojito.com/cookbooks/manage-knowledge-base.md): Upload documents so interviews can ask grounded, knowledge-based questions.
- [Build a coaching catalogue](https://developer.jobmojito.com/cookbooks/build-a-coaching-catalogue.md): Organise the coaching portal into directories, place coaching sessions and personas into them with tags, and author custom directory pages.
- [Edit interview questions](https://developer.jobmojito.com/cookbooks/edit-interview-questions.md): Read an interview's question list, change it, and send it back — without disturbing the questions you did not touch.
- [Interview and pre-screening workflows](https://developer.jobmojito.com/cookbooks/workflows.md)
- [Branding](https://developer.jobmojito.com/cookbooks/portal-customisation/branding.md)
- [Interview portal](https://developer.jobmojito.com/cookbooks/portal-customisation/interview-portal.md)
- [Coaching portal](https://developer.jobmojito.com/cookbooks/portal-customisation/coaching-portal.md)
- [Format content with Markdown](https://developer.jobmojito.com/cookbooks/format-content-with-markdown.md): The Markdown vocabulary JobMojito renders — headings, tables, code, plus chips, callouts, cards, columns and buttons.
- [Skills](https://developer.jobmojito.com/skills/overview.md): Reusable patterns (skills) for driving JobMojito from AI assistants — the docs-first loop, merchant selection, safe writes, and reliable multi-step workflows.
- [JobMojito MCP server](https://developer.jobmojito.com/mcp/overview.md): Connect an AI agent to JobMojito over the Model Context Protocol (MCP): endpoint, Supabase OAuth sign-in, and merchant scoping.
- [MCP tools reference](https://developer.jobmojito.com/mcp/tools.md): The JobMojito MCP tool inventory by category, how to build admin UI deep-links, and the docs-first calling pattern agents should follow.
- [Identifiers & admin links](https://developer.jobmojito.com/mcp/identifiers.md): What each JobMojito id means, where to get it, why the same interview id has different field names on different endpoints, and how to build admin app links.
- [Responsible use](https://developer.jobmojito.com/mcp/responsible-use.md): How JobMojito's AI output should be used in hiring: human review before decisions, disclosure to candidates, and what the platform will not do.
- [Data & privacy](https://developer.jobmojito.com/mcp/data-and-privacy.md): What the JobMojito MCP tools can reach, what is visible before sign-in, where candidate data goes, and how retention and logging work.
- [Connect Claude Code](https://developer.jobmojito.com/mcp/connect/claude-code.md): Add the JobMojito MCP server to Claude Code (CLI) and authorize it over OAuth.
- [Connect Claude Desktop](https://developer.jobmojito.com/mcp/connect/claude-desktop.md): Add JobMojito as a custom connector in the Claude desktop app and authorize it over OAuth.
- [Connect Claude (web)](https://developer.jobmojito.com/mcp/connect/claude-web.md): Add JobMojito as a custom connector on claude.ai and authorize it over OAuth.
- [Connect Cursor](https://developer.jobmojito.com/mcp/connect/cursor.md): Add the JobMojito MCP server to Cursor via mcp.json and authorize it over OAuth.
- [Connect Gemini CLI](https://developer.jobmojito.com/mcp/connect/gemini-cli.md): Add the JobMojito MCP server to the Gemini CLI and authorize it over OAuth.
- [Connect ChatGPT & OpenAI](https://developer.jobmojito.com/mcp/connect/openai.md): Use JobMojito as a connector in ChatGPT, or as a remote MCP tool from the OpenAI Responses API.
- [Connect VS Code](https://developer.jobmojito.com/mcp/connect/vscode.md): Add the JobMojito MCP server to VS Code (Copilot agent mode) and authorize it over OAuth.
- [Connect a custom agent (MCP SDK)](https://developer.jobmojito.com/mcp/connect/custom-agent.md): Connect any MCP-capable client or custom agent to JobMojito using an MCP SDK over Streamable HTTP with OAuth.

## OpenAPI Specs

- [openapi](https://cool.jobmojito.com/functions/v1/openapi)
- [openapi-webhooks](https://cool.jobmojito.com/functions/v1/openapi-webhooks)