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

# Create a task

> Submit a prompt to Ninja and start execution in the background.

Creates a new task and starts execution in the background. Returns immediately with a `taskId` and `pending` status.

## Request parameters

<ParamField body="prompt" type="string" required>
  The task prompt. Must be between 1 and 16,000 characters.
</ParamField>

<ParamField body="model" type="string" default="smart">
  The LLM model to use.

  | Value         | Description                                  |
  | ------------- | -------------------------------------------- |
  | `fast`        | Fastest and cheapest. Best for simple tasks. |
  | `smart`       | Balanced speed and quality. **(default)**    |
  | `super-smart` | Most capable. Best for complex reasoning.    |
</ParamField>

<ParamField body="resultSchema" type="object">
  Optional JSON Schema for structured output. When provided, the `result` field in the response will be a JSON object conforming to this schema. Must follow the [supported schema
  format](#result-schema-format). Maximum 5 KB when serialized.
</ParamField>

## Response fields

<ResponseField name="taskId" type="string" required>
  UUID of the created task. Use this to poll for results via the [get task result](/ninja/get-task-result) endpoint.
</ResponseField>

<ResponseField name="status" type="string" required>
  Always `pending` for newly created tasks.
</ResponseField>

<RequestExample>
  ```bash Simple task theme={null}
  curl -X POST https://ninja.new/v0/api/task \
    -H "Authorization: Bearer nsk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Find the top 3 competitors of Shopify",
      "model": "smart"
    }'
  ```

  ```bash Structured output theme={null}
  curl -X POST https://ninja.new/v0/api/task \
    -H "Authorization: Bearer nsk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Find the top 3 competitors of Shopify and their estimated annual revenue",
      "model": "smart",
      "resultSchema": {
        "type": "object",
        "properties": {
          "competitors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "estimatedAnnualRevenue": { "type": "string" }
              },
              "required": ["name", "estimatedAnnualRevenue"]
            }
          }
        },
        "required": ["competitors"]
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending"
  }
  ```
</ResponseExample>

***

## Result schema format

The `resultSchema` field must be a valid JSON Schema. The following features are **not** supported:

* `oneOf`, `anyOf`, `not`, `if`/`then`/`else`
* Numerical constraints (`minimum`, `maximum`, `multipleOf`)
* String length constraints (`minLength`, `maxLength`)
* Array length constraints (`minItems`, `maxItems`)
* Type arrays (e.g. `"type": ["string", "null"]`)

**Supported types:** `object`, `array`, `string`, `number`, `integer`, `boolean`

<Warning>The schema is validated at request time. An invalid schema returns `400 Bad Request`.</Warning>

**Example:**

```json theme={null}
{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "score": { "type": "number" }
  },
  "required": ["summary", "score"]
}
```