Apply a batch of commands to a workbook
Validates the WHOLE batch (shape, capability, sheet, commandId reuse) before applying anything; a commandId already committed in a prior batch is recognized and its cached result replayed rather than re-applied, so retrying a batch with the same commandIds is safe. A per-command apply() failure is NOT a batch failure — it lands as an `ok: false` CommandResult with its own `error.code` (see CommandResult); the whole batch is still 200 unless the batch itself was rejected pre-apply (400) or the `If-Match` precondition failed (409).
/workbooks/{id}/commandsAuthorization
bearerAuth PRE-RELEASE: this API does not yet authenticate callers. The bearer token is read but never verified — an "ak_"-prefixed value is attributed to an API-key actor and anything else, including an absent or empty header, to a generic user actor. Any string, or none at all, is accepted. Attribution only, not authentication: do not expose this surface to untrusted callers until key issuance ships.
In: header
Path Parameters
Header Parameters
Optimistic-concurrency precondition — the VersionId this batch's caller last read as HEAD. Enforced ONLY when the resolved X-Studio-Api-Version declares the "command_batch_occ" capability AND the batch contains at least one mutating command (a batch containing ONLY read:* commands — getRange, getFormats, getSheets, etc. — is exempt, matched by the "read:" prefix); on an incapable or unrecognized API version this header is silently ignored and the write proceeds unconditionally. A stale or missing token on an enforcing version returns 409 version_conflict, echoing both the token the caller sent and the actual current version.
Selects which behavioral capabilities this request gets — dated version strings, looked up in a plain registry, never regex-parsed. An unrecognized or missing value resolves to "no capabilities", identically. Only "2026-07-17.preview" is registered today, and is exactly what a missing header resolves to (DEFAULT_VERSION).
Declares the calling surface, recorded as per-commit attribution in the checkpoint history. An unrecognized or missing value defaults to "api".
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /workbooks/{id}/commands request body. Each entry in commands is one member of the Command union below, and is validated against its declared type before being applied.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/workbooks/string/commands" \ -H "Content-Type: application/json" \ -d '{ "commands": [ { "commandId": "string", "sheet": "string", "range": { "from": "string", "to": "string" }, "chartType": "column", "options": {}, "type": "chart:insert" } ] }'{
"version": "string",
"results": [
{
"ok": true,
"commandId": "string",
"type": "string",
"result": {
"property1": null,
"property2": null
}
}
]
}{
"error": "invalid_request",
"message": "string"
}{
"error": "not_found",
"message": "string"
}{
"error": "version_conflict",
"expectedVersion": "string",
"currentVersion": "string"
}Create a workbook (convenience route)
Create an empty workbook and return its identifiers. A convenience route, deliberately outside the core command contract — creating a workbook is expected to become billing- and entitlement-gated, so its shape is not yet fixed. Any request body is ignored: every workbook is created with the same defaults (1000 rows x 26 columns, one sheet named "Sheet1").
Read a workbook's checkpoint
Only the latest checkpoint is servable today (no history endpoint yet). No request headers are read by this route — neither `Authorization` nor any of the three contract headers; `security: []` reflects that faithfully rather than implying a check that does not exist.