> For the complete documentation index, see [llms.txt](https://help.nightfall.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.nightfall.ai/developer-api/nightfall_apis/saas-app-and-device-management-apis.md).
# SaaS App and Device Management APIs
APIs to monitor and manager integrations
## Fetch Github repositories
> Returns a list of repositories Nightfall has access to.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"GithubRepository":{"type":"object","properties":{"repositoryID":{"type":"integer","format":"int64","description":"The GitHub repository ID"},"repositoryName":{"type":"string","description":"The name of the repository"},"isRepoPrivate":{"type":"boolean","description":"Whether the repo is private"},"repoLink":{"type":"string","description":"The URL of the repository"},"scannedAt":{"type":"integer","format":"int64","description":"Unix timestamp, the last scan time of any file/commit in the repository. Omitted if not scanned yet."},"isMonitored":{"type":"boolean","description":"Whether the repository is covered by a policy"},"githubUsername":{"type":"string","description":"GitHub username in case of a personal account and organization name in case of an organization"}}},"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":{"/github/repositories":{"get":{"summary":"Fetch Github repositories","description":"Returns a list of repositories Nightfall has access to.","parameters":[{"name":"limit","in":"query","description":"The maximum number of records to be returned in the response","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"pageToken","in":"query","description":"Cursor for getting the next page of results","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","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":{"repositories":{"type":"array","items":{"$ref":"#/components/schemas/GithubRepository"},"description":"the list of repositories being scanned"},"nextPageToken":{"type":"string","description":"Next page cursor, omitted if end of results reached"}}}}}},"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"}}}},"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"}}}}}}}}}
```
## List endpoint devices
> Returns a list of endpoint devices where the Nightfall agent is installed across the organization.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AgentDetails":{"type":"object","properties":{"os":{"type":"string","enum":["MAC_OS","WINDOWS","OS_UNSPECIFIED"],"description":"Operating system of the endpoint device"},"deviceName":{"type":"string","description":"Name of the endpoint device"},"deviceId":{"type":"string","description":"Unique identifier for the endpoint device"},"macAddresses":{"type":"array","items":{"type":"string"},"description":"MAC addresses of the endpoint device's network interfaces"},"connectionStatus":{"type":"string","enum":["ONLINE","DISCONNECTED","OFFLINE","CONNECTION_STATUS_UNSPECIFIED","ERROR","MISSING_FULL_DISK_ACCESS","STARTING"],"description":"Current connection status of the agent"},"lastConnection":{"type":"string","format":"date-time","description":"Timestamp of the agent's last connection. Omitted if never connected."},"agentVersion":{"type":"string","description":"Version of the installed agent"},"osVersion":{"type":"string","description":"Version of the operating system"},"userEmail":{"type":"string","description":"Email of the user associated with the agent"},"stealthMode":{"type":"string","enum":["STEALTH_MODE_STATUS_UNKNOWN","STEALTH_MODE_STATUS_ACTIVE","STEALTH_MODE_STATUS_INACTIVE"],"description":"Stealth mode status of the agent"},"profileStatus":{"type":"string","enum":["PROFILE_STATUS_UNKNOWN","PROFILE_STATUS_UP_TO_DATE","PROFILE_STATUS_OUT_OF_DATE","PROFILE_STATUS_NOT_INSTALLED"],"description":"Configuration profile installation status"},"missingPermissions":{"type":"array","items":{"type":"string","enum":["AGENT_PERMISSION_FULL_DISK_ACCESS","AGENT_PERMISSION_SCREEN_RECORDING","AGENT_PERMISSION_ACCESSIBILITY"]},"description":"List of permissions the agent is missing"},"errors":{"type":"array","items":{"type":"string","enum":["AGENT_ERROR_CODE_USER_AGENT_NOT_CONNECTED","AGENT_ERROR_CODE_DRIVER_MISSING","AGENT_ERROR_CODE_DRIVER_NOT_LOADED","AGENT_ERROR_CODE_USER_DATA_MISSING","AGENT_ERROR_CODE_BROWSER_EXTENSION_NOT_CONNECTED","AGENT_ERROR_CODE_ES_CLIENT_UNAUTHORIZED"]},"description":"List of error codes reported by the agent"},"extensionInstallationStatuses":{"type":"array","description":"Browser extension installation statuses for each detected browser","items":{"type":"object","properties":{"browser":{"type":"string","enum":["BROWSER_CHROME","BROWSER_EDGE","BROWSER_FIREFOX","BROWSER_SAFARI","BROWSER_ARC","BROWSER_ATLAS","BROWSER_BRAVE","BROWSER_CHROME_BETA","BROWSER_COMET","BROWSER_VIVALDI"],"description":"The browser name"},"status":{"type":"string","enum":["BROWSER_EXTENSION_INSTALLATION_STATUS_UNKNOWN","BROWSER_EXTENSION_INSTALLATION_STATUS_BROWSER_NOT_INSTALLED","BROWSER_EXTENSION_INSTALLATION_STATUS_BROWSER_INSTALLED","BROWSER_EXTENSION_INSTALLATION_STATUS_EXTENSION_INSTALLED","BROWSER_EXTENSION_INSTALLATION_STATUS_ERROR","BROWSER_EXTENSION_INSTALLATION_STATUS_INSTALLATION_PENDING","BROWSER_EXTENSION_INSTALLATION_STATUS_CONNECTED","BROWSER_EXTENSION_INSTALLATION_STATUS_DISCONNECTED"],"description":"Extension installation status for this browser"},"extensionConnected":{"type":"boolean","description":"Whether the extension is connected for any profile"},"lastConnectionStatusUpdate":{"type":"string","format":"date-time","description":"Timestamp of the most recent extension-connection state change (omitted when never reported)"}}}}}},"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":{"/endpoint/devices":{"get":{"summary":"List endpoint devices","description":"Returns a list of endpoint devices where the Nightfall agent is installed across the organization.","parameters":[{"name":"limit","in":"query","description":"The maximum number of agents to be returned in the response","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":500}},{"name":"pageToken","in":"query","description":"Cursor for getting the next page of results","required":false,"schema":{"type":"string"}},{"name":"query","in":"query","description":"Prefix search across device name, device ID, and user email","required":false,"schema":{"type":"string"}},{"name":"osTypes","in":"query","description":"Filter agents by operating system types","required":false,"schema":{"type":"array","items":{"type":"string","enum":["MAC_OS","WINDOWS"]}},"style":"form","explode":true},{"name":"connectionStatuses","in":"query","description":"Filter agents by connection status","required":false,"schema":{"type":"array","items":{"type":"string","enum":["ONLINE","DISCONNECTED","OFFLINE","STARTING","ERROR","MISSING_FULL_DISK_ACCESS"]}},"style":"form","explode":true},{"name":"agentVersion","in":"query","description":"Filter agents by version status","required":false,"schema":{"type":"string","enum":["AGENT_VERSION_FILTER_UP_TO_DATE","AGENT_VERSION_FILTER_OUT_OF_DATE"]}},{"name":"stealthMode","in":"query","description":"Filter agents by stealth mode status","required":false,"schema":{"type":"string","enum":["STEALTH_MODE_FILTER_ACTIVE","STEALTH_MODE_FILTER_INACTIVE"]}},{"name":"profileStatus","in":"query","description":"Filter agents by profile status","required":false,"schema":{"type":"string","enum":["PROFILE_STATUS_FILTER_UP_TO_DATE","PROFILE_STATUS_FILTER_OUT_OF_DATE","PROFILE_STATUS_FILTER_NOT_INSTALLED"]}},{"name":"errorCodes","in":"query","description":"Filter agents that have any of the specified error codes","required":false,"schema":{"type":"array","items":{"type":"string","enum":["AGENT_ERROR_CODE_USER_AGENT_NOT_CONNECTED","AGENT_ERROR_CODE_DRIVER_MISSING","AGENT_ERROR_CODE_DRIVER_NOT_LOADED","AGENT_ERROR_CODE_USER_DATA_MISSING","AGENT_ERROR_CODE_BROWSER_EXTENSION_NOT_CONNECTED","AGENT_ERROR_CODE_ES_CLIENT_UNAUTHORIZED"]}},"style":"form","explode":true},{"name":"missingPermissions","in":"query","description":"Filter agents that are missing any of the specified permissions","required":false,"schema":{"type":"array","items":{"type":"string","enum":["AGENT_PERMISSION_FULL_DISK_ACCESS","AGENT_PERMISSION_SCREEN_RECORDING","AGENT_PERMISSION_ACCESSIBILITY"]}},"style":"form","explode":true},{"name":"browserExtensions","in":"query","description":"Comma-delimited list of BROWSER:VALUE pairs to filter by browser extension status. VALUE may be either:\n - a boolean (`true`/`false`) — true matches any installed/connected state, false matches not-installed; or\n - a pipe-delimited list of installation states (e.g. `EXTENSION_CONNECTED|EXTENSION_DISCONNECTED`)\n to match agents whose extension is in any of the listed states. States may be passed in short\n form (`EXTENSION_CONNECTED`) or full form (`BROWSER_EXTENSION_INSTALLATION_STATUS_EXTENSION_CONNECTED`).\nValid filter states: BROWSER_NOT_INSTALLED, BROWSER_INSTALLED, EXTENSION_INSTALLED, INSTALLATION_PENDING, EXTENSION_CONNECTED, EXTENSION_DISCONNECTED. Any other value (UNKNOWN, ERROR, or the unprefixed CONNECTED/DISCONNECTED forms) is silently dropped. Note: the response `status` field still echoes the bare proto enum names (e.g. `BROWSER_EXTENSION_INSTALLATION_STATUS_CONNECTED`) — only filter input uses the EXTENSION_ aliases. Supported browsers: BROWSER_CHROME, BROWSER_EDGE, BROWSER_FIREFOX, BROWSER_SAFARI, BROWSER_ARC, BROWSER_ATLAS, BROWSER_BRAVE, BROWSER_CHROME_BETA, BROWSER_COMET, BROWSER_VIVALDI.\n","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","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":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentDetails"},"description":"List of endpoint DLP agents"},"totalAgents":{"type":"integer","format":"int64","description":"Total number of agents matching the filter criteria"},"nextPageToken":{"type":"string","description":"Next page cursor, omitted if end of results reached"}}}}}},"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"}}}},"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"}}}}}}}}}
```
## List endpoint domain collections
> Returns a paginated list of domain collections configured for the company.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"CollectionSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["MANUAL","SYSTEM","SYSTEM_DYNAMIC"]},"domains":{"type":"array","items":{"type":"string"},"description":"Preview of domains belonging to the collection (truncated)"},"totalDomains":{"type":"integer","format":"int64","description":"Total number of domains in the collection"}}},"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":{"/endpoint/collections":{"get":{"summary":"List endpoint domain collections","description":"Returns a paginated list of domain collections configured for the company.","parameters":[{"name":"limit","in":"query","description":"The maximum number of collections to be returned in the response","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"pageToken","in":"query","description":"Cursor for getting the next page of results","required":false,"schema":{"type":"string"}},{"name":"sortOrder","in":"query","description":"Sort order for the collection name","required":false,"schema":{"type":"string","enum":["asc","desc"],"default":"asc"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"$ref":"#/components/schemas/CollectionSummary"}},"totalCollections":{"type":"integer","format":"int64"},"nextPageToken":{"type":"string","description":"Next page cursor, omitted if end of results reached"}}}}}},"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"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Create an endpoint domain collection
> Creates a new manual domain collection. Collection names are case-insensitive unique per company and cannot be the reserved value \`CORPORATE DOMAINS\`.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"CollectionRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for the collection. Case-insensitive unique per company. The value `CORPORATE DOMAINS` is reserved."}}},"Collection":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Collection identifier"},"name":{"type":"string","description":"Collection name"},"source":{"type":"string","enum":["MANUAL","SYSTEM","SYSTEM_DYNAMIC"],"description":"How the collection was created. Only MANUAL collections are user-mutable."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of the most recent update"}}},"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":{"/endpoint/collections":{"post":{"summary":"Create an endpoint domain collection","description":"Creates a new manual domain collection. Collection names are case-insensitive unique per company and cannot be the reserved value `CORPORATE DOMAINS`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionRequest"}}}},"responses":{"201":{"description":"Collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A collection with the same name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Collection name is reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Update an endpoint domain collection
> Renames an existing manual domain collection. System collections cannot be renamed.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"CollectionRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Human-readable name for the collection. Case-insensitive unique per company. The value `CORPORATE DOMAINS` is reserved."}}},"Collection":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Collection identifier"},"name":{"type":"string","description":"Collection name"},"source":{"type":"string","enum":["MANUAL","SYSTEM","SYSTEM_DYNAMIC"],"description":"How the collection was created. Only MANUAL collections are user-mutable."},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of the most recent update"}}},"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":{"/endpoint/collections/{collectionUUID}":{"put":{"summary":"Update an endpoint domain collection","description":"Renames an existing manual domain collection. System collections cannot be renamed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionRequest"}}}},"responses":{"200":{"description":"Collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A collection with the same name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Collection cannot be changed, or name is reserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Delete an endpoint domain collection
> Soft-deletes a manual domain collection.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/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":{"/endpoint/collections/{collectionUUID}":{"delete":{"summary":"Delete an endpoint domain collection","description":"Soft-deletes a manual domain collection.","responses":{"204":{"description":"Collection deleted"},"400":{"description":"Invalid collection ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Collection cannot be changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## List domains in a collection
> Returns every active domain attached to the collection.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Domain":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"The domain name"},"source":{"type":"string","enum":["MANUAL","CSV_UPLOAD","CLICK_TO_ADD","SYSTEM"],"description":"How the domain was originally added (always MANUAL for entries created via this API; other values may appear for entries added through the UI or CSV upload)"},"updatedAt":{"type":"string","format":"date-time"}}},"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":{"/endpoint/collections/{collectionUUID}/domains":{"get":{"summary":"List domains in a collection","description":"Returns every active domain attached to the collection.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}},"400":{"description":"Invalid collection ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Add domains to a collection
> Bulk-adds domains to a collection. Domains added via the workflow API are always recorded with source \`MANUAL\`. When the target collection is the reserved \`CORPORATE DOMAINS\` collection, personal-email domains are rejected and returned in \`failedDomains\`.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AddDomainsRequest":{"type":"object","required":["domains"],"properties":{"domains":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":253,"description":"A valid domain name (e.g. `example.com`)"}}}}}},"AddDomainsResponse":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/Domain"},"description":"The domains successfully added"},"failedDomains":{"type":"array","items":{"type":"string"},"description":"Domain names rejected because they are personal-email providers and were targeted at the reserved corporate-domains collection. Omitted when empty."}}},"Domain":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"The domain name"},"source":{"type":"string","enum":["MANUAL","CSV_UPLOAD","CLICK_TO_ADD","SYSTEM"],"description":"How the domain was originally added (always MANUAL for entries created via this API; other values may appear for entries added through the UI or CSV upload)"},"updatedAt":{"type":"string","format":"date-time"}}},"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":{"/endpoint/collections/{collectionUUID}/domains":{"post":{"summary":"Add domains to a collection","description":"Bulk-adds domains to a collection. Domains added via the workflow API are always recorded with source `MANUAL`. When the target collection is the reserved `CORPORATE DOMAINS` collection, personal-email domains are rejected and returned in `failedDomains`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddDomainsRequest"}}}},"responses":{"200":{"description":"Domains processed (some may have been rejected as personal domains, see `failedDomains`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddDomainsResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Remove a domain from a collection
> Soft-deletes a single domain from a collection.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/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":{"/endpoint/collections/{collectionUUID}/domains/{domainUUID}":{"delete":{"summary":"Remove a domain from a collection","description":"Soft-deletes a single domain from a collection.","responses":{"204":{"description":"Domain deleted"},"400":{"description":"Invalid collection or domain ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection or domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## List endpoint MCP server collections
> Returns a paginated list of MCP server collections configured for the company.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"MCPServerCollectionSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["MANUAL","SYSTEM"]},"totalItems":{"type":"integer","format":"int32"}}},"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":{"/endpoint/mcp-collections":{"get":{"summary":"List endpoint MCP server collections","description":"Returns a paginated list of MCP server collections configured for the company.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"pageToken","in":"query","required":false,"schema":{"type":"string"}},{"name":"namePrefix","in":"query","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"collections":{"type":"array","items":{"$ref":"#/components/schemas/MCPServerCollectionSummary"}},"total":{"type":"integer","format":"int32"},"nextPageToken":{"type":"string"}}}}}},"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"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Create an MCP server collection
> Creates a new manual MCP server collection. Collection names are case-insensitive unique per company.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"MCPServerCollectionRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255}}},"MCPServerCollection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["MANUAL","SYSTEM"]},"itemCount":{"type":"integer","format":"int32"},"updatedAt":{"type":"string","format":"date-time"}}},"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":{"/endpoint/mcp-collections":{"post":{"summary":"Create an MCP server collection","description":"Creates a new manual MCP server collection. Collection names are case-insensitive unique per company.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPServerCollectionRequest"}}}},"responses":{"201":{"description":"Collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPServerCollection"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A collection with the same name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Update an MCP server collection
> Renames an existing manual MCP server collection. System collections cannot be renamed.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"MCPServerCollectionRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255}}},"MCPServerCollection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"source":{"type":"string","enum":["MANUAL","SYSTEM"]},"itemCount":{"type":"integer","format":"int32"},"updatedAt":{"type":"string","format":"date-time"}}},"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":{"/endpoint/mcp-collections/{collectionUUID}":{"put":{"summary":"Update an MCP server collection","description":"Renames an existing manual MCP server collection. System collections cannot be renamed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPServerCollectionRequest"}}}},"responses":{"200":{"description":"Collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MCPServerCollection"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A collection with the same name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Collection cannot be changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Delete an MCP server collection
> Soft-deletes a manual MCP server collection.
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/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":{"/endpoint/mcp-collections/{collectionUUID}":{"delete":{"summary":"Delete an MCP server collection","description":"Soft-deletes a manual MCP server collection.","responses":{"204":{"description":"Collection deleted"},"400":{"description":"Invalid collection ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Collection cannot be changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## GET /endpoint/mcp-collections/{collectionUUID}/items
> List items (server scopes) in an MCP server collection
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"MCPServerCollectionItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serverScope":{"$ref":"#/components/schemas/MCPServerScope"},"updatedAt":{"type":"string","format":"date-time"}}},"MCPServerScope":{"type":"object","required":["serverName"],"properties":{"serverName":{"type":"string","minLength":1,"maxLength":255,"description":"The MCP server name to include in the collection"},"toolNames":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Optional list of tool names to restrict to. Omit or send an empty list to include all tools on the server."}}},"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":{"/endpoint/mcp-collections/{collectionUUID}/items":{"get":{"summary":"List items (server scopes) in an MCP server collection","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"pageToken","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MCPServerCollectionItem"}},"total":{"type":"integer","format":"int32"},"nextPageToken":{"type":"string"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Add items (server scopes) to an MCP server collection
> Bulk-adds MCP server scopes to a collection. Each scope identifies an MCP server by \`serverName\` and optionally restricts the inventoried tools to a list of \`toolNames\`. Omitting \`toolNames\` means "all tools on this server".
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AddMCPItemsRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/MCPServerScope"}}}},"MCPServerScope":{"type":"object","required":["serverName"],"properties":{"serverName":{"type":"string","minLength":1,"maxLength":255,"description":"The MCP server name to include in the collection"},"toolNames":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Optional list of tool names to restrict to. Omit or send an empty list to include all tools on the server."}}},"AddMCPItemsResponse":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MCPServerCollectionItem"}}}},"MCPServerCollectionItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"serverScope":{"$ref":"#/components/schemas/MCPServerScope"},"updatedAt":{"type":"string","format":"date-time"}}},"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":{"/endpoint/mcp-collections/{collectionUUID}/items":{"post":{"summary":"Add items (server scopes) to an MCP server collection","description":"Bulk-adds MCP server scopes to a collection. Each scope identifies an MCP server by `serverName` and optionally restricts the inventoried tools to a list of `toolNames`. Omitting `toolNames` means \"all tools on this server\".\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddMCPItemsRequest"}}}},"responses":{"200":{"description":"Items added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddMCPItemsResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## DELETE /endpoint/mcp-collections/{collectionUUID}/items/{itemUUID}
> Remove an item from an MCP server collection
```json
{"openapi":"3.0.3","info":{"title":"Nightfall Workflow Applications API","version":"1.0.0"},"servers":[{"url":"https://api.nightfall.ai/apps/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":{"/endpoint/mcp-collections/{collectionUUID}/items/{itemUUID}":{"delete":{"summary":"Remove an item from an MCP server collection","responses":{"204":{"description":"Item deleted"},"400":{"description":"Invalid collection or item ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Collection or item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate Limit Exceeded or Daily Quota Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal Nightfall Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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/saas-app-and-device-management-apis.md?ask=
```
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.