Basic operations

Timestamps

Timestamps are returned in ISO 8601 format.

For example: 2017-11-30T10:04:07.890853+00:00

Content Type

All requests and responses should expect
the application/json content type:

Content-Type: application/json
Accept: application/json

Pagination

Responses contain a maximum of 200 items per page by default.

To retrieve more than 200 items from an endpoint
make your request with these parameters:

You can figure out the number of pages available
from an endpoint by looking at the total_count
field in the response body.

To retrieve only the total_count from an endpoint,
make your request with the ?data=false parameter.

Sorting

You can customize the sorting strategy for the GET
endpoints by using the ?sort argument on your query
string. The sort argument has the following format:

sort=field1,field2,-field3,...

Where each field identifies a payload attribute.
A field prefixed by the minus sign - will instruct
the API to apply descending sorting on that field -
ascending ordering is the default behaviour otherwise.

Filtering

Filter collections with the ?filter parameter.

For example:

# To get only observables of ipv4 `type`
GET /api/v1/observables?filter[type]=ipv4

# To get only observables with the `value` '127.0.0.1'
GET /api/v1/observables?filter[value]=127.0.0.1

You can also combine filters:

GET /api/v1/observables?filter[type]=city&filter[type]=country&filter[value]=Andorra

The following conventions apply:

1. If two filter parameters point to the same field (like type in the previous
   example), then they will be chained with an OR logic (in the previous example,
   type='city' OR type='country').
2. If two filter parameters point to different fields (like type and value
   in the previous example), then they will be chained with an AND logic.

You can also use relational operators for more advanced filtering, for example:

GET /api/v1/entities?filter[>created_at]=2020-01-01T00:00:00+00:00

The syntax for relational operators is the following:

?filter[<operator><field>]=<value>

The following operators are supported:

Response attributes

You can select which attributes should be returned on the GET responses through
the ?attributes parameter. Nested attributes are separated by dots "." (e.g.
data.timestamp).

For instance, if you only want to return created_at and data.title of the entities:

GET /api/v1/entities?attributes=created_at,data.title