# Create Task


POST /tasks

```
POST /tasks
```

Creates a standalone task — a single operation without a parent job. Tasks give you granular control: probe a file to inspect it, then decide what to do next. This is how agents and custom workflows compose operations. For the CLI equivalent, see [`ittybit task`](/cli/task).

## Request body

| Field     | Type   | Required | Description                                                                                  |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `kind`    | string | yes      | `probe` · `import` · `video` · `audio` · `image` · `animation` · `adaptive_video` · `export` |
| `input`   | object | yes      | Shape depends on kind                                                                        |
| `options` | object | no       | Processing options                                                                           |

## Input by kind

**probe / import** — minimum is `{"url": "..."}`:

```json
{ "kind": "probe", "input": { "url": "https://example.com/video.mp4" } }
```

**video / audio / image / animation** — requires a File object from a prior probe:

```json
{
  "kind": "video",
  "input": {
    "object": "file",
    "url": "...",
    "kind": "video",
    "format": "mp4",
    "width": 1920,
    "height": 1080,
    "duration": 62.5,
    "codecs": { "video": "h264", "audio": "aac" }
  },
  "options": { "width": 720, "quality": "medium" }
}
```

**export** — push to S3:

```json
{
  "kind": "export",
  "input": { "object": "file", "url": "...", "kind": "video", "format": "mp4" },
  "options": { "url": "s3://bucket/output.mp4", "connection_id": "conn_abc123" }
}
```

## Response `201`

```json
{
  "id": "task_abc123",
  "object": "task",
  "kind": "probe",
  "input": { "object": "external_file", "url": "https://example.com/video.mp4" },
  "output": null,
  "options": {},
  "status": "waiting",
  "progress": null,
  "error": null,
  "created_at": 1711900000000,
  "started_at": null,
  "finished_at": null,
  "updated_at": 1711900000000
}
```

## Composing tasks

Output of one task feeds into the next. Probe a file, then encode:

<CodeGroup labels={["CLI", "TypeScript", "Python", "curl"]}>
```bash
# 1. Probe
ittybit task probe \
  -i '{"url": "https://example.com/video.mp4"}' \

# 2. Encode using probe output as input

ittybit task video \
 -i '<probe_output>' \
 --width 720 \

````

```typescript
// 1. Probe
const probeTask = {
  kind: "probe",
  input: { url: "https://example.com/video.mp4" },
};

const probe = await fetch("https://api.ittybit.com/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(probeTask),
});
const probeResult = await probe.json();

// 2. Encode using probe output as input
const encodeTask = {
  kind: "video",
  input: probeResult.output,
  options: {
    width: 720,
  },
};

const encode = await fetch("https://api.ittybit.com/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(encodeTask),
});
const encodeResult = await encode.json();
````

```python

headers = {"Authorization": f"Bearer {api_key}"}

# 1. Probe
probe_task = {
    "kind": "probe",
    "input": {"url": "https://example.com/video.mp4"},
}

probe = requests.post(
    "https://api.ittybit.com/tasks",
    headers=headers,
    json=probe_task,
)
probe_result = probe.json()

# 2. Encode using probe output as input
encode_task = {
    "kind": "video",
    "input": probe_result["output"],
    "options": {
        "width": 720,
    },
}

encode = requests.post(
    "https://api.ittybit.com/tasks",
    headers=headers,
    json=encode_task,
)
encode_result = encode.json()
```

```bash
# 1. Probe
TASK='{
  "kind": "probe",
  "input": {"url": "https://example.com/video.mp4"}
}'

curl -s -X POST https://api.ittybit.com/tasks \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$TASK"

# 2. Encode using probe output as input
TASK='{
  "kind": "video",
  "input": <probe_output>,
  "options": {
    "width": 720
  }
}'

curl -X POST https://api.ittybit.com/tasks \
  -H "Authorization: Bearer $ITTYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$TASK"
```

</CodeGroup>

This is how agents can inspect a file before deciding what to do with it.

## See also

- [Create Job](/api/create-job) — run a full pipeline (probe + import + encode + export) in one call
- [CLI `task`](/cli/task) — run tasks locally from the command line
- [Get Job](/api/get-job) — jobs also contain tasks, viewable after creation