SaaS App and Device Management APIs

APIs to monitor and manager integrations

Fetch Github repositories

get

Returns a list of repositories Nightfall has access to.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1 · max: 100Optional

The maximum number of records to be returned in the response

Default: 100

pageTokenstringOptional

Cursor for getting the next page of results

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/github/repositories

GET /apps/v1/github/repositories HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "repositories": [
    {
      "repositoryID": 1,
      "repositoryName": "text",
      "isRepoPrivate": true,
      "repoLink": "text",
      "scannedAt": 1,
      "isMonitored": true,
      "githubUsername": "text"
    }
  ],
  "nextPageToken": "text"
}

List endpoint devices

get

Returns a list of endpoint devices where the Nightfall agent is installed across the organization.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1 · max: 500Optional

The maximum number of agents to be returned in the response

Default: 500

pageTokenstringOptional

Cursor for getting the next page of results

querystringOptional

Prefix search across device name, device ID, and user email

agentVersionstring · enumOptional

Filter agents by version status

Possible values:

stealthModestring · enumOptional

Filter agents by stealth mode status

Possible values:

profileStatusstring · enumOptional

Filter agents by profile status

Possible values:

browserExtensionsstringOptional

Comma-delimited list of BROWSER:VALUE pairs to filter by browser extension status. VALUE may be either:

a boolean (true/false) — true matches any installed/connected state, false matches not-installed; or
a pipe-delimited list of installation states (e.g. EXTENSION_CONNECTED|EXTENSION_DISCONNECTED) to match agents whose extension is in any of the listed states. States may be passed in short form (EXTENSION_CONNECTED) or full form (BROWSER_EXTENSION_INSTALLATION_STATUS_EXTENSION_CONNECTED). Valid 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.

Example: BROWSER_CHROME:EXTENSION_CONNECTED|EXTENSION_DISCONNECTED,BROWSER_EDGE:true

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/endpoint/devices

GET /apps/v1/endpoint/devices HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "agents": [
    {
      "os": "MAC_OS",
      "deviceName": "text",
      "deviceId": "text",
      "macAddresses": [
        "text"
      ],
      "connectionStatus": "ONLINE",
      "lastConnection": "2026-06-10T15:57:24.928Z",
      "agentVersion": "text",
      "osVersion": "text",
      "userEmail": "text",
      "stealthMode": "STEALTH_MODE_STATUS_UNKNOWN",
      "profileStatus": "PROFILE_STATUS_UNKNOWN",
      "missingPermissions": [
        "AGENT_PERMISSION_FULL_DISK_ACCESS"
      ],
      "errors": [
        "AGENT_ERROR_CODE_USER_AGENT_NOT_CONNECTED"
      ],
      "extensionInstallationStatuses": [
        {
          "browser": "BROWSER_CHROME",
          "status": "BROWSER_EXTENSION_INSTALLATION_STATUS_UNKNOWN",
          "extensionConnected": true,
          "lastConnectionStatusUpdate": "2026-06-10T15:57:24.928Z"
        }
      ]
    }
  ],
  "totalAgents": 1,
  "nextPageToken": "text"
}

List endpoint domain collections

get

Returns a paginated list of domain collections configured for the company.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1 · max: 100Optional

The maximum number of collections to be returned in the response

Default: 50

pageTokenstringOptional

Cursor for getting the next page of results

sortOrderstring · enumOptional

Sort order for the collection name

Default: ascPossible values:

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/endpoint/collections

GET /apps/v1/endpoint/collections HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "collections": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "source": "MANUAL",
      "domains": [
        "text"
      ],
      "totalDomains": 1
    }
  ],
  "totalCollections": 1,
  "nextPageToken": "text"
}

Create an endpoint domain collection

post

Creates a new manual domain collection. Collection names are case-insensitive unique per company and cannot be the reserved value CORPORATE DOMAINS.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

namestring · min: 1 · max: 255Required

Human-readable name for the collection. Case-insensitive unique per company. The value CORPORATE DOMAINS is reserved.

Responses

201

Collection created

application/json

400

Invalid request body

application/json

401

Authentication failure

application/json

409

A collection with the same name already exists

application/json

422

Collection name is reserved

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

post

/endpoint/collections

POST /apps/v1/endpoint/collections HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "source": "MANUAL",
  "updatedAt": "2026-06-10T15:57:24.928Z"
}

Update an endpoint domain collection

put

Renames an existing manual domain collection. System collections cannot be renamed.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

UUID of the collection

Body

namestring · min: 1 · max: 255Required

Human-readable name for the collection. Case-insensitive unique per company. The value CORPORATE DOMAINS is reserved.

Responses

200

Collection updated

application/json

400

Invalid request

application/json

401

Authentication failure

application/json

404

Collection not found

application/json

409

A collection with the same name already exists

application/json

422

Collection cannot be changed, or name is reserved

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

put

/endpoint/collections/{collectionUUID}

PUT /apps/v1/endpoint/collections/{collectionUUID} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "source": "MANUAL",
  "updatedAt": "2026-06-10T15:57:24.928Z"
}

Delete an endpoint domain collection

delete

Soft-deletes a manual domain collection.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

UUID of the collection

Responses

204

Collection deleted

No content

400

Invalid collection ID

application/json

401

Authentication failure

application/json

404

Collection not found

application/json

422

Collection cannot be changed

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

delete

/endpoint/collections/{collectionUUID}

DELETE /apps/v1/endpoint/collections/{collectionUUID} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List domains in a collection

get

Returns every active domain attached to the collection.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

UUID of the parent collection

Responses

200

Successful response

application/json

400

Invalid collection ID

application/json

401

Authentication failure

application/json

404

Collection not found

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/endpoint/collections/{collectionUUID}/domains

GET /apps/v1/endpoint/collections/{collectionUUID}/domains HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "domains": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "source": "MANUAL",
      "updatedAt": "2026-06-10T15:57:24.928Z"
    }
  ]
}

Add domains to a collection

post

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.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

UUID of the parent collection

Body

Responses

200

Domains processed (some may have been rejected as personal domains, see failedDomains)

application/json

400

Invalid request

application/json

401

Authentication failure

application/json

404

Collection not found

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

post

/endpoint/collections/{collectionUUID}/domains

POST /apps/v1/endpoint/collections/{collectionUUID}/domains HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "domains": [
    {
      "name": "text"
    }
  ]
}

{
  "domains": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "source": "MANUAL",
      "updatedAt": "2026-06-10T15:57:24.928Z"
    }
  ],
  "failedDomains": [
    "text"
  ]
}

Remove a domain from a collection

delete

Soft-deletes a single domain from a collection.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

UUID of the parent collection

domainUUIDstring · uuidRequired

UUID of the domain to remove

Responses

204

Domain deleted

No content

400

Invalid collection or domain ID

application/json

401

Authentication failure

application/json

404

Collection or domain not found

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

delete

/endpoint/collections/{collectionUUID}/domains/{domainUUID}

DELETE /apps/v1/endpoint/collections/{collectionUUID}/domains/{domainUUID} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List endpoint MCP server collections

get

Returns a paginated list of MCP server collections configured for the company.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1 · max: 100OptionalDefault: 50

pageTokenstringOptional

namePrefixstring · max: 255Optional

Responses

200

Successful response

application/json

400

Invalid request parameters

application/json

401

Authentication failure

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/endpoint/mcp-collections

GET /apps/v1/endpoint/mcp-collections HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "collections": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "source": "MANUAL",
      "totalItems": 1
    }
  ],
  "total": 1,
  "nextPageToken": "text"
}

Create an MCP server collection

post

Creates a new manual MCP server collection. Collection names are case-insensitive unique per company.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

namestring · min: 1 · max: 255Required

Responses

201

Collection created

application/json

400

Invalid request body

application/json

401

Authentication failure

application/json

409

A collection with the same name already exists

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

post

/endpoint/mcp-collections

POST /apps/v1/endpoint/mcp-collections HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "source": "MANUAL",
  "itemCount": 1,
  "updatedAt": "2026-06-10T15:57:24.928Z"
}

Update an MCP server collection

put

Renames an existing manual MCP server collection. System collections cannot be renamed.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

Body

namestring · min: 1 · max: 255Required

Responses

200

Collection updated

application/json

400

Invalid request

application/json

401

Authentication failure

application/json

404

Collection not found

application/json

409

A collection with the same name already exists

application/json

422

Collection cannot be changed

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

put

/endpoint/mcp-collections/{collectionUUID}

PUT /apps/v1/endpoint/mcp-collections/{collectionUUID} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "source": "MANUAL",
  "itemCount": 1,
  "updatedAt": "2026-06-10T15:57:24.928Z"
}

Delete an MCP server collection

delete

Soft-deletes a manual MCP server collection.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

Responses

204

Collection deleted

No content

400

Invalid collection ID

application/json

401

Authentication failure

application/json

404

Collection not found

application/json

422

Collection cannot be changed

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

delete

/endpoint/mcp-collections/{collectionUUID}

DELETE /apps/v1/endpoint/mcp-collections/{collectionUUID} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List items (server scopes) in an MCP server collection

get

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

Query parameters

limitinteger · min: 1 · max: 100OptionalDefault: 50

pageTokenstringOptional

Responses

200

Successful response

application/json

400

Invalid request

application/json

401

Authentication failure

application/json

404

Collection not found

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

get

/endpoint/mcp-collections/{collectionUUID}/items

GET /apps/v1/endpoint/mcp-collections/{collectionUUID}/items HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "serverScope": {
        "serverName": "text",
        "toolNames": [
          "text"
        ]
      },
      "updatedAt": "2026-06-10T15:57:24.928Z"
    }
  ],
  "total": 1,
  "nextPageToken": "text"
}

Add items (server scopes) to an MCP server collection

post

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".

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

Body

Responses

200

Items added

application/json

400

Invalid request body

application/json

401

Authentication failure

application/json

404

Collection not found

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

post

/endpoint/mcp-collections/{collectionUUID}/items

POST /apps/v1/endpoint/mcp-collections/{collectionUUID}/items HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54

{
  "items": [
    {
      "serverName": "text",
      "toolNames": [
        "text"
      ]
    }
  ]
}

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "serverScope": {
        "serverName": "text",
        "toolNames": [
          "text"
        ]
      },
      "updatedAt": "2026-06-10T15:57:24.928Z"
    }
  ]
}

Remove an item from an MCP server collection

delete

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

collectionUUIDstring · uuidRequired

itemUUIDstring · uuidRequired

Responses

204

Item deleted

No content

400

Invalid collection or item ID

application/json

401

Authentication failure

application/json

404

Collection or item not found

application/json

429

Rate Limit Exceeded or Daily Quota Exceeded

application/json

500

Internal Nightfall Error

application/json

delete

/endpoint/mcp-collections/{collectionUUID}/items/{itemUUID}

DELETE /apps/v1/endpoint/mcp-collections/{collectionUUID}/items/{itemUUID} HTTP/1.1
Host: api.nightfall.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

PreviousPosture Management APIs NextAI Governance API's

Last updated 13 days ago

Was this helpful?