List controls#

Description#

Return a paginated collection of controls as full representations. A workspace is in either standalone mode or multi-instance mode. Unfiltered results contain standalone controls in standalone mode, or definition and instance controls in multi-instance mode. Use $filter=controlType eq 'standalone' (or in) to request a subset of the types available in that workspace mode. To page through the instances derived from a specific definition, filter by that definition’s controlId with $filter=definitionId eq 'BEN.002'. Nested attributes are filtered with dotted paths that mirror the response body, for example process.name eq 'Revenue' or locations.id eq '...'. Absence is expressed as <field> eq null and presence as <field> ne null; for subProcess, locations, systems, programs, mitigatedRisks and activeTestingSignal a null comparison is the only form supported. Against a value, ne is the negation of eq, so like not (...) it does not match controls whose value is absent; use <field> eq null to find those. overriddenFields accepts either a standard field name or a custom field schema id, where in matches instances overriding any of the listed fields and eq matches a single overridden field.

GET /controls

Required OAuth Scopes

grc:read

Parameters#

Parameter	In	Type	Required	Description
X-Version	header	string	true	Version of the API (2026-09-01.grc.preview)
$maxpagesize	query	integer(int32)	false	Maximum number of items to return in a single page. The service applies a default and a maximum; requests above the maximum are clamped.
$next	query	string	false	Opaque cursor identifying the next page of results, taken from the previous page. Omit on the first request.
$filter	query	string	false	Filter expression restricting the collection, of the form `field <op> value`. Comparison operators are `eq`, `in`, and `contains`, composed with the logical connectives `and`, `or`, and `not` (negation is expressed as `not (field eq value)` — there is no `ne`). The set of filterable fields and supported operators varies per resource. Example: `significance eq 'key'`.
$orderBy	query	string	false	Sort criteria of the form `field [asc
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.

Filter Options#

Available logical operators: and, or, not

Name	Predicates Supported
activeAssessments	`eq`, `in`, `ne`
activeIssueCount	`eq`, `gt`, `lt`
activeTestingSignal	`eq`, `ne`
automatedManual	`eq`, `ne`
controlId	`eq`, `contains`, `ne`
controlType	`eq`, `in`
definitionId	`eq`, `contains`
description	`eq`, `contains`, `ne`
frequency	`eq`, `ne`
id	`eq`, `in`
locations	`eq`, `ne`
locations.id	`eq`, `in`
mitigatedRisks	`eq`, `ne`
mitigatedRisks.id	`eq`, `in`
name	`eq`, `contains`, `ne`
overriddenFields	`eq`, `in`
owner.id	`eq`, `in`
preventiveDetective	`eq`, `ne`
process.id	`eq`, `in`
process.name	`eq`
programs	`eq`, `ne`
programs.id	`eq`, `in`
projectId	`eq`, `in`
significance	`eq`, `ne`
subProcess	`eq`, `ne`
subProcess.id	`eq`, `in`
subProcess.name	`eq`
systems	`eq`, `ne`
systems.id	`eq`, `in`

Sorting Options#

Name	Orders Supported
automatedManual	`asc`, `desc`
controlId	`asc`, `desc`
description	`asc`, `desc`
frequency	`asc`, `desc`
name	`asc`, `desc`
preventiveDetective	`asc`, `desc`
process.name	`asc`, `desc`
significance	`asc`, `desc`
subProcess.name	`asc`, `desc`
updatedAt	`asc`, `desc`

Code Samples#

curl

curl -X GET https://api.app.wdesk.com/controls \
    -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'

httpie

http GET https://api.app.wdesk.com/controls \
    X-Version:2026-09-01.grc.preview \
    Accept:application/json \
    Wk-Workspace:1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d \
    Authorization:"Bearer {access-token}"

wget

wget --method=GET "https://api.app.wdesk.com/controls" \
    --output-document - \
    --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'

python

import requests

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

r = requests.get('https://api.app.wdesk.com/controls', headers = headers)

print(r.json())