Sheets

​
Atomically create, update and delete in-house sheet rows

Values use column IDs or unambiguous titles. Strict column types; null clears a cell. Invalid values reject the whole batch with row_ref, column_id and reason. Preview returns cell changes and created/deleted row IDs without writing. Every write returns the full sheet. Writes are not idempotent: re-read after an unknown outcome before retrying. Updates are not upserts.

POST
/v1/space/sheets/{sheet_id}/tabs/{tab_id}/rows/batch
curl -X POST "https://api.orchestor.io/v1/space/sheets/%3Csheet_id%3E/tabs/%3Ctab_id%3E/rows/batch" \  -H "Authorization: Bearer $API_KEY" \  -H "X-Workspace-ID: wks_abc123" \  -H "Content-Type: application/json" \  -d '{  "operations": [    {      "before_row_id": "string",      "op": "create",      "row_id": "string",      "values": {}    }  ],  "preview": true,  "updated_at": "string"}'
{  "data": {    "archived": true,    "created_at": "2026-01-01T00:00:00Z",    "deleted_at": "2026-01-01T00:00:00Z",    "folder_id": null,    "id": "<string>",    "pinned": true,    "sort_position": 0,    "tabs": [      {        "columns": [          {            "color": "<string>",            "currencyCode": "<string>",            "description": "<string>",            "hidden": true,            "id": "<string>",            "options": [              "<string>"            ],            "pinned": true,            "title": "<string>",            "type": "text",            "width": 104          }        ],        "deleted": true,        "filter": {          "columnId": "<string>",          "value": "<string>"        },        "hidden": true,        "id": "<string>",        "rows": [          {            "id": "<string>",            "parentId": "<string>",            "values": {}          }        ],        "sort": {          "columnId": "<string>",          "direction": "asc"        },        "title": "<string>"      }    ],    "title": "<string>",    "updated_at": "2026-01-01T00:00:00Z",    "workspace_id": "<string>"  }}

Get your Orchestor API key

Create an API key in your workspace settings.

Authorizations

Satisfy one of these options:

  • Session cookie
  • API key

Authentication details

cookie
wos-session

Browser session established by signing in to the web app. The server checks your workspace membership and permissions. Supply X-Workspace-ID for workspace-scoped operations. For server-to-server requests, use an API key when the operation supports it.

Path Parameters

sheet_idstringpathrequired
Pattern
^sht_[a-f0-9]{24}$
tab_idstringpathrequired
String length
≥ 1, ≤ 256

Headers

X-Workspace-IDstringheader

Workspace to access. With a workspace-scoped API key, the server derives this value from the key, so the header is optional. If supplied, it must match the credential workspace or the request returns 403 workspace_mismatch. For interactive session requests, supply this header to select a workspace where you are a member. A project ID cannot be used as a workspace ID.

Example"wks_abc123"

Bodyapplication/jsonrequired

Additional properties
Not allowed
operations(object | object | object)[]bodyrequired
Item count
≥ 1
operations[]object | object | objectbody

Match exactly one of the following

Variant 1: object

Additional properties
Not allowed
operations[].before_row_idstringbody
String length
≥ 1, ≤ 256
operations[].opstringenum<string>bodyrequired
Allowed
create
operations[].row_idstringbody
String length
≥ 1, ≤ 256
operations[].valuesobjectbodyrequired
operations[].values.*anybody

Variant 2: object

Additional properties
Not allowed
operations[].opstringenum<string>bodyrequired
Allowed
update
operations[].row_idstringbodyrequired
String length
≥ 1, ≤ 256
operations[].valuesobjectbodyrequired
operations[].values.*anybody

Variant 3: object

Additional properties
Not allowed
operations[].opstringenum<string>bodyrequired
Allowed
delete
operations[].row_idstringbodyrequired
String length
≥ 1, ≤ 256
previewbooleanbody
updated_atstringbodyrequiredformat:date-time

Response

application/json

Full updated sheet or preview diff

dataSpaceSheet | objectrequired

Match at least one of the following

Variant 1: SpaceSheet

data.archivedbooleanrequired
data.created_atstringrequiredformat:date-time
data.deleted_atstring | nullrequiredformat:date-time
data.folder_idstring | nulldefault:null
data.idstringrequired
Pattern
^sht_[a-f0-9]{24}$
data.pinnedbooleanrequired
data.sort_positionintegerrequired
Value range
≥ 0, ≤ 2147483647
data.tabsobject[]required
Item count
≥ 1
data.tabs[]object
Additional properties
Not allowed
data.tabs[].columnsobject[]
data.tabs[].columns[]object
Additional properties
Not allowed
data.tabs[].columns[].colorstring
data.tabs[].columns[].currencyCodestring
data.tabs[].columns[].descriptionstring
data.tabs[].columns[].hiddenboolean
data.tabs[].columns[].idstringrequired
String length
≥ 1, ≤ 256
data.tabs[].columns[].optionsstring[]
data.tabs[].columns[].options[]string
data.tabs[].columns[].pinnedboolean
data.tabs[].columns[].titlestringrequired
data.tabs[].columns[].typestringenum<string>required
Allowed
textnumbercurrencyurldomaindatetimestampemailimagecheckboxselectmulti-select
data.tabs[].columns[].widthinteger
Value range
≥ 104
data.tabs[].deletedboolean
data.tabs[].filterobject
Additional properties
Not allowed
data.tabs[].filter.columnIdstringrequired
String length
≥ 1, ≤ 256
data.tabs[].filter.valuestringrequired
data.tabs[].hiddenboolean
data.tabs[].idstringrequired
String length
≥ 1, ≤ 256
data.tabs[].rowsobject[]required
data.tabs[].rows[]object
Additional properties
Not allowed
data.tabs[].rows[].idstringrequired
String length
≥ 1, ≤ 256
data.tabs[].rows[].parentIdstring
String length
≥ 1, ≤ 256
data.tabs[].rows[].valuesobject
data.tabs[].rows[].values.*string | number | boolean | string[]

Match at least one of the following

Variant 1: string

data.tabs[].rows[].values.*string

Variant 2: number

data.tabs[].rows[].values.*number

Variant 3: boolean

data.tabs[].rows[].values.*boolean

Variant 4: string[]

data.tabs[].rows[].values.*[]string
data.tabs[].sortobject
Additional properties
Not allowed
data.tabs[].sort.columnIdstringrequired
String length
≥ 1, ≤ 256
data.tabs[].sort.directionstringenum<string>required
Allowed
ascdesc
data.tabs[].titlestringrequired
String length
≥ 1, ≤ 100
data.titlestringrequired
String length
≥ 1, ≤ 100
data.updated_atstringrequiredformat:date-time
data.workspace_idstringrequired

Variant 2: object

data.changesobject[]required
data.changes[]object
data.changes[].afterstring | number | boolean | string[] | nullrequired

Match at least one of the following

Variant 1: string

data.changes[].afterstring

Variant 2: number

data.changes[].afternumber

Variant 3: boolean

data.changes[].afterboolean

Variant 4: string[]

data.changes[].after[]string

Variant 5: null

data.changes[].afternull
data.changes[].beforestring | number | boolean | string[] | nullrequired

Match at least one of the following

Variant 1: string

data.changes[].beforestring

Variant 2: number

data.changes[].beforenumber

Variant 3: boolean

data.changes[].beforeboolean

Variant 4: string[]

data.changes[].before[]string

Variant 5: null

data.changes[].beforenull
data.changes[].column_idstringrequired
String length
≥ 1, ≤ 256
data.changes[].row_idstringrequired
String length
≥ 1, ≤ 256
data.createdstring[]required
data.created[]string
String length
≥ 1, ≤ 256
data.deletedstring[]required
data.deleted[]string
String length
≥ 1, ≤ 256
data.previewbooleanenum<boolean>required
Allowed
true