Partially update a single sheet#

Description#

Updates the properties of a sheet.

This is a long running operation. Responses include a Location header, which indicates where to poll for results. For more details on long-running job polling, see Operations endpoint.

Options#

Path	PATCH Operations Supported
`/name`	`replace`
`/index`	`replace`
`/parent`	`replace`
`/customFields/<custom field id>`	`add`, `remove`, `replace`, `test`
`/lock`	`replace`

Examples#

Lock an unlocked sheet#

[
  {
    "op": "replace",
    "path": "/lock",
    "value": "lock"
  }
]

Unlock a locked sheet#

[
  {
    "op": "replace",
    "path": "/lock",
    "value": null
  }
]

Update the name of a sheet#

[
  {
    "op": "replace",
    "path": "/name",
    "value": "Q1 Draft"
  }
]

Update the parent of a sheet (preserving its index)#

[
  {
    "op": "replace",
    "path": "/parent",
    "value": {
      "id": "242a56d3cc0742c8abad0820bd318b23"
    }
  }
]

Update the parent of a sheet (making it the first child)#

[
  {
    "op": "replace",
    "path": "/parent",
    "value": {
      "id": "242a56d3cc0742c8abad0820bd318b23"
    }
  },
  {
    "op": "replace",
    "path": "/index",
    "value": 0
  }
]

Add a custom field value#

[
  {
    "op": "add",
    "path": "/customFields/com.workiva.gsr.legal_entity",
    "value": "Workiva"
  }
]

Remove a custom field value#

[
  {
    "op": "remove",
    "path": "/customFields/com.workiva.gsr.legal_entity"
  }
]

Replace a custom field value#

[
  {
    "op": "replace",
    "path": "/customFields/com.workiva.gsr.legal_entity",
    "value": "Workiva, Inc."
  }
]

PATCH /spreadsheets/{spreadsheetId}/sheets/{sheetId}

Required OAuth Scopes

file:write

Parameters#

Parameter	In	Type	Required	Description
X-Version	header	string	true	Version of the API (2026-01-01)
spreadsheetId	path	string	true	The unique identifier of the spreadsheet
sheetId	path	string	true	The unique identifier of the sheet
body	body	JSONPatchDocument	true	A collection of patch operations to apply to the sheet.

Body parameter example#

[
  {
    "op": "replace",
    "path": "/name",
    "value": "Sheet 1"
  }
]

Code Samples#

curl

curl -X PATCH https://api.app.wdesk.com/spreadsheets/{spreadsheetId}/sheets/{sheetId} \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer {access-token}' \
    -H 'X-Version: 2026-01-01'

httpie

http PATCH https://api.app.wdesk.com/spreadsheets/{spreadsheetId}/sheets/{sheetId} \
    X-Version:2026-01-01 \
    Content-Type:application/json \
    Accept:application/json \
    Authorization:"Bearer {access-token}"

wget

wget --method=PATCH "https://api.app.wdesk.com/spreadsheets/{spreadsheetId}/sheets/{sheetId}" \
    --output-document -  \ 
    --header 'Content-Type: application/json' \ 
    --header 'Accept: application/json' \ 
    --header 'Authorization: Bearer {access-token}' \
    --header 'X-Version: 2026-01-01'

python

import requests

headers = {
  'X-Version': '2026-01-01',
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.patch('https://api.app.wdesk.com/spreadsheets/{spreadsheetId}/sheets/{sheetId}', headers = headers)

print(r.headers['Location'])

Returns#

202 - Accepted#

Response body for asynchronous operations. Contains an operationLocation field that specifies the URL to poll for the operation result. This URL can also be found in the Location header on the response.

Header	Description
Location	The location to poll for the operation result.
Retry-After	The number of seconds to wait before polling for a result and between polling attempts.