Public API Specification

Welcome to the Flightdeck API by dope.security. Modify custom categories, get endpoint statuses, and more via API! Stay tuned for upcoming updates that will enhance the capabilities and features of this API.

For details on how to create API client credentials please see API Client Credentials.

Generate Flightdeck API access token

post

Use this API to generate an access token for use with the Flightdeck API. A valid access token returned from this API is required in all other Flightdeck API calls.

Token generation is based on the OAuth 2.0 Client Credentials Flow. The returned token is used within the HTTP Authorization header as follows:

Authorization: Bearer <access token>

Note:

• The required client_id and client_secret are created by an admin via the dope console.

• Returned access tokens are valid for a limited time period. Clients must check the expires_in value in the response to generate a new access token before the current one expires.

• The OAuth scopes parameter is not supported and if provided will be ignored. The scopes returned in the access token are set directly by the authorization server.

Body

application/json

grant_typestring · enumRequired

The type of grant requested. You must set this to client_credentials

Possible values:

client_idstringRequired

Your application's Client ID.

client_secretstringRequired

Your application's Client Secret.

Responses

200

OK

application/json

access_tokenstringRequired

The new access token.

Example: eyJz93a...k4laUWw

token_typestring · enumRequired

The type of token returned.

Possible values:

expires_innumberRequired

The expiration time of the new access token in seconds.

Example: 3600

400

Bad request

application/json

401

Client not authorized

application/json

500

Internal server error.

application/json

post

/partner/oauth/token

HTTPcURLJavaScriptPython

POST /v1/partner/oauth/token HTTP/1.1
Host: api.flightdeck.dope.security
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "grant_type": "client_credentials",
  "client_id": "text",
  "client_secret": "text"
}

{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "bearer",
  "expires_in": 3600
}

List and Search Endpoints

get

Use this API to get a list of all endpoints, or search for those matching a query parameter.

Note:

• To return a list of all endpoints do not include any additional parameter.

• Only one of the optional parameters is allowed to be specified per request.

• Results are returned in pages using cursor based pagination and ordered by the lastSeen property.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

idstringOptional

Broad search query across endpoints by device, user and email identities that contain this string (case-insensitive)

emailIdstringOptional

Search by email ids that contain this string (case-insensitive)

deviceNamestringOptional

Search by device names that contain this string (case-insensitive)

userIdstringOptional

Search by user ids that contain this string (case-insensitive). userId for OIDC users is usually their email address.

osVersionstringOptional

Filter by this exact device OS version string

fallbackModestring · enumOptional

Filter by the fallback mode

Possible values:

locationIdstringOptional

Filter by this exact location id - with an underscore separating the case sensitive city and country values e.g. "City_Country"

agentVersionstringOptional

Filter by this exact agent version

firstnumberOptional

An optional pagination param that states the number of records requested from the start of the cursor. The default value is 50 and the maximum value is 1,000

afterstringOptional

An optional pagination cursor. The API will return the items after this cursor, according to default sort. Use the value returned in the previous endCursor response.

orderstring · enumOptional

The direction of the sort by the lastSeen property. The default is to sort by descending

Possible values:

Responses

200

OK

application/json

400

Bad request

application/json

403

Access denied

application/json

500

Internal server error.

application/json

get

/endpoints/search

HTTPcURLJavaScriptPython

GET /v1/endpoints/search HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "pageInfo": {
      "endCursor": "text",
      "hasNextPage": true
    },
    "endpoints": [
      {
        "adminSetState": {
          "enabled": true,
          "timestamp": "2024-04-10T00:00:00+00:00"
        },
        "agentUUID": "10e68510c-0885-4943-a8b0-b6feb29a9f81",
        "userUUID": "24c38805-1289-44fa-b974-2071a1702ba9",
        "agentVersion": "1.0.00000",
        "binaryType": "x86",
        "cityName": "Cork",
        "region": "Munster",
        "countryName": "Ireland",
        "cpuFamily": "Apple M1 Max",
        "debugState": "1",
        "deviceName": "Dope-MacBook-Pro.local",
        "disableMode": false,
        "errorMessage": "Agent is not running.",
        "fallbackMode": false,
        "configurationLastUpdated": "2023-10-10T10:10:00-0000",
        "osVersion": "Mac13",
        "policyName": "Base Policy",
        "realtimeConnection": true,
        "status": "healthy",
        "lastSeen": "2023-10-10T10:10:00-0000",
        "userId": "dope-user",
        "emailId": "[email protected]"
      }
    ]
  }
}

List Custom Categories

get

Use this API to get a paginated list of all custom categories.

Results are returned in pages using cursor based pagination.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

firstnumberOptional

An optional pagination param that states the number of records requested from the start of the cursor. The default value is 50.

afterstringOptional

An optional pagination cursor. The API will return the items after this cursor, according to default sort. Use the value returned in the previous endCursor response.

Responses

200

OK

application/json

403

Access denied

application/json

500

Internal server error.

application/json

get

/custom_categories

HTTPcURLJavaScriptPython

GET /v1/custom_categories HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "pageInfo": {
      "endCursor": "abc123",
      "hasNextPage": true
    },
    "customCategories": [
      "Gambling",
      "Social Media",
      "Streaming"
    ]
  }
}

Create a Custom Category

post

Use this API to create a new custom category.

Specify the name of the custom category in the path parameter (custom_category_name).

If the custom category already exists, a 400 error is returned.

Validation rules for custom_category_name:

• Must not be empty or whitespace-only

• Must not contain leading or trailing whitespace

• Maximum length of 32 characters

• Must not contain any of the following characters: # ! @ $ % ^ * ? . / \

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

custom_category_namestring · min: 1 · max: 32Required

The name of the custom category to create

Example: Streaming_Custom_CategoryPattern: ^[^#!@$%^*?./\\]+$

Responses

200

OK

application/json

A simple message response indicating a successful operation

messagestringRequired

Simple success message

Example: Success

400

Bad request - invalid custom category name or custom category already exists

application/json

403

Unauthorized access

application/json

500

Internal server error.

application/json

post

/custom_categories/{custom_category_name}

HTTPcURLJavaScriptPython

POST /v1/custom_categories/{custom_category_name} HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Success"
}

Delete a Custom Category

delete

Use this API to delete a single custom category by name. This action will remove the custom category and all of its associated data.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

custom_category_namestringRequired

The name of the custom category to delete

Example: Social Media

Responses

200

OK

application/json

A simple message response indicating a successful operation

messagestringRequired

Simple success message

Example: Success

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error.

application/json

delete

/custom_categories/{custom_category_name}

HTTPcURLJavaScriptPython

DELETE /v1/custom_categories/{custom_category_name} HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Success"
}

List all URLs of a Custom Category

get

Use this API to get all URLs of an existing custom category.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

custom_category_namestringRequired

The name of the custom category to get URLs from

Responses

200

OK

application/json

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error.

application/json

get

/custom_categories/{custom_category_name}/urls

HTTPcURLJavaScriptPython

GET /v1/custom_categories/{custom_category_name}/urls HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "urls": [
      "dope.security",
      "google.com"
    ]
  }
}

Add URLs to a Custom Category

post

Use this API to add URLs to an existing custom category.

Specify the name of the custom category in the path parameter (custom_category_name) and provide a JSON array of URLs in the request body.

Ensure that URLs are properly formatted and included in the array.

Please check the docs at https://inflight.dope.security for guidelines on URL formatting.

If any URL in the list is invalid, the entire request will be rejected. The 400 error response will include the list of invalid URLs in the error details.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

custom_category_namestringRequired

The name of the custom category to add URLs to

Body

application/json

Responses

200

OK

application/json

A simple message response indicating a successful operation

messagestringRequired

Simple success message

Example: Success

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error.

application/json

post

/custom_categories/{custom_category_name}/urls

HTTPcURLJavaScriptPython

POST /v1/custom_categories/{custom_category_name}/urls HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "data": {
    "urls": [
      "dope.security",
      "google.com"
    ]
  }
}

{
  "message": "Success"
}

Overwrite all URLs of a Custom Category

put

Use this API to replace all existing URLs of a custom category with a new list of URLs.

Specify the name of the custom category in the path parameter (custom_category_name) and provide a JSON array of URLs in the request body. All existing URLs will be removed and replaced with the provided list.

Please check the docs at https://inflight.dope.security for guidelines on URL formatting.

If any URL in the list is invalid, the entire request will be rejected. The 400 error response will include the list of invalid URLs in the error details.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

custom_category_namestringRequired

The name of the custom category to overwrite URLs for

Example: AI-ML Chatbots

Body

application/json

Responses

200

OK

application/json

A simple message response indicating a successful operation

messagestringRequired

Simple success message

Example: Success

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error.

application/json

put

/custom_categories/{custom_category_name}/urls

HTTPcURLJavaScriptPython

PUT /v1/custom_categories/{custom_category_name}/urls HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "data": {
    "urls": [
      "chat.openai.com",
      "gemini.google.com",
      "copilot.microsoft.com"
    ]
  }
}

{
  "message": "Success"
}

Delete All URLs from a Custom Category

delete

Use this API to delete all URLs from an existing custom category.

Specify the name of the custom category in the path parameter (custom_category_name).

This action will remove all URLs associated with the specified custom category.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

custom_category_namestringRequired

The name of the custom category to delete all URLs from

Responses

200

OK

application/json

A simple message response indicating a successful operation

messagestringRequired

Simple success message

Example: Success

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error.

application/json

delete

/custom_categories/{custom_category_name}/urls

HTTPcURLJavaScriptPython

DELETE /v1/custom_categories/{custom_category_name}/urls HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Success"
}

Delete a specific URL from a Custom Category

delete

Use this API to delete a specific URL from an existing custom category.

Specify the name of the custom category in the path parameter (custom_category_name).

Ensure that a given URL is encoded using URL encoding.

Authorizations

BearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

custom_category_namestringRequired

The name of the custom category to delete given URL from

encoded_urlstringRequired

The URL to be deleted (Ensure that URLs are properly URL-encoded using the UTF8 encoding method)

Example: https%3A%2F%2Fdope.security

Responses

200

OK

application/json

A simple message response indicating a successful operation

messagestringRequired

Simple success message

Example: Success

400

Bad request

application/json

403

Unauthorized access

application/json

500

Internal server error.

application/json

delete

/custom_categories/{custom_category_name}/url/{encoded_url}

HTTPcURLJavaScriptPython

DELETE /v1/custom_categories/{custom_category_name}/url/{encoded_url} HTTP/1.1
Host: api.flightdeck.dope.security
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Success"
}