export_create
Start exports and retrieve export artifacts. Use readiness for screenplay and shot-list exports to discover valid template IDs before start; screenplay exports default to script-only sections.
When to use
Use for screenplay, shot list, pitch deck, or season export workflows.
For `screenplay_export` and `shot_list_export`, call `phase=readiness` first; it returns `available_templates`, `default_template_id`, and a start payload.
Use `payload.options.sections=["screenplay"]` for a script-only screenplay PDF. The readiness start payload includes this by default for `screenplay_export`; pass `sections=["all"]` only when you intentionally want planning/bible sections included.
Export title and author currently come from project/user metadata: title from the project name, author from `user_profiles.name` with email fallback. Do not mutate databases directly just to change export cosmetics.
When not to use
Do not use for editing or generation flows.
Examples
“Check screenplay export readiness, then start the export with the returned `template_id` and `options.sections=["screenplay"]`.”
“Export a screenplay-only PDF with `workflow=screenplay_export`, `phase=start`, `payload.template_id` from readiness, and `payload.options={"format":"pdf_screenplay","sections":["screenplay"]}`.”
Anti-examples
- Apply this screenplay edit.
- Guess template IDs such as `pdf`, `fdx`, or `classic_hollywood`; use readiness to get numeric export template IDs.
- Export a clean script by calling the lower-level PDF exporter directly; first fix the screenplay document with `screenplay_snapshot_apply`/`screenplay_import_run`, then use `export_create`.
Workflows
Switch behavior by setting the workflow input field.
screenplay_export
shot_list_export
pitch_deck_export
season_export
Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase",
"project_id"
],
"properties": {
"workflow": {
"type": "string",
"enum": [
"screenplay_export",
"shot_list_export",
"pitch_deck_export",
"season_export"
]
},
"phase": {
"type": "string",
"enum": [
"readiness",
"start"
],
"description": "Use readiness first for screenplay_export and shot_list_export to discover available template IDs."
},
"project_id": {
"type": "integer"
},
"payload": {
"type": "object",
"properties": {
"template_id": {
"type": "integer",
"description": "Export template id from readiness. 0 means BeatBandit default config for the selected format."
},
"format": {
"type": "string",
"description": "Optional export format override such as pdf_screenplay, fountain, fdx, or shot_list_pdf."
},
"options": {
"type": "object",
"description": "Forwarded export options. For screenplay_export, use sections=[\"screenplay\"] for a script-only export; sections=[\"all\"] intentionally includes planning/bible sections. Export title/author are currently resolved from project/user metadata rather than custom options."
},
"episode_id": {
"type": "string"
}
},
"additionalProperties": false
}
},
"allOf": [
{
"if": {
"properties": {
"workflow": {
"enum": [
"pitch_deck_export",
"season_export"
]
},
"phase": {
"const": "readiness"
}
}
},
"then": false
},
{
"if": {
"properties": {
"workflow": {
"const": "season_export"
},
"phase": {
"const": "start"
}
}
},
"then": {
"required": [
"payload"
],
"properties": {
"payload": {
"required": [
"episode_id"
]
}
}
}
}
],
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": [
"workflow",
"phase"
],
"properties": {
"workflow": {
"type": "string"
},
"phase": {
"type": "string"
},
"project_id": {
"type": "integer"
},
"format": {
"type": "string"
},
"available_templates": {
"type": "array",
"items": {
"type": "object"
}
},
"default_template_id": {
"type": "integer"
},
"start_payload_template": {
"type": "object"
},
"result": {
"type": "object"
},
"credits_skipped_reason": {
"type": "string"
},
"next_actions": {
"type": "array",
"items": {
"$ref": "./_common/next_action.schema.json"
}
}
},
"additionalProperties": true
}