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
ittybit step probe \
  -i '{"url": "https://example.com/video.mp4"}' \
  --cloud

# 2. Encode using probe output as input
ittybit step video \
  -i '<probe_output>' \
  --width 720 \
  --cloud
// 1. Probe
const probeStep = {
  kind: "probe",
  input: { url: "https://example.com/video.mp4" },
};

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(probeStep),
});
const probeResult = await probe.json();

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

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(encodeStep),
});
const encodeResult = await encode.json();
import requests

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

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

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

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

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

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

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

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

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