Update an assurance project’s scope documentation#

Description#

Update the writable fields on an assurance project with a JSON Patch (RFC 6902) document. The supported operations are replace on /scopingRationale (the project-level scoping narrative) and replace on /scopingFiles (the set of attached Workiva files). Include an operation only for the field you want to change; a field with no operation is left unchanged. /scopingFiles is replace-set: the array you supply becomes the complete attached set, so a currently-attached file you omit is detached and [] detaches all; reference each file by its Workiva file id. Supported only for Independent Controls Testing projects; an update against any other project type returns 409. Returns the updated project.

PATCH /assuranceProjects/{id}

Required OAuth Scopes

grc:write

Parameters#

Parameter	In	Type	Required	Description
X-Version	header	string	true	Version of the API (2026-09-01.grc.preview)
id	path	string	true	The unique system identifier of the resource.
body	body	JSONPatchDocument	true
Wk-Workspace	header	string	true	The id of the Workiva workspace to operate in. Authorization is enforced against the authenticated user’s access within this workspace.

Body parameter example#

[
  {
    "op": "replace",
    "path": "/scopingRationale",
    "value": "FY26 scope limited to key controls over financial reporting per materiality analysis."
  },
  {
    "op": "replace",
    "path": "/scopingFiles",
    "value": [
      {
        "id": "019f2a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b"
      }
    ]
  }
]

Code Samples#

curl

curl -X PATCH 'https://api.app.wdesk.com/assuranceProjects/{id}' \
    -H 'Content-Type: application/json-patch+json' \
    -H 'Accept: application/json' \
    -H 'Wk-Workspace: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d' \
    -H 'Authorization: Bearer {access-token}' \
    -H 'X-Version: 2026-09-01.grc.preview' \
    --data-raw '[{"op":"replace","path":"/scopingRationale","value":"FY26 scope limited to key controls over financial reporting per materiality analysis."},{"op":"replace","path":"/scopingFiles","value":[{"id":"019f2a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b"}]}]'

httpie

echo '[{"op":"replace","path":"/scopingRationale","value":"FY26 scope limited to key controls over financial reporting per materiality analysis."},{"op":"replace","path":"/scopingFiles","value":[{"id":"019f2a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b"}]}]' | http PATCH https://api.app.wdesk.com/assuranceProjects/{id} \
    X-Version:2026-09-01.grc.preview \
    Content-Type:application/json-patch+json \
    Accept:application/json \
    Wk-Workspace:1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
    Authorization:"Bearer {access-token}"

wget

wget --method=PATCH "https://api.app.wdesk.com/assuranceProjects/{id}" \
    --output-document - \
    --header 'Content-Type: application/json-patch+json' \
    --header 'Accept: application/json' \
    --header 'Wk-Workspace: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d' \
    --header 'Authorization: Bearer {access-token}' \
    --header 'X-Version: 2026-09-01.grc.preview' \
    --body-data='[{"op":"replace","path":"/scopingRationale","value":"FY26 scope limited to key controls over financial reporting per materiality analysis."},{"op":"replace","path":"/scopingFiles","value":[{"id":"019f2a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b"}]}]'

python

import requests

headers = {
  'X-Version': '2026-09-01.grc.preview',
  'Content-Type': 'application/json-patch+json',
  'Accept': 'application/json',
  'Wk-Workspace': '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
  'Authorization': 'Bearer {access-token}'
}

body = [
  {
    "op": "replace",
    "path": "/scopingRationale",
    "value": "FY26 scope limited to key controls over financial reporting per materiality analysis."
  },
  {
    "op": "replace",
    "path": "/scopingFiles",
    "value": [
      {
        "id": "019f2a3b-4c5d-7e6f-8a9b-0c1d2e3f4a5b"
      }
    ]
  }
]

r = requests.patch('https://api.app.wdesk.com/assuranceProjects/{id}', headers = headers, json=body)

print(r.json())

Returns#

200 - The updated assurance project.#

An assurance project. Only fields common to every project type are returned, so the shape is stable as new project types are added.