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

# Ninja API

> HTTP API for creating and executing Ninja tasks programmatically.

<Info>The Ninja API is currently in **beta**. Email [hey@molin.ai](mailto:hey@molin.ai) to request access and receive your API key.</Info>

The Ninja API lets you submit prompts to [Ninja](https://ninja.new), optionally define a structured output schema, and retrieve results — all over HTTP.

## Base URL

```
https://ninja.new
```

## Authentication

All requests require a Bearer token in the `Authorization` header. API keys are prefixed with `nsk_`.

```http theme={null}
Authorization: Bearer nsk_your_api_key_here
```

## Endpoints

<CardGroup cols={2}>
  <Card title="Create a task" icon="plus" href="/ninja/create-task">
    `POST /v0/api/task` — submit a prompt and start execution.
  </Card>

  <Card title="Get task result" icon="magnifying-glass" href="/ninja/get-task-result">
    `GET /v0/api/task/result` — retrieve status and result.
  </Card>
</CardGroup>

## Typical usage pattern

1. **Create a task** — `POST /v0/api/task` — save the returned `taskId`.
2. **Poll for result** — `GET /v0/api/task/result?taskId=...&wait=1`.
3. **If status is `pending`** — the task hasn't started yet. `wait=1` has no effect for `pending` tasks. Wait a short moment and poll again.
4. **If status is `in_progress`** — the long-poll is active and the request will block until the task completes. Poll again if the request times out.
5. **When status is `completed` or `failed`** — read the `result` or `error` field and stop polling.

***

## Task statuses

| Status           | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `pending`        | Task created, hasn't started yet.                        |
| `in_progress`    | Task is currently executing.                             |
| `completed`      | Task finished successfully. `result` is available.       |
| `failed`         | Task encountered an error. `error` contains the message. |
| `cancelled`      | Task was cancelled.                                      |
| `paused`         | Task is paused, waiting for user input.                  |
| `stopped`        | Task was stopped.                                        |
| `impossible`     | Task cannot be completed.                                |
| `out_of_credits` | User ran out of credits during execution.                |

***

## Execution limits

Each task has a maximum execution time of **30 minutes**. If the task does not complete within this window, it is automatically marked as `failed` with the error `Task timed out`.

## Rate limits

Both endpoints share a limit of **10 requests per minute** per user. Exceeding the rate limit returns `429 Too Many Requests`.

***

## Error responses

| Status code | Description                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------ |
| `400`       | Invalid request body or query parameters (e.g. prompt too long, invalid `resultSchema`, malformed `taskId`). |
| `401`       | Missing or invalid API key.                                                                                  |
| `404`       | Task not found or not owned by the authenticated user.                                                       |
| `429`       | Rate limit exceeded (10 req/min) or free-plan task quota exhausted.                                          |