MCP / Tools / Shot / Media / Export / export_create

export_create

exportbetaauth: export:readapproval: suggeststatus: v1

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

Present the returned open_url for retained document exports. It opens BeatBandit's download page with normal website sign-in; API download URLs alone are not browser links.
Use for screenplay, Novel manuscript, 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.
For `novel_export`, call `phase=readiness` first; it reports empty/stale Chapters and the four Novel format templates. When Chapters are empty, readiness returns `options.allow_in_progress=false` and no executable start action. After the author explicitly chooses an in-progress export, rerun readiness with `payload.options.allow_in_progress=true` to receive the start action.
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"]}`.”
“After the author confirms an in-progress Novel EPUB, rerun readiness with `payload.options.allow_in_progress=true`, then use its returned start action.”

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.

Workflow	Phases	Calls
`screenplay_export`	readiness, start	`export.create`
`shot_list_export`	readiness, start	`export.create`
`novel_export`	readiness, start	`export.create`
`pitch_deck_export`	start	`export.create`
`season_export`	start	`export.create`

Input schema

export_create input

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": [
    "workflow",
    "phase",
    "project_id"
  ],
  "properties": {
    "workflow": {
      "type": "string",
      "enum": [
        "screenplay_export",
        "novel_export",
        "shot_list_export",
        "pitch_deck_export",
        "season_export"
      ]
    },
    "phase": {
      "type": "string",
      "enum": [
        "readiness",
        "start"
      ],
      "description": "Use readiness first for screenplay_export, novel_export, and shot_list_export to discover available template IDs and readiness constraints."
    },
    "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"
        },
        "slides": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Pitch deck slides to export."
        },
        "structure_key": {
          "type": "string"
        },
        "include_storyline_context": {
          "type": "boolean"
        },
        "project_name": {
          "type": "string"
        },
        "idempotency_key": {
          "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

export_create output

{
  "$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
}