Sign in
Spreadsheets

Submit Spreadsheet Processing Job

Submit a natural language prompt to process a spreadsheet. Optionally provide an initial Excel file and context files.

post/api/spreadsheets

Request body

promptstring required

Natural language task description

initFilestring uuid

Optional File ID for initial Excel file

contextFilesstring[]

Optional File IDs for additional context files

webhookUrlstring uri

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>.

mode'action' | 'ask'

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

modelstring

Optional ShortcutXL model id or model pattern for this job

thinking'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'

Optional ShortcutXL thinking/effort level for this job

runtimeModelOverlayobject

Versioned ShortcutXL runtime model overlay, carried opaquely to the runtime

preferCurrentModelForSubagentsboolean
subagentModelstring
projectIdstring uuid

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

skillsstring[]

Optional source-qualified skill IDs to apply to this job. Use GET /api/spreadsheets/skills and submit returned id values such as default:commit, personal:my-skill, or team:{teamId}:team-skill. Submit-time validation checks id shape and team authorization, but does not perform a GCS existence check. Passing one skill is recommended — combining multiple skills may produce unpredictable results.

Response

Default Response

runIdstring required

Unique run identifier

status'queued' | 'running' required

Initial job status

Changes