Submit Idempotent Spreadsheet Processing Job

Natural language task description

Optional File ID for initial Excel file

What to do with the result of a workbook run. "none" (default) only makes the result downloadable. "review" stores the baseline, result and a manifest in the review folder so the changes can be reviewed and merged. "auto" overwrites the workspace workbook if it is unchanged since the baseline and its filename extension matches the result format; otherwise it falls back to "review" and reports a warning in apply.warnings. For XLSM inputs, unavailable macro-format repair (including restricted storage egress) can therefore produce review artifacts instead of an automatic overwrite.

Workspace-relative folder for review artifacts (baseline/result workbooks with format-dependent extensions, and review.json). Defaults to "platform-api/runs/<runId>". Only meaningful with apply "review" or "auto".

Attribute this run to an automation run, so history and credits roll up to it.

Optional URL to receive a POST callback when the job completes or fails. Requests are signed with your API key's webhook secret (see /verify) via X-Shortcut-Signature: sha256=<hmac-sha256>. Delivery is at least once with retries; deduplicate on the eventId body field (also X-Shortcut-Event-Id).

The conversation a Continue in Cloud handoff came from, so the same user can find its run from another device (GET /api/spreadsheets?sourceThreadId=).

Agent mode: "action" (default) reads and writes the spreadsheet, "ask" performs read-only analysis and review without modifying the spreadsheet

Optional ShortcutXL model id or model pattern for this job. Use GET /api/spreadsheets/models for the standard catalog and actual submission default.

Response speed; Fast and Ultrafast require an exact supported Shortcut model ID and Fast mode access. Ultrafast requires GPT-6 Astra and uses more credits

Optional ShortcutXL thinking/effort level for this job

Organization work reference for usage reporting. Independent of project file access.

Explicit workflow category for usage reporting, such as Tax or Working papers.

Optional Project ID whose source files are mounted read-only at /project. The writable /workspace mount remains the run-scoped file workspace.

Optional. When true, the run's agent sees every skill you can see in Shortcut (default, personal, and team skills, as listed by GET /api/spreadsheets/skills) as a catalog of names and descriptions, and reads a skill's instructions only if it decides to use one. The list is resolved when the run is dispatched, not at submit time, and grants no access beyond the skills the run can already read. It does not select or apply any skill; use skills to select one. Omitted or false keeps the default: only skills and built-in skills are available.

Optional. Save this run's agent conversation as one of your Shortcut conversations so it can be reopened from chat history. When the run completes, its status includes conversation: an available locator or unavailable. Omitted runs keep the default unsaved session.

Unique run identifier

Job status: "queued" or "running" for a new run; the current status when an Idempotency-Key replays an existing run

The automation run this run is attributed to, when one was supplied

Present when the Idempotency-Key matched an existing run: no new run was created and nothing was charged. The response also carries an Idempotent-Replayed: true header.

Present on a replay when the request body differs from the one that created the run. The original run is still returned.