# EclecticIQ Platform API Documentation > CAUTION: Do not use in production. > > The project is in-development. > > If you are a customer and wish to participate in the Platform API beta programme, > contact your customer success manager. ## API root and reference The API root is located at `https:///api/` GET the API root endpoint (`https:///api/`) to retrieve an OpenAPI 3-compatible specifications for the API. Installing the package on an EclecticIQ Platform instance lets you access the API reference, available through two interfaces: - Redoc interface, through `https:///api//docs`. This is a tidy and comprehensive interface that however lacks an interactive API console. - Swagger-UI interface, through `https:///api//swagger-ui`. An arguably less polished interface, but with full support for interaction with the endpoints. ## Schema All request and response payloads encapsulate parameters in a `data` object: ```javascript { "data": [ { // parameters } ] } ``` 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 ``` ## Authentication Requests are authenticated through the following HTTP header: ``` "Authorization: Bearer $EIQ_TOKEN" ``` ### Generate API tokens To generate an API token: - Open the EclecticIQ web interface - Select your profile (bottom-left corner of the screen) - Click _My Profile_ - Scroll to _API Tokens_ - Click _Create API Token_ ## 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: | Parameter | Description | | - | - | | `?limit=` | Set the number of items the endpoints should respond with. | | `?offset=` | Retrieve responses from a given endpoint starting from the (zero-based) index n. | 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//observables?filter[type]=ipv4 # To get only observables with the `value` '127.0.0.1' GET /api//observables?filter[value]=127.0.0.1 ``` You can also combine filters: ``` GET /api//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. So the SQL-like equivalent for the previous request would be: ```sql SELECT * FROM observables WHERE type IN ('city', 'country') AND value = 'Andorra' ``` You can also use relational operators for more advanced filtering, for example: ``` # To get entities that were created after certain time GET /api//entities?filter[>created_at]=2020-01-01T00:00:00+00:00 # To get entities that have `COVID` in their title GET /api//entities?filter[*data.title]=*COVID* ``` The syntax for relational operators is the following: `?filter[]=` The following operators are supported: | Operator | Description | | - | - | | `<` | Less than. | | `<=` | Lesser or equal than. | | `>` | Greater than. | | `<=` | Greater or equal than. | | `!` | Does not equal/not in. | | `*` | Wildcard. | ## 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//entities?attributes=created_at,data.title` ## Bulk requests The API supports bulk manipulation of objects on the following endpoints: - `PUT /api//`: create `` from the provided payload, or update them if they already exist (according to some unique attribute, e.g. `name` or ``). This is functionally equivalent to an idempotent `upsert` (insert or update) operation. The endpoint returns a `201` response code if at least one of the provided objects was newly created, `200` if all the objects existed and have been updated. - `DELETE /api//`: delete `` whose IDs are provided as a list on the JSON payload, e.g. `{"data": [1, 2, 3, 4]}`. NOTE: for performance reasons, bulk operations are handled within the same transaction. This means that the whole request fails if at least the handling of one record failed. This also minimizes the risk of data inconsistency caused by partially succeeded transactions.

400Invalid request

401Unauthorized request

403Missing permissions

404Element not found

409The element already exists