Working with scoped controls

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

When integrating with the Hyperproof API, managing scoped controls is a critical part of the process. This article explains the essential concepts and shows you how to work with scoped controls—from retrieving scope data to updating assignments through API calls.

What is a scoped control?

A scoped control is the child control of a parent control. Scoped controls have a variety of use cases, but the most common is to track proof collection on controls for subdivisions of an organization. For more information, refer to Working with scopes.

When a scope is assigned to a control in the UI, Hyperproof generates a new child control. This control includes a parentControlId that links it to the original control, maintaining a clear hierarchy and ensuring each scoped control can be traced back to its source.

Accessing scope information for controls

Fetching a single control with GET /controls/{controlId}

If you call https://api.hyperproof.app/v1/controls/{controlId} to retrieve a control’s details, you may notice that scopeName and other scope-related fields aren’t included in the response. That's expected behavior.

Getting the full picture with GET /controls and expanded scopes

Use the GET /controls endpoint with the expandscopes=true query parameter. This returns additional scoped-control details, including:

• Controls that have a parentControlId, indicating their parent control.
• The associated scopeId and scopeName for each scoped control.

GET https://api.hyperproof.app/v1/controls?expandscopes=true

Assigning or changing scopes on controls

Changing the scope on an existing control with PATCH

To update the scope of an existing control, issue a PATCH request to https://api.hyperproof.app/v1/controls/{controlId}. Be sure to include the scopeId you want to assign in the request body. This links the control to the specified scope.

Note: Because there's no API endpoint to list all available scopeIds, the scopeId must be determined beforehand. To get the scopeId, run the GET /controls?expandscopes=true call. Be sure to double-check that the scopeId is valid for your Hyperproof setup before sending the request.

PATCH https://api.hyperproof.app/v1/controls/{controlId}

Content-Type: application/json  
{  
"scopeId": "desiredScopeId"  
}

Setting up a new control with a scope using POST

If you’re creating a control from scratch, you can assign a scope right away with the POST /controls endpoint. Be sure to use the desired scopeId in the request payload alongside other control details.

Note: This action creates a NEW control that can be used as a parent. Child controls are not created using the API.

Currently, the creation of scoped child controls on existing controls is not supported.

POST https://api.hyperproof.app/v1/controls

Content-Type: application/json

{
"name": "New Control Name",
"scopeId": "desiredScopeId",
...other control properties...
}

Known limitations

Since there is no dedicated endpoint for listing scopeIds, the recommended approach for finding scope IDs is to query controls with the expandscopes=true parameter or retrieve the IDs directly from the Hyperproof UI.