# 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"}}}}}}}}}
```


---

# 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/saas-app-and-device-management-apis.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.