> ## 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:** all endpoints use `POST`.
* **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

Resources (interviews, results, webhooks) are scoped to an **environment** so you can keep test data separate from live data. Your token determines the environment it operates in. Webhooks are also configured per environment, so a staging endpoint never receives production events. Talk to your account contact if you need a separate test environment.

## 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.    |
| `POST /job-interview-get`                             | Fetch an interview definition.                                            |
| `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.                                        |

### 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                                                       |
| ----------------------------- | ------------------------------------------------------------- |
| `POST /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. |

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