# BatchReel API — Agent Guide

A reference for an automated agent that uploads videos and schedules posts
through the BatchReel public API. BatchReel publishes to **YouTube, TikTok,
and Instagram** accounts the user has connected in the web app.

Fetch this document any time: `https://batchreel.com/docs/api`
(raw markdown). The slideshow generator has its own guide at
`https://batchreel.com/docs/slideshow-api` (admin-only feature). NatureVideos
(section 9) and ViralSplit (section 10) are admin-only and documented below.

---

## 1. Base URL & auth

- **Base URL:** `https://batchreel.com/api/v1`
- **Auth:** Sanctum bearer token on every request:

```
Authorization: Bearer <YOUR_TOKEN>
Accept: application/json
```

**Getting a token (human step):** sign in to BatchReel, open
**Settings → API** at `https://batchreel.com/settings/api`, create a token,
and copy the plaintext (it is shown once). Tokens do not expire; revoke them
from the same page.

Sanity check:

```bash
curl -sS https://batchreel.com/api/v1/me -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"
# {"id":7,"email":"you@example.com"}
```

## 2. Projects

Everything (connections, videos, posts) lives inside a **project**. If the
account has exactly one project you can omit `project_id` everywhere and it
is inferred. With more than one, pass `project_id` in the JSON body (POST) or
query string (GET) or you get a `422`.

```bash
GET /projects
```

```json
{
  "data": [
    { "id": 3, "name": "My First Project", "platforms": ["tiktok", "youtube"], "created_at": "2026-09-03T21:26:47+00:00" }
  ]
}
```

`platforms` lists what is connected, which is exactly the set of valid
`platforms` values for a post in that project.

## 3. Connections

```bash
GET /connections?project_id=3
```

```json
{ "project_id": 3, "data": [ { "platform": "tiktok", "display_name": "@creator" } ] }
```

Connecting or disconnecting a platform is done by the human in the web app
(`/connections`, OAuth). The API only reads them. Platform keys are
`youtube`, `tiktok`, `instagram`.

## 4. Videos

### Upload — `POST /videos`

Two ways. Both return `202 Accepted` with the video in `pending` /
`processing` state. **Poll until `status` is `ready` before scheduling.**

**a) URL ingest (JSON).** BatchReel downloads the file server-side. Best for
agents: no multipart handling, and the URL just needs to be publicly
fetchable (a presigned S3/Spaces link, a CDN URL, a direct download).

```bash
curl -sS -X POST https://batchreel.com/api/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{ "video_url": "https://example.com/clip.mp4", "title": "Morning routine", "project_id": 3 }'
```

Optional on both forms: `"is_cta": true` tags the upload as a **CTA
(call-to-action) clip**. Tools that append a CTA to the end of a video
(NatureVideos below, plus the admin UGCTA/ViralSplit tools) only accept
videos carrying this tag. Likewise `"is_preroll": true` tags it as a
**preroll (intro) clip**; NatureVideos can play one *before* the narration
and only offers tagged videos. A video may carry both tags.

**b) Direct multipart upload.** Field `video`, max 500 MB, types
`video/mp4`, `video/quicktime`, `video/x-m4v`, `video/webm`.

```bash
curl -sS -X POST https://batchreel.com/api/v1/videos \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  -F "video=@clip.mp4" -F "title=Morning routine" -F "project_id=3"
```

Response (both):

```json
{ "data": { "id": 91, "title": "Morning routine", "status": "pending", "is_cta": false, "is_preroll": false, "duration_seconds": null, "width": null, "height": null, "size_bytes": null, "download_url": null, "poster_url": null, "urls_expire_at": null, "created_at": "2026-09-03T22:00:00+00:00" } }
```

### Poll — `GET /videos/{id}`

`status` is one of `pending`, `processing`, `ready`, `failed`. Poll every
5–10 s; a typical clip is `ready` within a minute. Once ready,
`duration_seconds`, `width`, and `height` are filled in. Vertical 9:16 video
(1080×1920) is what all three platforms want for short-form.

**Verifying the file.** Once `status` is `ready` the response also carries
`download_url` (the MP4, presigned, direct from storage) and `poster_url`
(a JPEG frame). Both are valid until `urls_expire_at` (~1 hour); fetch
`GET /videos/{id}` again for fresh links. Use them to confirm what was
actually stored — check size/duration, look at the poster, or pull the MP4
through a vision/video model — before promising a post is good.

```json
{ "data": { "id": 91, "title": "Morning routine", "status": "ready", "is_cta": false, "is_preroll": false, "duration_seconds": 14.2, "width": 1080, "height": 1920, "size_bytes": 4812390,
            "download_url": "https://batchreel.nyc3.digitaloceanspaces.com/videos/3/abc.mp4?X-Amz-...", "poster_url": "https://batchreel.nyc3.digitaloceanspaces.com/thumbs/3/91/poster.jpg?X-Amz-...", "urls_expire_at": "2026-09-14T11:00:00+00:00", "created_at": "2026-09-03T22:00:00+00:00" } }
```

### List — `GET /videos`

Paginated (50 per page, `?page=N`), newest first, standard Laravel
pagination envelope (`data`, `links`, `meta`). Filters combine:

| Query | Effect |
|-------|--------|
| `?cta=1` | Only CTA-tagged videos (what the CTA pickers accept). |
| `?preroll=1` | Only preroll-tagged videos (what the NatureVideos preroll picker accepts). |
| `?search=word` | Case-insensitive title contains `word`. |
| `?page=N` | Pagination. |

### Edit — `PATCH /videos/{id}`

Retroactively rename a video or flip its CTA / preroll tags. Send only the fields you
want to change. Returns the updated video.

```bash
curl -sS -X PATCH https://batchreel.com/api/v1/videos/91 \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{ "is_cta": true }'
```

| Field | Notes |
|-------|-------|
| `title` | string, ≤255. |
| `is_cta` | bool. `true` makes the video selectable as a CTA; `false` removes it from the pickers. |
| `is_preroll` | bool. `true` makes the video selectable as a NatureVideos preroll; `false` removes it. |

## 5. Posts (scheduling)

### Create — `POST /posts`

```bash
curl -sS -X POST https://batchreel.com/api/v1/posts \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{
    "project_id": 3,
    "video_id": 91,
    "platforms": ["tiktok", "youtube"],
    "title": "Morning routine",
    "caption": "How I start every day #routine #morning",
    "scheduled_at": "2026-09-05T09:00:00",
    "timezone": "America/Chicago",
    "tiktok_privacy_level": "PUBLIC_TO_EVERYONE",
    "tiktok_allow_comment": true
  }'
```

| Field | Notes |
|---|---|
| `video_id` | Required (unless `slideshow_id`). Must be `ready` and belong to the project. |
| `platforms` | Required, non-empty. Each value must be connected in the project. One post row fans out to one target per platform. |
| `title` | Optional, ≤255. Used as the YouTube title and TikTok photo title. |
| `caption` | Optional, ≤5000. YouTube description, TikTok/Instagram caption. Put hashtags here. |
| `scheduled_at` | Optional ISO 8601. With an offset it is taken literally; without one it is interpreted in `timezone`. Must be in the future. **Omit to publish at the next scheduler tick (~1 min).** |
| `timezone` | Optional IANA name. Defaults to the account's timezone. |
| `tiktok_draft` | Optional bool. `true` sends the video to the creator's TikTok inbox to finish in-app instead of publishing directly. |
| `tiktok_privacy_level` | `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY`. Omit to auto-pick the most public level the account allows. |
| `tiktok_allow_comment` / `tiktok_allow_duet` / `tiktok_allow_stitch` | Bools, default `false` (TikTok requires explicit opt-in). Set them if you want interactions on. |
| `tiktok_brand_organic` / `tiktok_brand_content` | Commercial-content disclosure bools, default `false`. `brand_content` cannot combine with `SELF_ONLY` (422). |

Response `201 Created`:

```json
{
  "data": {
    "id": 120, "project_id": 3, "type": "video", "video_id": 91, "slideshow_id": null,
    "title": "Morning routine", "caption": "How I start every day #routine #morning",
    "tiktok_draft": false,
    "tiktok": { "privacy_level": "PUBLIC_TO_EVERYONE", "allow_comment": true, "allow_duet": false, "allow_stitch": false, "brand_organic": false, "brand_content": false },
    "scheduled_at": "2026-09-05T14:00:00+00:00", "timezone": "America/Chicago",
    "status": "pending",
    "targets": [
      { "platform": "tiktok",  "status": "pending", "platform_post_id": null, "error": null, "published_at": null },
      { "platform": "youtube", "status": "pending", "platform_post_id": null, "error": null, "published_at": null }
    ]
  }
}
```

### Poll — `GET /posts/{id}`

- Post `status`: `pending` → `completed` | `partial` | `failed` (rolled up from targets).
- Target `status`: `pending` → `publishing` → `published` | `failed`. On `published`, `platform_post_id` is the ID on the platform. On `failed`, `error` says why (token expired, platform rejected the file, rate limit). TikTok pull failures are retried automatically up to 3 times before a target is marked failed.

Publishing starts at the scheduled time, so there is nothing to poll until then. After it, poll every 30–60 s; most targets finish within a few minutes.

### List — `GET /posts`

Paginated (50 per page), newest scheduled first, includes `targets`.

### Cancel — `DELETE /posts/{id}`

Only while the post is still `pending`. Returns `{"deleted": true}`; `422`
once publishing has started.

## 6. Account limits

Regular accounts have hard caps that protect the shared platform apps from
rate limiting. Exceeding one returns a `422` with the reason under the
relevant field, and nothing is created.

| Limit | Value | Error field |
|---|---|---|
| Connected platform accounts | 2 per account, across all projects | (web app only) |
| Posts per platform | 1 per platform per calendar day, in the post's `timezone` | `platforms` |
| Video uploads | 5 per rolling 24 hours (URL ingest counts) | `video` |

Practical consequence: **for each platform, schedule at most one post per
day, and spread a batch across days.** A `failed` target frees that day back
up. Before scheduling, `GET /posts` and check what is already on the target
day rather than discovering it through 422s.

## 7. Errors

| Code | Meaning |
|---|---|
| `401` | Missing or invalid bearer token. |
| `404` | Resource does not exist or belongs to another account. Admin-only endpoints also 404 for regular tokens. |
| `422` | Validation failed. Body: `{"message": "...", "errors": {"field": ["..."]}}`. Read `errors` and fix the request; retrying unchanged will fail again. |
| `429` | Too many requests. Back off and retry. |

## 8. End-to-end recipe (plain upload)

1. `GET /projects` → pick `project_id`, note `platforms`.
2. `POST /videos` with `video_url` → get `video.id`.
3. Poll `GET /videos/{id}` until `status == "ready"` (fail if `failed`).
4. `GET /posts` to see what is already scheduled on the intended day for each platform.
5. `POST /posts` with `video_id`, `platforms`, copy, `scheduled_at` + `timezone`, and explicit TikTok settings.
6. After the scheduled time, poll `GET /posts/{id}` until every target is `published` or `failed`; surface `error` text for failures.

## 9. NatureVideos (admin-only)

Narrated text-to-video: xAI text-to-speech reads your script, word-by-word
captions burn on top of stock nature footage (1080×1920, 30 fps), and the
finished MP4 lands in the project's video library as a normal video you can
schedule with `POST /posts`. Optionally a **preroll clip** plays before the
narration and/or a **CTA clip** is appended after it (order: preroll →
narration → CTA). Regular tokens get `404` on these routes.

### Options — `GET /nature-videos/options`

Returns the valid values for a create request, so you never have to guess:

```json
{
  "voices": { "leo": "Leo", "zagan": "Zagan" },
  "fonts": { "montserrat": "Montserrat", "...": "..." },
  "themes": ["forest", "mountains", "ocean", "..."],
  "cta_videos": [ { "id": 91, "title": "Download the app" } ],
  "preroll_videos": [ { "id": 88, "title": "Channel intro" } ]
}
```

`cta_videos` is the project's CTA-tagged library (`GET /videos?cta=1`) and
`preroll_videos` the preroll-tagged one (`GET /videos?preroll=1`). If the
clip you want is missing, tag it first with `PATCH /videos/{id}`
`{"is_cta": true}` or `{"is_preroll": true}`.

### Create — `POST /nature-videos`

```bash
curl -sS -X POST https://batchreel.com/api/v1/nature-videos \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{
    "script": "Every morning is a fresh page. Write something worth reading.",
    "voice": "leo",
    "font": "montserrat",
    "theme": "forest",
    "preroll_video_id": 88,
    "mute_preroll_audio": false,
    "cta_video_id": 91,
    "mute_cta_audio": false,
    "title": "Fresh page",
    "project_id": 3
  }'
```

| Field | Type | Notes |
|-------|------|-------|
| `script` | string, **required** | The exact words spoken and captioned (≤100k chars). Roughly 2.5 words/second of video. |
| `voice` | string, optional | Key from `options.voices`. Default `leo`. |
| `font` | string, optional | Key from `options.fonts`. Default `montserrat`. |
| `theme` | string, optional | One of `options.themes`. Omit for a random mix of all footage. |
| `preroll_video_id` | int, optional | A **preroll-tagged**, `ready` video in this project, played before the narration (letterboxed to 9:16 if needed). Untagged videos are rejected with `422`. Remembered as the project's default preroll. |
| `mute_preroll_audio` | bool, optional | Default `false`. `true` silences the preroll segment. |
| `cta_video_id` | int, optional | A **CTA-tagged**, `ready` video in this project, appended after the narration (letterboxed to 9:16 if needed). Untagged videos are rejected with `422`. Remembered as the project's default CTA. |
| `mute_cta_audio` | bool, optional | Default `false`. `true` silences the CTA segment. |
| `title` | string, optional | Library title; auto-named from the script if blank. |
| `project_id` | int, optional | Required only if the account has multiple projects. |

Response — `202 Accepted`:

```json
{ "data": { "id": 14, "title": "Fresh page", "status": "pending", "error": null, "voice": "leo", "font": "montserrat", "theme": "forest", "cta_video_id": 91, "mute_cta_audio": false, "preroll_video_id": 88, "mute_preroll_audio": false, "duration_seconds": null, "video_id": 133, "video": { "id": 133, "status": "pending", "is_cta": false, "...": "..." }, "created_at": "2026-09-13T10:00:00+00:00" } }
```

### Poll — `GET /nature-videos/{id}`

`status` moves `pending` → `speaking` → `composing` → `ready` (or `failed`,
with `error` text). Poll every 10–15 s; a 30-second script typically takes
1–3 minutes. When `ready`, `video_id` is a library video whose own `status`
becomes `ready` shortly after (thumbnails). Then schedule it exactly like an
upload: `POST /posts` with that `video_id`.

### List — `GET /nature-videos`

Paginated (50 per page), newest first.

### Recipe

1. `GET /videos?cta=1` — pick the CTA, or `PATCH /videos/{id}` `{"is_cta": true}` to tag one.
   Same for an intro: `GET /videos?preroll=1`, or tag with `{"is_preroll": true}`.
2. `GET /nature-videos/options` — confirm voice/font/theme keys.
3. `POST /nature-videos` — note `id` and `video_id`.
4. Poll `GET /nature-videos/{id}` until `status == "ready"`.
5. Poll `GET /videos/{video_id}` until `status == "ready"`, then `POST /posts`.

## 10. ViralSplit (admin-only)

Takes ripped clips from an admin-curated channel pool, appends your CTA to
each, and schedules one post per clip across a posting cadence — all in one
call. Each clip is used at most once per project. Regular tokens get `404`.

### Channels — `GET /viralsplit/channels`

```json
{ "data": [ { "name": "Some Channel", "total": 40, "available": 27, "poster": "https://...jpg?X-Amz-..." } ] }
```

`available` is how many clips this project has not used yet. Pick a
channel with `available >= count`, or accept fewer (the response `meta`
says how many were actually scheduled).

### Schedule — `POST /viralsplit/schedule`

```bash
curl -sS -X POST https://batchreel.com/api/v1/viralsplit/schedule \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{
    "channel": "Some Channel",
    "cta_video_id": 91,
    "count": 5,
    "platforms": ["tiktok", "instagram"],
    "titles": ["Wait for the ending", "You won't believe this", "POV: it actually worked"],
    "captions": ["Link in bio for the full story", "Follow for more like this", "Which one are you? Comment below"],
    "mute_cta_audio": false,
    "tiktok_draft": false,
    "interval_days": 1,
    "window_start": "09:00",
    "window_end": "21:00",
    "start_date": "2026-09-15",
    "timezone": "America/New_York",
    "project_id": 3
  }'
```

| Field | Type | Notes |
|-------|------|-------|
| `channel` | string, **required** | A `name` from `GET /viralsplit/channels`. |
| `cta_video_id` | int, **required** | A **CTA-tagged**, `ready` video in this project (`GET /videos?cta=1`). Untagged → `422`. Remembered as the project default. |
| `count` | int, **required** | 1–20 videos to make. Capped by the channel's `available` for this project. |
| `platforms` | string[], **required** | Subset of the project's connected platforms (`GET /projects`). |
| `title` | string, optional | One title for every post. Defaults to the source clip's title. |
| `caption` | string, optional | One caption for every post (≤5000). |
| `titles` | string[], optional | **Preferred.** Per-post titles (≤20, each ≤255). Post *i* gets `titles[i % len]`, so a list shorter than `count` cycles. Overrides `title`. |
| `captions` | string[], optional | **Preferred.** Per-post captions (≤20, each ≤5000), rotated the same way. Overrides `caption`. |
| `mute_cta_audio` | bool, optional | Silence the CTA segment; the clip keeps its own audio. Default `false`. |
| `tiktok_draft` | bool, optional | Send TikTok targets to the user's inbox as drafts instead of publishing. Default `false`. |
| `interval_days` | int, **required** | Days between posts: `1`, `2`, `3`, or `7`. |
| `window_start` / `window_end` | `HH:MM`, **required** | Local daily window; each post gets a random time inside it. |
| `start_date` | `YYYY-MM-DD`, **required** | First posting day (local). Days whose window has already passed are skipped. |
| `timezone` | string, **required** | IANA zone for the window and start date. |
| `project_id` | int, optional | Required only if the account has multiple projects. |

**Vary the copy.** Posting the same title and caption on 5–20 videos in a
row is a strong bot signal on TikTok/Instagram/YouTube and can get a batch
throttled or the account flagged. Always send `titles` and `captions` with
`count` distinct entries (write them yourself — different hooks, different
CTAs, different hashtags, natural length variation). Only fall back to the
single `title`/`caption` fields when the human explicitly wants identical
copy. Empty strings in the lists are dropped before rotation.

Response — `201 Created`: the scheduled posts (same shape as `GET /posts`),
plus `meta`:

```json
{ "data": [ { "id": 140, "video_id": 133, "status": "pending", "scheduled_at": "2026-09-15T14:12:00+00:00", "targets": [ ... ] } ],
  "meta": { "requested": 5, "scheduled": 5, "video_ids": [133, 134, 135, 136, 137] } }
```

The composed videos start as `pending` and are built in the background;
publishing waits for them. To verify before the first post goes out, poll
`GET /videos/{video_id}` for each id in `meta.video_ids` until `ready` and
inspect `download_url` / `poster_url`. Then track each post with
`GET /posts/{id}`.
