---
title: "Submit Spreadsheet Processing Job"
method: POST
path: "/api/spreadsheets"
tags: ["Spreadsheets"]
---

# Submit Spreadsheet Processing Job

`POST /api/spreadsheets`

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

## Request body

- object
  - `prompt` string, required — Natural language task description
  - `initFile` string, uuid — Optional File ID for initial Excel file
  - `contextFiles` string[] — Optional File IDs for additional context files
  - `webhookUrl` string, 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
  - `model` string — 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
  - `runtimeModelOverlay` object — Versioned ShortcutXL runtime model overlay, carried opaquely to the runtime
  - `preferCurrentModelForSubagents` boolean
  - `subagentModel` string
  - `projectId` string, uuid — Optional Project ID whose source files are mounted read-only at /project. The writable /workspace mount remains the run-scoped file workspace.
  - `skills` string[] — 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.
  - `debug` union — Optional debug mode. When enabled, API-v1 periodically persists bounded runner/session debug snapshots while the sandbox run is still active.
    - boolean
    - object
      - `enabled` boolean
      - `snapshotIntervalMs` integer

## Response `200`

Default Response

- object
  - `runId` string, required — Unique run identifier
  - `status` 'queued' | 'running', required — Initial job status

## Other responses

- `400` — Default Response
- `401` — Default Response
- `402` — Default Response
- `429` — Default Response
- `500` — Default Response

---

[API](https://skmtc.net/shortcut/apis/shortcut-api.md) · [All operations](https://skmtc.net/shortcut/apis/shortcut-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shortcut/shortcut-api/revisions/1d5c69423568/schema)