Driftnet API

Overview

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.

Authenticating

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.

Viewing your user information

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]",
  "name": "John Doe",
  "marketing": false,
  "quota": {
    "api_limit": 500,
    "api_usage": 0,
    "lifetime_usage": 0,
    "next_reset": "2019-06-13T11:16:52.000Z",
    "priority_limit": 0,
    "priority_usage": 0,
    "reset": "2019-05-13T11:16:52.000Z",
    "ws_limit": 1,
    "ws_usage": 0
  },
  "token": "<your-api-token>"
}

The api_ and priority_ numbers show the current usage and limit values for standard API and prioritization operations, respectively. The ws_ numbers show limits on the number of saved projects ("working sets").

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.

API limitations

The API is not rate-limited, but 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.