How the API works - JobMojito Developer / Agent

The JobMojito API is a set of HTTPS endpoints. Calls are simple: POST a JSON body, get a JSON response.

Base URL

https://cool.jobmojito.com/functions/v1

A full endpoint URL is the base URL plus the endpoint path, e.g. https://cool.jobmojito.com/functions/v1/job-interview-create.

Conventions

Method: actions that create or change something use POST; read-only lookups and lists use GET (with parameters in the query string).
Auth: every request needs Authorization: Bearer <token> - see Authentication.
Request body: application/json (one endpoint, the binary resume upload, uses multipart/form-data).
Response body: application/json.
IDs: resources are identified by UUIDs.

curl https://cool.jobmojito.com/functions/v1/job-interview-create \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project manager",
    "location": "remote",
    "interview_template_id": "…",
    "mojito_language_code": "en",
    "status": "active",
    "type": "interview",
    "visibility": "merchant_public"
  }'

Environments and testing

Each interview has an environment: production (the default), uat, development or demo. You set it in the admin app (Interview ▸ Edit ▸ Custom integration ▸ Environment), or with the environment field on job-interview-update. Each webhook is also registered for one environment. When a result fires an event, it goes only to the webhooks whose environment matches the environment of that interview. Your API token plays no part in this routing. A typical test set-up:

Create the test interview with environment: "uat".
Register a uat webhook that points at your test system (for example your ATS sandbox).
Invite test candidates with is_test: true on job-interview-register-users. Test links work on draft interviews too, and their results are flagged as tests.

Test results go only to the test endpoint, and production webhooks never see them. Test interviews use credits like any other interview. For a fully separate set of users, interviews, API keys and webhooks, ask your account contact for a UAT sub-merchant next to your production merchant.

Errors

When a request fails, you get a non-2xx status and a JSON error envelope:

{ "error": "Field is required.", "name": "interview_template_id" }

error - a human-readable message.
name - present for field-level validation problems; the name of the offending field.

Status codes

Status	Meaning
`200`	Success.
`401`	Missing or invalid authentication.
`403`	Authenticated but not permitted.
`404`	Resource not found.
`409`	Conflict - the request can’t be applied in the current state.
`422`	Validation error (a field is missing or invalid).
`500`	Unexpected server error.

Batch endpoints return per-row results

Endpoints that act on a list - invite-users and job-interview-register-users - process each row independently and always return HTTP 200 with a results array. A bad row doesn’t fail the whole request; instead that row carries an error while the others succeed:

[
  { "email": "ok@example.com", "result": "ok", "interview_url": "https://…" },
  { "email": "bad", "result": "Error: Email address is not valid" }
]

Always inspect each row’s result field rather than relying on the HTTP status alone.

Credits

Some actions consume your account’s credits - for example creating an interview, running a pre-screen, or generating a PDF report. A few options add cost on top (e.g. translating a report to another language, or enabling full-session recording). Your current balance and usage are visible in the admin. See How credits work for per-action costs, plans and top-ups.

OpenAPI specification & MCP

The entire API is described by a machine-readable OpenAPI 3.1 document, which powers this reference and can be imported into your own tooling:

https://cool.jobmojito.com/functions/v1/openapi

Webhooks have their own spec:

https://cool.jobmojito.com/functions/v1/openapi-webhooks

Because the spec is OpenAPI, the API is also MCP-friendly - AI agents can discover and call the endpoints from the same definition. Each endpoint and field includes a description to guide automated use.

Endpoints

Interviews & assessments

Endpoint	Purpose
`POST /job-interview-create`	Create a new interview (AI-generated questions from a job description).
`POST /job-interview-create-from-array`	Create an interview from your own array of questions.
`POST /job-interview-create-for-candidate-with-token`	Create an interview for a candidate and get a ready-to-use access URL.
`GET /job-interview-get`	Fetch an interview definition, including its ordered `questions` array.
`POST /job-interview-update`	Update an existing interview / position — settings, and the question list when you send `questions`.
`POST /job-interview-set-state`	Change an interview’s lifecycle state and/or manage its iframe embed key.
`POST /job-interview-token`	Generate a signed interview URL.
`POST /job-interview-result-request-another-attempt`	Allow a candidate another attempt.

Coaching catalogue

Endpoint	Purpose
`GET /catalogue-tag-list`	List catalogue directories (search, filter, or walk the tree with `parent_tag`).
`GET /catalogue-tag-get`	Read one directory in full, with its content page and the sessions it lists.
`POST /catalogue-tag-create`	Create a directory (page) in the coaching portal catalogue.
`POST /catalogue-tag-update`	Update a catalogue directory, including its custom Markdown content page.

A directory lists a coaching session when the session’s tags contain every tag in the directory’s tags_interview_set_filter — so tags on the interview and tags_interview_set_filter on the directory are the two halves of the same mapping.

Candidates & invitations

Endpoint	Purpose
`POST /invite-users`	Invite users / candidates (batch, per-row results).
`POST /job-interview-register-users`	Register candidates for an interview and get their links (batch, per-row results).

Results & reports

Endpoint	Purpose
`GET /job-interview-details`	Get an interview result with full transcript and AI analysis.
`POST /job-interview-pdf`	Generate a branded PDF / HTML / JSON interview report.

Pre-screening

Endpoint	Purpose
`POST /pre-screening-create`	Create or update a pre-screening position.
`POST /job-interview-pre-screening-api-resume-text`	Pre-screen a candidate from a plaintext resume.
`POST /job-interview-pre-screening-api-resume-binary`	Pre-screen a candidate from an uploaded resume file.

Knowledge base

Endpoint	Purpose
`POST /knowledge-base-document-upload`	Upload a document the AI can draw questions/context from.

Merchant reads (lists & status)

Read-only endpoints scoped to the merchant from your token (or a merchant_id query parameter). Being reads, these use GET.

Endpoint	Purpose
`GET /merchant-interview-list`	List the merchant’s interview definitions.
`GET /merchant-candidate-list`	List candidates.
`GET /merchant-result-list`	List interview results.
`GET /merchant-avatar-list`	List available interviewer avatars.
`GET /merchant-sub-merchant-list`	List sub-merchants you manage.
`GET /merchant-analytics`	Daily event analytics.
`GET /merchant-status`	Status snapshot: credit balances, subscription, pending-work counts, candidate/result totals, invitation headroom.

See the API Reference for each endpoint’s exact request and response schema, or fetch the OpenAPI spec.

​Base URL

​Conventions

​Environments and testing

​Errors

​Status codes

​Batch endpoints return per-row results

​Credits

​OpenAPI specification & MCP

​Endpoints

​Interviews & assessments

​Coaching catalogue

​Candidates & invitations

​Results & reports

​Pre-screening

​Knowledge base

​Merchant reads (lists & status)