Create Step

POST /steps

Creates a standalone step — a single operation without a parent task. Steps 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 step.

Request body

FieldTypeRequiredDescription
kindstringyesprobe · ingest · video · audio · image · adaptive_video · upload
inputobjectyesShape depends on kind
optionsobjectnoProcessing options

Input by kind

probe / ingest — minimum is {"url": "..."}:

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

video / audio / image — requires a Source object from a prior probe:

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

upload — push to S3:

{
  "kind": "upload",
  "input": {"object": "source", "url": "...", "kind": "video", "format": "mp4"},
  "options": {"url": "s3://bucket/output.mp4", "connection_id": "conn_abc123"}
}

Response 201

{
  "id": "step_abc123",
  "object": "step",
  "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 steps

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

# 1. Probe
curl -s -X POST https://api.ittybit.com/steps \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "probe", "input": {"url": "https://example.com/video.mp4"}}'

# 2. Encode using probe output as input
curl -X POST https://api.ittybit.com/steps \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "video", "input": <probe_output>, "options": {"width": 720}}'
// 1. Probe
const probe = await fetch("https://api.ittybit.com/steps", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    kind: "probe",
    input: { url: "https://example.com/video.mp4" },
  }),
});
const probeResult = await probe.json();

// 2. Encode using probe output as input
const encode = await fetch("https://api.ittybit.com/steps", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    kind: "video",
    input: probeResult.output,
    options: { width: 720 },
  }),
});
const encodeResult = await encode.json();
import requests

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

# 1. Probe
probe = requests.post(
    "https://api.ittybit.com/steps",
    headers=headers,
    json={"kind": "probe", "input": {"url": "https://example.com/video.mp4"}},
)
probe_result = probe.json()

# 2. Encode using probe output as input
encode = requests.post(
    "https://api.ittybit.com/steps",
    headers=headers,
    json={
        "kind": "video",
        "input": probe_result["output"],
        "options": {"width": 720},
    },
)
encode_result = encode.json()

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

See also

  • Create Task — run a full pipeline (probe + ingest + encode + upload) in one call
  • CLI step — run steps locally from the command line
  • Get Task — tasks also contain steps, viewable after creation