Create a series

Creating a series in TwistCue is a five-step wizard. It’s the same flow whether you’re onboarding a new title or a spin-off: the only difference is what you pre-fill.

Prerequisites

• Role: content_manager or superadmin (permission catalog:write)
• A poster (2:3) and hero image (16:9) ready to upload, or you can add them later.
• The primary language of the show (EN, AR, or ID).

Where to start

Catalog → Series → New series (top-right button on the series list). The wizard opens with tabs across the top; you can jump back and forth but you can’t publish until every required field is filled.

Step 1: Metadata

Field	Type	Notes
Title (EN)	string, ≤120	The canonical title. Additional languages come in Step 2.
Slug	string, kebab-case, unique	Auto-generated from title but editable before first save. Immutable after publish.
Synopsis (EN)	string, ≤2000	Short blurb. Long-form marketing copy is a separate field on the series detail page later.
Genres	multi-select from /admin/genres	Drives For You rails.
Tropes	multi-select from /admin/tropes	Same idea, narrower buckets.
Cast	multi-select from /admin/cast	Feeds the cast-based rails and per-series performance.
Maturity	enum: general / teen / mature	Blocks some markets automatically (parental settings).
Market availability	multi-select ISO country codes	Empty = all launch markets (see Constants).

Step 2: Localization

Three tabs: EN / AR / ID. Each tab has:

• Localized title: required for any market that speaks that language.
• Localized synopsis: same.
• RTL preview on the AR tab: shows the exact layout the mobile app renders.

Caution

If you’re launching in Egypt or another AR-primary market, you must fill the AR tab before publishing. The publish workflow will refuse to move a series out of in_review while a target-market language is missing.

Step 3: Media

• Poster (2:3): home-rail hero image. Recommended 900×1350px, JPEG/WebP.
• Hero (16:9): feature banner. 1920×1080px.
• Trailer: optional; a video asset from the media library or a fresh direct upload (see Upload an episode video, the flow is identical).

Media uploads go straight to Cloudflare Stream (video) or Cloudflare Images (posters/hero) via a TUS resumable direct-upload URL: the admin API doesn’t proxy the bytes.

Step 4: Pricing

Field	Default	Meaning
Coin price per episode	30	Series-wide override. Blank = falls back to the market default → global default (30).
Free-episode count	3	How many leading episodes are free.
Free-passes count	5	Daily free passes attached to this series (rare per-series override; usually kept global).

Overrides here are stored in price_overrides with scope=series. Precedence for the mobile client at unlock time:

episode override → series override → market override → global default (30)

See Pricing overrides guide for the full resolution model.

Step 5: Schedule

Two choices:

1. Save as draft: status draft, invisible to mobile. No schedule set.
2. Schedule for publish: pick a datetime (UTC), status becomes scheduled. The publish-scheduler cron (runs every minute) flips it to published at the target time.

You can also drop-schedule episodes here in bulk (e.g. 2 episodes/week), but that’s usually easier from the series detail page after episodes exist.

What happens after Save

1. Series row created with status='draft' (or scheduled if you scheduled it).
2. AuditLog entry: action='series.create', before=null, after=full series JSON.
3. If a market/language combo is incomplete, the series detail page banner warns you.
4. Series shows up in Catalog → Series filtered by status.

Publish workflow after creation

stateDiagram-v2
    [*] --> draft
    draft --> in_review: submit for review
    in_review --> scheduled: schedule publish
    in_review --> published: publish now
    scheduled --> published: cron flips at run_at
    published --> archived: archive
    archived --> draft: restore
    draft --> [*]: delete (requires approval)

Only published series appear on mobile. archived retains data but is hidden.

Gotchas

• The slug is immutable after publish. You can rename the display title all you want, but the slug is baked into share URLs.
• Deleting a series requires approval. It’s a two-person action (catalog:delete + a second catalog:delete holder). Prefer archive.
• Publishing an incomplete localization is soft-blocked, not hard-blocked. The API will let a superadmin force-publish, but the audit log will flag incomplete_localization: [lang, ...] for finance.

API calls behind the wizard

Step	Endpoint
Create	POST /v1/admin/series
Update metadata / localization	PUT /v1/admin/series/:id
Attach media	PUT /v1/admin/series/:id/media
Workflow transition	POST /v1/admin/series/:id/workflow
Schedule	POST /v1/admin/schedules (ref_type=series)

Full details in API, Catalog and API, Publishing.