# Policy Update APIs

## Update a policy user scope

> Update a policy user scope, define inclusion/exclusion rule for users using user emails. Only supports gDrive policies, separates internal or external users based on google domains registered in Nightfall.

```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Policy API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/policy/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"integer","description":"A status code to uniquely describe this error."},"message":{"type":"string","description":"A message associated with the status code."},"description":{"type":"string","description":"Additional details to explain what may have occurred. Omitted if empty."}}}}},"paths":{"/{policyID}/scope/users":{"post":{"summary":"Update a policy user scope","description":"Update a policy user scope, define inclusion/exclusion rule for users using user emails. Only supports gDrive policies, separates internal or external users based on google domains registered in Nightfall.","parameters":[{"name":"policyID","in":"path","description":"The UUID of the policy to update","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string","format":"email"},"description":"user emails to be added in inclusion setting, supports both internal & external users"},"exclude":{"type":"array","items":{"type":"string","format":"email"},"description":"user emails to be added in exclusion setting, supports both internal & external users"}}},"delete":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string","format":"email"},"description":"user emails to be removed in inclusion setting, supports both internal & external users"},"exclude":{"type":"array","items":{"type":"string","format":"email"},"description":"user emails to be removed in exclusion setting, supports both internal & external users"}}}}}}}},"responses":{"200":{"description":"Successful response (processed immediately)","headers":{"X-Rate-Limit-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next second before being throttled"}},"X-Quota-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next quota period"}},"X-Quota-Period-End":{"schema":{"type":"string","format":"date-time","description":"When the current quota period expires"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"includedUsers":{"type":"array","items":{"type":"string"},"description":"a list of all included user identifiers (emails or id's) in the policy"},"excludedUsers":{"type":"array","items":{"type":"string"},"description":"a list of all excluded user identifiers (emails or id's) in the policy"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Operation prohibited on the policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","headers":{"Retry-After":{"schema":{"type":"integer","description":"Seconds after which to retry the request"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Update a policy domain scope

> Update a policy domain scope, define inclusion/exclusion rule for domains. Only supports gDrive policies.

```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Policy API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/policy/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"integer","description":"A status code to uniquely describe this error."},"message":{"type":"string","description":"A message associated with the status code."},"description":{"type":"string","description":"Additional details to explain what may have occurred. Omitted if empty."}}}}},"paths":{"/{policyID}/scope/domains":{"post":{"summary":"Update a policy domain scope","description":"Update a policy domain scope, define inclusion/exclusion rule for domains. Only supports gDrive policies.","parameters":[{"name":"policyID","in":"path","description":"The UUID of the policy to update","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"},"description":"domains to be added in inclusion setting"},"exclude":{"type":"array","items":{"type":"string"},"description":"domains to be added in exclusion setting"}}},"delete":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"},"description":"domains to be removed in inclusion setting"},"exclude":{"type":"array","items":{"type":"string"},"description":"domains to be removed in exclusion setting"}}}}}}}},"responses":{"200":{"description":"Successful response (processed immediately)","headers":{"X-Rate-Limit-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next second before being throttled"}},"X-Quota-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next quota period"}},"X-Quota-Period-End":{"schema":{"type":"string","format":"date-time","description":"When the current quota period expires"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"includedDomains":{"type":"array","items":{"type":"string"},"description":"a list of all included domains in the policy"},"excludedDomains":{"type":"array","items":{"type":"string"},"description":"a list of all excluded domains in the policy"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Operation prohibited on the policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","headers":{"Retry-After":{"schema":{"type":"integer","description":"Seconds after which to retry the request"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Update a posture policy trigger user scope

> Update trigger-scoped users for a posture management policy. Modifies users stored in the trigger scope. Only supports posture management policies of gDrive.

```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Policy API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/policy/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"integer","description":"A status code to uniquely describe this error."},"message":{"type":"string","description":"A message associated with the status code."},"description":{"type":"string","description":"Additional details to explain what may have occurred. Omitted if empty."}}}}},"paths":{"/{policyID}/trigger/users":{"post":{"summary":"Update a posture policy trigger user scope","description":"Update trigger-scoped users for a posture management policy. Modifies users stored in the trigger scope. Only supports posture management policies of gDrive.","parameters":[{"name":"policyID","in":"path","description":"The UUID of the policy to update","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string","format":"email"},"description":"user emails to be added in inclusion setting"},"exclude":{"type":"array","items":{"type":"string","format":"email"},"description":"user emails to be added in exclusion setting"}}},"delete":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string","format":"email"},"description":"user emails to be removed from inclusion setting"},"exclude":{"type":"array","items":{"type":"string","format":"email"},"description":"user emails to be removed from exclusion setting"}}}}}}}},"responses":{"200":{"description":"Successful response (processed immediately)","headers":{"X-Rate-Limit-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next second before being throttled"}},"X-Quota-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next quota period"}},"X-Quota-Period-End":{"schema":{"type":"string","format":"date-time","description":"When the current quota period expires"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"includedUsers":{"type":"array","items":{"type":"string"},"description":"a list of all included user identifiers (emails or IDs) in the policy trigger scope"},"excludedUsers":{"type":"array","items":{"type":"string"},"description":"a list of all excluded user identifiers (emails or IDs) in the policy trigger scope"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Operation prohibited on the policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","headers":{"Retry-After":{"schema":{"type":"integer","description":"Seconds after which to retry the request"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Update a posture policy trigger domain scope

> Update trigger-scoped domains for a posture management policy. Modifies domains stored in trigger scope. Only supports posture management policies of gDrive.

```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Policy API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/policy/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"integer","description":"A status code to uniquely describe this error."},"message":{"type":"string","description":"A message associated with the status code."},"description":{"type":"string","description":"Additional details to explain what may have occurred. Omitted if empty."}}}}},"paths":{"/{policyID}/trigger/domains":{"post":{"summary":"Update a posture policy trigger domain scope","description":"Update trigger-scoped domains for a posture management policy. Modifies domains stored in trigger scope. Only supports posture management policies of gDrive.","parameters":[{"name":"policyID","in":"path","description":"The UUID of the policy to update","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"},"description":"domains to be added in inclusion setting"},"exclude":{"type":"array","items":{"type":"string"},"description":"domains to be added in exclusion setting"}}},"delete":{"type":"object","properties":{"include":{"type":"array","items":{"type":"string"},"description":"domains to be removed from inclusion setting"},"exclude":{"type":"array","items":{"type":"string"},"description":"domains to be removed from exclusion setting"}}}}}}}},"responses":{"200":{"description":"Successful response (processed immediately)","headers":{"X-Rate-Limit-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next second before being throttled"}},"X-Quota-Remaining":{"schema":{"type":"integer","description":"How many remaining requests you can make within the next quota period"}},"X-Quota-Period-End":{"schema":{"type":"string","format":"date-time","description":"When the current quota period expires"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"includedDomains":{"type":"array","items":{"type":"string"},"description":"a list of all included domains in the policy trigger scope"},"excludedDomains":{"type":"array","items":{"type":"string"},"description":"a list of all excluded domains in the policy trigger scope"}}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Operation prohibited on the policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","headers":{"Retry-After":{"schema":{"type":"integer","description":"Seconds after which to retry the request"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.nightfall.ai/developer-api/nightfall_apis/scope_update.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.