> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jobmojito.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How the API works

> Base URL, request and response format, error model, credits, and the full list of JobMojito API endpoints.

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

## Base URL

```text theme={null}
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](/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.

```bash theme={null}
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:

1. Create the test interview with `environment: "uat"`.
2. Register a `uat` webhook that points at your test system (for example your ATS sandbox).
3. Invite test candidates with `is_test: true` on [`job-interview-register-users`](/cookbooks/invite-candidates). 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:

```json theme={null}
{ "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:

```json theme={null}
[
  { "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](/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:

```text theme={null}
https://cool.jobmojito.com/functions/v1/openapi
```

Webhooks have their own spec:

```text theme={null}
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](https://cool.jobmojito.com/functions/v1/openapi).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.