Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
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
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-01-01T00:00:00.000Z",
      "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-01-01T00:00:00.000Z"
        }
      ]
    }
  ],
  "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
totalCollectionsinteger · int64Optional
nextPageTokenstringOptional

Next page cursor, omitted if end of results reached

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
idstring · uuidOptional

Collection identifier

namestringOptional

Collection name

sourcestring · enumOptional

How the collection was created. Only MANUAL collections are user-mutable.

Possible values:
updatedAtstring · date-timeOptional

Timestamp of the most recent update

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-01-01T00:00:00.000Z"
}

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
idstring · uuidOptional

Collection identifier

namestringOptional

Collection name

sourcestring · enumOptional

How the collection was created. Only MANUAL collections are user-mutable.

Possible values:
updatedAtstring · date-timeOptional

Timestamp of the most recent update

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-01-01T00:00:00.000Z"
}

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
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
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-01-01T00:00:00.000Z"
    }
  ]
}

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
failedDomainsstring[]Optional

Domain names rejected because they are personal-email providers and were targeted at the reserved corporate-domains collection. Omitted when empty.

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-01-01T00:00:00.000Z"
    }
  ],
  "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
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
totalinteger · int32Optional
nextPageTokenstringOptional
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
idstring · uuidOptional
namestringOptional
sourcestring · enumOptionalPossible values:
itemCountinteger · int32Optional
updatedAtstring · date-timeOptional
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-01-01T00:00:00.000Z"
}

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
idstring · uuidOptional
namestringOptional
sourcestring · enumOptionalPossible values:
itemCountinteger · int32Optional
updatedAtstring · date-timeOptional
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-01-01T00:00:00.000Z"
}

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
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
totalinteger · int32Optional
nextPageTokenstringOptional
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-01-01T00:00:00.000Z"
    }
  ],
  "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
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-01-01T00:00:00.000Z"
    }
  ]
}

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

Was this helpful?