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

# Task Generation

> Generate tasks from tool definitions

**Base URL:** `https://rl-gym-api.collinear.ai`

Generate task bundles (instructions, rubrics, verifiers) from your tool definitions. Task generation is asynchronous — submit a job, poll for status, then download results.

> **Authentication required.** Task generation endpoints use the `/v1/` prefix and require the `API-Key` header.

## Submit a Task Generation Job

```
POST /v1/task-gen
```

**Request body:**

```json theme={null}
{
  "toolset": [
    {
      "name": "send_email",
      "description": "Send an email to the specified recipient.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "to": { "type": "string" },
          "subject": { "type": "string" },
          "body": { "type": "string" }
        },
        "required": ["to", "subject", "body"]
      }
    }
  ],
  "num_tasks": 10,
  "model": "claude-sonnet-4-6",
  "preset": "recruiting",
  "complexity": { "easy": 0.3, "medium": 0.5, "hard": 0.2 }
}
```

| Field        | Type           | Required | Description                                                                                                                |
| ------------ | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `toolset`    | `list[object]` | Yes      | MCP tool definitions (JSON from a `/tools` endpoint). Each object should include `name`, `description`, and `inputSchema`. |
| `num_tasks`  | `int`          | No       | Number of tasks to generate (default: 10, max: 200)                                                                        |
| `model`      | `string`       | No       | Any OpenAI-compatible model identifier (default: `claude-sonnet-4-6`)                                                      |
| `preset`     | `string`       | No       | Built-in preset (e.g. `"recruiting"`) — auto-fills agent, scenario, workflows                                              |
| `agent`      | `object`       | No       | Agent identity: `{ "role": "...", "description": "..." }`                                                                  |
| `scenario`   | `object`       | No       | Scenario context: `{ "name": "...", "role_label": "...", "conventions": "...", "policies": [...] }`                        |
| `categories` | `list[object]` | No       | Task categories: `[{ "id": "...", "label": "..." }]`                                                                       |
| `workflows`  | `list[object]` | No       | Example workflows: `[{ "name": "...", "steps": ["..."] }]`                                                                 |
| `npcs`       | `list[object]` | No       | NPC roles: `[{ "role": "...", "typical_asks": "..." }]`                                                                    |
| `workspace`  | `object`       | No       | Workspace branding: `{ "email_domain": "...", "agent_email": "..." }`                                                      |
| `complexity` | `object`       | No       | Difficulty distribution: `{ "easy": 0.3, "medium": 0.5, "hard": 0.2 }`                                                     |
| `diversity`  | `object`       | No       | Diversity config for scenario variations                                                                                   |

**Response:** `200 OK`

```json theme={null}
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "progress": null,
  "created_at": "2026-03-07T06:20:00Z"
}
```

## Check Job Status

```
GET /v1/task-gen/{job_id}
```

**Response:** `200 OK`

```json theme={null}
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "progress": "Step 4/10: formatting tasks",
  "created_at": "2026-03-07T06:20:00Z"
}
```

| Status      | Meaning                               |
| ----------- | ------------------------------------- |
| `pending`   | Job queued, not yet started           |
| `running`   | Generation in progress                |
| `completed` | Results ready for download            |
| `failed`    | Generation failed (see `error` field) |

## Download Results

```
GET /v1/task-gen/{job_id}/results
```

**Response:** `200 OK` (only when status is `completed`)

```json theme={null}
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tasks": [
    { "filename": "task_001.json", "content": "{ ... }" }
  ],
  "instructions": [
    { "filename": "task_001_instruction.md", "content": "..." }
  ],
  "rubrics": [
    { "filename": "task_001_rubric.md", "content": "..." }
  ],
  "verifiers": [
    { "filename": "task_001_verifier.py", "content": "..." }
  ],
  "skills_md": "# Skills\n\n..."
}
```

Returns `202` if the job is still running, `404` if not found, `500` if the job failed.

**CLI shortcut:**

```bash theme={null}
simlab tasks-gen run --config config.toml --num-tasks 10
```