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