API Documentation

All of Driftnet's features are fully available via API. This page provides a conversational quick-start guide to the API. For users who prefer structured documentation, an OpenAPI specification is also available.

The examples on this page use the curl and jq utilities. Install them using your operating system's package manager, or from here and here.

All API calls must be authenticated. This is achieved by adding an Authorization HTTP header containing your API token:

Authorization: Bearer <your-api-token>

To get an API token with free quota, sign up for an account.

You can retrieve information on your user account by caling the admin/user endpoint:

curl -s -H 'Authorization: Bearer <your-api-token>' \
     'https://api.driftnet.io/v1/admin/user' \
  | jq .

{
  "created": "2019-05-13T11:16:52.000Z",
  "email": "[email protected]",
  "marketing": false,
  "name": "John Doe",
  "quota": {
    "api_limit": 500,
    "api_usage": 0,
    "last_used": 2019-05-13T11:16:52.000Z,
    "lifetime_usage": 0,
    "next_reset": "2019-06-13T11:16:52.000Z",
    "priority_limit": 0,
    "priority_usage": 0,
    "reset": "2019-05-13T11:16:52.000Z",
  },
  "token": "<your-api-token>",
  "user_class": "network_admin"
}

The api_ and priority_ numbers show the current usage and limit values for standard API and prioritization operations, respectively.

The lifetime_usage number shows the total number of calls (standard + prioritization) made over all time.

reset is the last time the quota was refreshed, and next_reset is the next time that it will be refreshed.

last_used is the last time the associated token was used against the API. Only present if the token has ever been used.

Users with split quota will have an additional_quota array describing quota usage against their non-primary tokens.

There is a concurrency limit which is applied per token. Currently, each token is restricted to five concurrent queries.

Searches are limited to returning a maximum of 100 pages of data (10,000 results).

Prioritization operations are limited to an average of five prioritizations per second, calculated over a rolling ten-minute window.