{"openapi":"3.0.3","info":{"title":"Shortcut API","version":"1.0.0","description":"Shortcut API lets teams automate spreadsheet workflows and export organization usage data programmatically.\n\n## Getting Started\n\n### Create an API key\n\n1. Go to [shortcut.ai](https://shortcut.ai)\n2. Navigate to **Settings → API Keys**\n3. Create a new API key\n\nExternal callers use an API key in the `Authorization` header as a Bearer token:\n`Authorization: Bearer sc-xxx`\n\nAuthenticated Shortcut applications can call spreadsheet automation routes with\nthe user's Shortcut session or access token for run, upload, status, download,\nskills, and cancel operations. Non-browser applications send the JWT as a\nbearer token; Shortcut web applications may use the same JWT through the\n`shortcut_access_token` cookie in a credentialed request from a trusted\nShortcut origin. `/verify` and webhooks require API key authentication because\nthey depend on API key and webhook-secret state.\n\nRegistered integrations can also use authorization-code OAuth with S256 PKCE\nand client authentication. The user approves `api:access`; the integration\nsends its OAuth access token as a Bearer token on spreadsheet routes. This\npreserves the user's ownership, subscription, and credit checks. OAuth does not\nsupport API-key verification, webhooks, or organization usage export.\n\n### Spreadsheet automation workflow\n\n1. **Verify your API key**: `GET /api/spreadsheets/verify`\n2. **Submit a job**: `POST /api/spreadsheets` with a prompt\n3. **Check status**: `GET /api/spreadsheets/:runId` (poll until completed, failed, or error)\n4. **Download result**: `GET /api/spreadsheets/:runId/download`\n\n### Usage export workflow\n\n1. Open **Usage Metrics** in Shortcut.\n2. Copy the prefilled command from **Programmatic export**.\n3. Use the Usage API reference to customize date range, format, or grouping.\n\n### Spreadsheet automation limits\n\n- Maximum 2000 concurrent jobs per API key\n- Job timeout: 30 minutes (configurable up to 120 minutes)\n"},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in Bearer token format: `Authorization: Bearer sc-xxx`"},"shortcutOAuth":{"type":"http","scheme":"bearer","bearerFormat":"OAuth access token","description":"Delegated OAuth access token with api:access scope. Existing user permissions and billing apply."},"shortcutSession":{"type":"http","scheme":"bearer","bearerFormat":"Shortcut Session","description":"First-party Shortcut application session or access token sent as an explicit Bearer token."},"shortcutCookie":{"type":"apiKey","in":"cookie","name":"shortcut_access_token","description":"Shortcut web session cookie for credentialed fetch requests. Missing or untrusted Origin headers are rejected."}},"schemas":{}},"paths":{"/api/spreadsheets":{"post":{"summary":"Submit Spreadsheet Processing Job","tags":["Spreadsheets"],"description":"Submit a natural language prompt to process a spreadsheet. Optionally provide an initial Excel file and context files.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"Natural language task description"},"initFile":{"type":"string","format":"uuid","description":"Optional File ID for initial Excel file"},"contextFiles":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":20,"description":"Optional File IDs for additional context files"},"timeoutSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":7200,"description":"Optional timeout in seconds (default: 1800s, max: 7200s)"},"webhookUrl":{"type":"string","format":"uri","description":"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":{"type":"string","enum":["action","ask"],"default":"action","description":"Agent mode: \"action\" (default) reads and writes the spreadsheet, \"ask\" performs read-only analysis and review without modifying the spreadsheet"},"model":{"type":"string","minLength":1,"description":"Optional ShortcutXL model id or model pattern for this job"},"thinking":{"type":"string","enum":["off","minimal","low","medium","high","xhigh","max"],"description":"Optional ShortcutXL thinking/effort level for this job"},"runtimeModelOverlay":{"type":"object","additionalProperties":{},"description":"Versioned ShortcutXL runtime model overlay, carried opaquely to the runtime"},"preferCurrentModelForSubagents":{"type":"boolean"},"subagentModel":{"type":"string","minLength":1},"projectId":{"type":"string","format":"uuid","description":"Optional Project ID whose source files are mounted read-only at /project. The writable /workspace mount remains the run-scoped file workspace."},"skills":{"type":"array","items":{"type":"string","minLength":1},"maxItems":10,"description":"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":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"enabled":{"type":"boolean"},"snapshotIntervalMs":{"type":"integer","minimum":10000,"maximum":60000}},"additionalProperties":false}],"description":"Optional debug mode. When enabled, API-v1 periodically persists bounded runner/session debug snapshots while the sandbox run is still active."}},"required":["prompt"],"additionalProperties":false}}}},"security":[{"apiKey":[]},{"shortcutSession":[]},{"shortcutCookie":[]},{"shortcutOAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string","description":"Unique run identifier"},"status":{"type":"string","enum":["queued","running"],"description":"Initial job status"}},"required":["runId","status"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"402":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"429":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}}}},"get":{"summary":"List Spreadsheet Runs","tags":["Spreadsheets"],"description":"List past spreadsheet processing runs for the authenticated user.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false}],"security":[{"apiKey":[]},{"shortcutSession":[]},{"shortcutCookie":[]},{"shortcutOAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"runs":{"type":"array","items":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string"},"prompt":{"type":"string"},"createdAt":{"type":"string"},"completedAt":{"type":["null","string"]},"creditsUsed":{"type":["null","number"]},"summary":{"type":["null","string"]}},"required":["runId","status","prompt","createdAt","completedAt","creditsUsed","summary"],"additionalProperties":false}},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["runs","limit","offset"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}}}}},"/api/spreadsheets/verify":{"get":{"summary":"Verify API Key","tags":["Authentication"],"description":"Verifies that your API key is valid and returns information about the authenticated user","security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Request success status","enum":[true]},"message":{"type":"string","description":"Success message"},"webhookSecret":{"type":"string","description":"Per-API-key HMAC-SHA256 secret for verifying webhook signatures. Use this to validate the X-Shortcut-Signature header on incoming webhook requests."}},"required":["success","message","webhookSecret"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Request success status","enum":[false]},"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Request success status","enum":[false]},"error":{"type":"string","description":"Error type"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/spreadsheets/skills":{"get":{"summary":"List Skills","tags":["Spreadsheets"],"description":"List available skills (built-in/default, personal, and team). The returned `id` is source-qualified and is the only accepted value for `POST /api/spreadsheets` `skills`; older folder-name-only ids are rejected. The web UI labels default skills as Official, but the API id prefix is `default:`.","security":[{"apiKey":[]},{"shortcutSession":[]},{"shortcutCookie":[]},{"shortcutOAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Source-qualified skill identifier — pass this exact value in the `skills` array when submitting a job. Valid prefixes are `default:`, `personal:`, and `team:{teamId}:`."},"folderName":{"type":"string","description":"Skill folder name used for paths and slash commands"},"name":{"type":"string","description":"Human-readable skill name"},"description":{"type":"string","description":"When to use this skill"},"source":{"type":"string","enum":["default","user","team"],"description":"Where the skill comes from"}},"required":["id","folderName","name","description","source"],"additionalProperties":false}}},"required":["skills"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"503":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}}}}},"/api/spreadsheets/upload":{"post":{"summary":"Upload File","tags":["Spreadsheets"],"description":"Upload a file to use in spreadsheet jobs. Returns a file ID.","security":[{"apiKey":[]},{"shortcutSession":[]},{"shortcutCookie":[]},{"shortcutOAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Upload success status","enum":[true]},"fileId":{"type":"string","format":"uuid","description":"File ID to use in job submission"}},"required":["success","fileId"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Request success status","enum":[false]},"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["success","error","message"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Request success status","enum":[false]},"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["success","error","message"],"additionalProperties":false}}}},"413":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Request success status","enum":[false]},"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["success","error","message"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Request success status","enum":[false]},"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Error message"}},"required":["success","error","message"],"additionalProperties":false}}}}}}},"/api/spreadsheets/{runId}/cancel":{"post":{"summary":"Cancel Spreadsheet Job","tags":["Spreadsheets"],"description":"Cancel an active spreadsheet processing job. Active queued/running runs are marked cancelled and any live execution sandbox is terminated best-effort.","parameters":[{"schema":{"type":"string"},"in":"path","name":"runId","required":true,"description":"Unique run identifier"}],"security":[{"apiKey":[]},{"shortcutSession":[]},{"shortcutCookie":[]},{"shortcutOAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"runId":{"type":"string"},"status":{"type":"string","enum":["cancelled"]},"previousStatus":{"type":"string","enum":["queued","running"]},"message":{"type":"string"}},"required":["runId","status","previousStatus","message"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}}}}},"/api/spreadsheets/{runId}":{"get":{"summary":"Get Spreadsheet Job Status","tags":["Spreadsheets"],"description":"Check the status of a spreadsheet processing job. Returns queued, running, finalizing, completed, failed, or cancelled status.","parameters":[{"schema":{"type":"string"},"in":"path","name":"runId","required":true,"description":"Unique run identifier"}],"security":[{"apiKey":[]},{"shortcutSession":[]},{"shortcutCookie":[]},{"shortcutOAuth":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"runId":{"type":"string","description":"Unique run identifier"},"status":{"type":"string","description":"Job completed successfully","enum":["completed"]},"downloadUrl":{"type":"string","description":"URL to download the result workbook, present when the completed job produced a workbook. Ask-mode jobs may complete with only a summary."},"summary":{"type":"string","description":"Final AI message summary from the agent"},"artifacts":{"type":"array","items":{"type":"string"},"description":"Filenames of files produced by the job. Download via GET /api/spreadsheets/:runId/artifacts/:filename"}},"required":["runId","status","artifacts"],"additionalProperties":false},{"type":"object","properties":{"runId":{"type":"string","description":"Unique run identifier"},"status":{"type":"string","enum":["queued","running","finalizing"],"description":"Job is still active"},"artifacts":{"type":"array","items":{"type":"string"},"description":"Filenames of currently available run artifacts, including live debug snapshots when debug mode is enabled."}},"required":["runId","status"],"additionalProperties":false},{"type":"object","properties":{"runId":{"type":"string","description":"Unique run identifier"},"status":{"type":"string","enum":["failed","cancelled"],"description":"Job failed or was cancelled"},"error":{"type":"string","description":"Error message"},"downloadUrl":{"type":"string","description":"URL to download a partial result workbook when a timeout saved one."},"artifacts":{"type":"array","items":{"type":"string"},"description":"Filenames of currently available run artifacts, including failure debug artifacts when debug mode is enabled."}},"required":["runId","status","error"],"additionalProperties":false}]}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}}}}},"/api/spreadsheets/{runId}/download":{"get":{"summary":"Download Spreadsheet Result","tags":["Spreadsheets"],"description":"Download the processed Excel file for a completed workbook-producing job","parameters":[{"schema":{"type":"string"},"in":"path","name":"runId","required":true,"description":"Unique run identifier"}],"security":[{"apiKey":[]},{"shortcutSession":[]},{"shortcutCookie":[]},{"shortcutOAuth":[]}],"responses":{"200":{"description":"Binary Excel file","content":{"application/json":{"schema":{"description":"Binary Excel file","type":"string","format":"binary","contentMediaType":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"409":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}}}}},"/api/spreadsheets/{runId}/artifacts/{filename}":{"get":{"summary":"Download Artifact","tags":["Spreadsheets"],"description":"Download a specific artifact file produced by a job.","parameters":[{"schema":{"type":"string"},"in":"path","name":"runId","required":true,"description":"Unique run identifier"},{"schema":{"type":"string"},"in":"path","name":"filename","required":true,"description":"Artifact filename"}],"security":[{"apiKey":[]},{"shortcutSession":[]},{"shortcutCookie":[]},{"shortcutOAuth":[]}],"responses":{"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"message":{"type":"string"}},"required":["success","error","message"],"additionalProperties":false}}}}}}},"/api/v1/team/usage-export":{"get":{"summary":"Export team usage metrics","tags":["Usage"],"description":"Export team usage metrics as JSON or CSV. The \"pure cost\" field is usage credits multiplied by the current active contract's credit_overage_rate in USD; it is a usage valuation at that rate, not an invoice total or provider cost. When there is no active contract or its rate is missing or non-positive, exports return credit metrics and omit dollar values. Usage Metrics in Shortcut provides a prefilled request with your team_id; use these query parameters to customize the date range, output format, and optional platform grouping. API keys must belong to a user with usage metrics access for the requested team or organization.","parameters":[{"schema":{"type":"string"},"in":"query","name":"team_id","required":false,"description":"Team or organization ID to export. Required for API-key integrations. Usage Metrics shows a prefilled request for the current organization."},{"schema":{"type":"string","enum":["day","week","month","60days","90days","all"],"default":"month"},"in":"query","name":"period","required":false,"description":"Relative date range to export when start_date and end_date are omitted."},{"schema":{"type":"string"},"in":"query","name":"start_date","required":false,"description":"YYYY-MM-DD. Must be provided together with end_date; takes precedence over period."},{"schema":{"type":"string"},"in":"query","name":"end_date","required":false,"description":"YYYY-MM-DD. Must be provided together with start_date; takes precedence over period."},{"schema":{"type":"string","default":"UTC"},"in":"query","name":"timezone","required":false,"description":"IANA timezone used to resolve relative periods and day boundaries."},{"schema":{"type":"string","enum":["json","csv"],"default":"json"},"in":"query","name":"format","required":false,"description":"Response format."},{"schema":{"type":"string","enum":["summary","daily"],"default":"summary"},"in":"query","name":"report","required":false,"description":"CSV only. summary exports per-member totals; daily exports member usage by day."},{"schema":{"type":"string","enum":["platform"]},"in":"query","name":"group_by","required":false,"description":"JSON only. Add platform usage breakdowns to the response."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}}},"tags":[{"name":"Authentication","description":"API key authentication and verification"},{"name":"Spreadsheets","description":"Spreadsheet processing and automation endpoints"},{"name":"Usage","description":"Export team usage metrics for reporting, finance, and internal analytics. Usage Metrics in Shortcut provides a prefilled request with your team_id; use this reference to customize date range, format, or grouping."}]}