# Controls API

The Controls API provides access to manage and retrieve control information within a Hyperproof organization. This API allows you to list, create, update, and manage controls and any linked proof, ensuring compliance and oversight of organizational processes.

Version: 1.0.0

## Servers

Hyperproof US
```
https://api.hyperproof.app/v1/controls
```

Hyperproof Gov
```
https://api.hyperproofgov.app/v1/controls
```

Hyperproof EU
```
https://api.hyperproof.eu/v1/controls
```

## Security

### oauth2

Type: oauth2

## Download OpenAPI description

[Controls API](https://developer.hyperproof.app/_bundle/hyperproof-api/controls/controls.openapi.yaml)

## Other

### Get Controls

 - [GET /](https://developer.hyperproof.app/hyperproof-api/controls/controls.openapi/other/get-controls.md): GET /

#### Description

Fetches a collection of controls based on specified query parameters. Use this endpoint to retrieve controls with optional filters for permissions, scopes, teams, or status.

#### Notes and caveats

##### Finding scoped controls

Use the GET / controls endpoint with the expandscopes=true query parameter. This addition pulls in extra information about scoped controls, such as:

- Controls with a parentControlId value, showing the original parent control they stem from.
- The linked scopeId and scopeName for each scoped control.

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


---

### Add Control

 - [POST /](https://developer.hyperproof.app/hyperproof-api/controls/controls.openapi/other/add-control.md): POST /

#### Description

Adds a new control to the organization with specified attributes, such as identifier, name, description, and owner.

#### Notes and caveats

##### 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. Just 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.

bash
POST https://api.hyperproof.app/v1/controls
Content-Type: application/json
{
"name": "New Control Name",
"scopeId": "desiredScopeId",
...other control properties...
}

### Add Control Proof

 - [POST /{controlId}/proof](https://developer.hyperproof.app/hyperproof-api/controls/controls.openapi/other/add-control-proof.md): POST /{controlId}/proof

#### Description

Uploads a proof item (e.g. a file) to associate with a specific control.

### Get Controls Filtered

 - [PUT /filter](https://developer.hyperproof.app/hyperproof-api/controls/controls.openapi/other/get-controls-filtered.md): PUT /filter

#### Description

Fetches controls matching a provided filter, such as a list of control IDs.

### Get Control Summaries

 - [GET /summaries](https://developer.hyperproof.app/hyperproof-api/controls/controls.openapi/other/get-control-summaries.md): GET /summaries

#### Description

Fetches a summarized list of controls, including their IDs, identifiers, names, and timestamps.

### Get Control

 - [GET /{controlId}](https://developer.hyperproof.app/hyperproof-api/controls/controls.openapi/other/get-control.md): GET /{controlId}

#### Description

Fetches detailed information about a specific control using its unique ID.

#### Notes and caveats

##### Finding scoped controls

Use the GET /controls endpoint with the expandscopes=true query parameter. This addition pulls in extra information about scoped controls, such as:

- Controls with a parentControlId value, showing the original parent control they stem from.
- The linked scopeId and scopeName for each scoped control.

bash
GET https://api.hyperproof.app/v1/controls/{controlId}?expandscopes=true


---

### Update Control

 - [PATCH /{controlId}](https://developer.hyperproof.app/hyperproof-api/controls/controls.openapi/other/update-control.md): PATCH /{controlId}

#### Description

Modifies an existing control’s attributes, such as name, description, or owner.

#### Notes and caveats

##### Changing the scope on an existing control with PATCH

You can do a PATCH request to https://api.hyperproof.app/v1/controls/{controlId}.  Just include the scopeId you want to assign in the request body. This links the control to the specified scope.

- You must know the scopeId beforehand. There’s no API endpoint to list all available scopeIds, so you can get the scopeId by running a GET /controls?expandscopes=true call as mentioned earlier.
- Double-check that the scopeId is valid for your Hyperproof setup before sending the request.

bash   
PATCH https://api.hyperproof.app/v1/controls/{controlId}  
Content-Type: application/json  
{  
"scopeId": "desiredScopeId"  
}