Resource format

Collections are accessed as https://rest.threatstop.com/v4.0/collection_name, while objects are accessed as https://rest.threatstop.com/v4.0/collection_name/{id}.

:id is a generally a UUID.

Operations

The API operations use HTTP methods as follows:

Method Collection Object
GET Retrieve collection listing Retrieve single object
POST Create new object in collection Not applicable
PATCH Not applicable Update one or several object settings
PUT Not applicable Replace an object
DELETE Not available Delete the object

Headers

For requests that create (POST) or update (PATCH, PUT) an object, the data must be provided as a JSON object in the request body and the request must set a Content-Type: application/json header.

This header should not be included for requests that read (GET) an object and don’t include a request body.

API Responses

Status codes

The API returns the following HTTP codes:

Code Description
200 Successful request
201 Successfully created object
400 Error in request
401 Authentication not provided or incorrect
404 API key doesn’t provide access to this service/resource or it does not exist
500 Server side error

JSON objects

Objects are returned as JSON objects. The API outputs a header Content-Type: application/json.

For easier parsing, responses always contain an array, even if a single object is returned. The array is named _data and reachable as ._data[]. If the API response contains a single object, it is reachable as ._data[0].

Data types

Element Format Example
Booleans Case sensitive true, false
Country codes ISO 3166-1 List
Dates ISO-8601, UTC time zone 2018-01-01T20:30:45+00:00
Timestamps Unix timestamps 1559675417
UUID UUID4 format df1b1f2f-acf8-43eb-a3ff-ccb38e954acb

HATEOAS

Every request and every object output by the API contains a HATEOAS object to easily retrieve associated resources. For example, the Device service will return the policy associated with the device. The policy object will contain a link to the policy service for that object.

The object is named _links. It contains an object type and a link (href), e.g.:

{ 
  "_links": {
    "policy": { 
      "href": "https://rest.threatstop.com/v4.0/policies/df11dc61-e54f-4fe2-9f19-08d1d8970861"
    }
  }
}

Pagination

The output of some commands is paginated.

Pagination can be controlled with:

  • limit: the number of records to return; 20 is the default
  • offset: the first record returned in the response

When pagination is possible, the API response will contain a HATEOAS section called ._links. The section contains links to the current page (._links.self), to the previous page (_links.prev) and to the next page (._links.next) as applicable.

Error handling

Error responses (4xx codes) contain an extended error code, to help diagnose the cause of the error. The extended error contains the HTTP status (status_code), a general description (error_description), and when applicable, additional details (additional_info.error_code and additional_info.detail)

{
    "status_code": 400,
    "error_description": "Invalid argument",
    "additional_info": {
        "detail": "Invalid start date",
        "error_code": 10302
    }
}

Metadata

API responses contain a metadata section - see the documentation of the different services for its content.

Every API response will contain a request ID (._meta.request_id) which can be provided to ThreatSTOP support for troubleshooting purposes.

CORS

As of August 2020, CORS is supported by the API.

  • Allowed origins are configured on a per-API token.
  • In the token configuration page of the Admin Portal, enter the list of origins as a comma-separated list, e.g. htttps://www.mydomain.com, https://sub.mydomain.com