# Organize output with path templates

Use dynamic paths to organize processed files by date, type, or ID

Dumping all output into a flat folder doesn't scale. Path templates let you route processed files into structured directories automatically.

"Prismatic" (a media agency like Bynder) manages video assets for dozens of clients. They use path templates to keep output organized by date, client, and format.

## API

Use template variables in the `output` path. Ittybit replaces them at processing time:

<CodeGroup labels={["CLI", "TypeScript", "Python", "curl"]}>
```bash
ittybit video \
  -i https://prismatic-agency.com/uploads/spot-tv-30s.mov \
  -o "s3://prismatic-output/processed/{date}/{filename}.mp4" \
  --width 1920 \
  --format mp4
```

```typescript
const task = {
  input: 'https://prismatic-agency.com/uploads/spot-tv-30s.mov',
  kind: 'video',
  options: {
    width: 1920,
    format: 'mp4',
  },
  output: 's3://prismatic-output/processed/{date}/{filename}.mp4',
};

const res = await fetch('https://api.ittybit.com/jobs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ITTYBIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(task),
});
const data = await res.json();
```

```python

task = {
    "input": "https://prismatic-agency.com/uploads/spot-tv-30s.mov",
    "kind": "video",
    "options": {
        "width": 1920,
        "format": "mp4",
    },
    "output": "s3://prismatic-output/processed/{date}/{filename}.mp4",
}

res = requests.post(
    "https://api.ittybit.com/jobs",
    headers={"Authorization": f"Bearer {api_key}"},
    json=task,
)
data = res.json()
```

```bash
TASK='{
  "input": "https://prismatic-agency.com/uploads/spot-tv-30s.mov",
  "kind": "video",
  "options": {
    "width": 1920,
    "format": "mp4"
  },
  "output": "s3://prismatic-output/processed/{date}/{filename}.mp4"
}'

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

</CodeGroup>

This produces a path like `s3://prismatic-output/processed/2026-04-03/spot-tv-30s.mp4`.

## CLI

```bash
ittybit video \
  -i spot-tv-30s.mov \
  -o "s3://prismatic-output/processed/{date}/{filename}.mp4" \
  --width 1920
```

## Template variables

| Variable     | Resolves to                      | Example       |
| ------------ | -------------------------------- | ------------- |
| `{filename}` | Input filename without extension | `spot-tv-30s` |
| `{ext}`      | Output file extension            | `mp4`         |
| `{format}`   | Output format                    | `mp4`         |
| `{date}`     | Processing date (YYYY-MM-DD)     | `2026-04-03`  |
| `{year}`     | Processing year                  | `2026`        |
| `{month}`    | Processing month (zero-padded)   | `04`          |
| `{day}`      | Processing day (zero-padded)     | `03`          |
| `{id}`       | Task ID                          | `task_abc123` |
| `{width}`    | Output width                     | `1920`        |
| `{height}`   | Output height                    | `1080`        |

## Common patterns

Organize by date:

```
s3://bucket/processed/{year}/{month}/{day}/{filename}.{ext}
-> s3://bucket/processed/2026/04/03/spot-tv-30s.mp4
```

Organize by format and resolution:

```
s3://bucket/{format}/{width}x{height}/{filename}.{ext}
-> s3://bucket/mp4/1920x1080/spot-tv-30s.mp4
```

Organize by task ID (guaranteed unique):

```
s3://bucket/output/{id}/{filename}.{ext}
-> s3://bucket/output/task_abc123/spot-tv-30s.mp4
```

## Multi-client structure

Combine templates with metadata to build per-client paths. Pass client info in the path directly:

<CodeGroup labels={["CLI", "TypeScript", "Python", "curl"]}>
```bash
ittybit video \
  -i https://prismatic-agency.com/uploads/acme-corp/spot-tv-30s.mov \
  -o "s3://prismatic-output/clients/acme-corp/{date}/{filename}.mp4" \
  --width 1920 \
  --format mp4
```

```typescript
const clientId = 'acme-corp';

const task = {
  input: `https://prismatic-agency.com/uploads/${clientId}/spot-tv-30s.mov`,
  kind: 'video',
  options: {
    width: 1920,
    format: 'mp4',
  },
  output: `s3://prismatic-output/clients/${clientId}/{date}/{filename}.mp4`,
};

const res = await fetch('https://api.ittybit.com/jobs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ITTYBIT_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(task),
});
const data = await res.json();
```

```python

client_id = "acme-corp"

task = {
    "input": f"https://prismatic-agency.com/uploads/{client_id}/spot-tv-30s.mov",
    "kind": "video",
    "options": {
        "width": 1920,
        "format": "mp4",
    },
    "output": f"s3://prismatic-output/clients/{client_id}/{{date}}/{{filename}}.mp4",
}

res = requests.post(
    "https://api.ittybit.com/jobs",
    headers={"Authorization": f"Bearer {api_key}"},
    json=task,
)
data = res.json()
```

```bash
TASK='{
  "input": "https://prismatic-agency.com/uploads/acme-corp/spot-tv-30s.mov",
  "kind": "video",
  "options": {
    "width": 1920,
    "format": "mp4"
  },
  "output": "s3://prismatic-output/clients/acme-corp/{date}/{filename}.mp4"
}'

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

</CodeGroup>

## See also

- [Write output to S3](/guides/write-output-to-s3) -- set up S3 output connections
- [Write output to R2](/guides/write-output-to-r2) -- R2-specific output setup
- [Attach metadata to tasks](/guides/attach-metadata-to-tasks) -- tag tasks with custom key-value pairs