# EclecticIQ Platform API Documentation ## API root and reference The API root is located at `https:///api/v2` GET the API root endpoint (`https:///api/v2`) 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 Redoc interface, through `https:///api/v2/docs/`. ## 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 `100` items per page by default. To retrieve more than `100` 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. | Except if mentioned otherwise on the endpoint documentation, the maximum page size is limited to `1000`. For more results, multiple calls must be made. The `count` field at the top level response shows the number of document as part of the response. The total number of resources matching a request are visible in the `total_count` field at the top level response. To retrieve only the total number of resources matching a request, the query parameter `data` set to `false` must be added to the request. The `count` field will be present at the response top level with the value. ## 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/v2/observables?filter[type]=ipv4 # To get only observables with the `value` '127.0.0.1' GET /api/v2/observables?filter[value]=127.0.0.1 ``` You can also combine filters: ``` GET /api/v2/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/v2/entities?filter[>created_at]=2020-01-01T00:00:00+00:00 # To get entities that have `COVID` in their title GET /api/v2/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. | NOTE: often when multiple filters are applied to a resource, the complete request URL can grow significantly, but for security reasons the length of a request-URL is restricted to 8k characters. If request line exceeds this size, `414 (Request-URI Too Large)` error is returned to the client. ## 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/v2/entities?attributes=created_at,data.title` If a client does not specify the set of fields for a given resource type, the server returns all fields. ## Missing Top-Level Resource Permission EclecticIQ provides a permission mechanism to define which top-level resource a user can access. A permission is separated in `read` and `modify`. A `modify` permission implies a `read` one. When such permission is missing, the API response is `403`. It could originate either from the main top-level resource or a related top-level resource used through a property. ## Missing Individual Resource Access Some individual resource may require additional permission to be accessed. For example to fetch an entity, one must have the `read entities` permission but also access to at least one of the source the entity is from. If only an individual resource can not be accessed then a `404` is returned. It is not a `403` to hide the existence of such object. It could originate either from the main individual resource or a related individual resource used through a property. ## Bulk requests The API supports bulk manipulation of objects on the following endpoints: - `PUT /api/v2/`: 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/v2/`: 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. ## Update Resource Relationships An update on a relationships fields will overwrite all the related values: Example for an entity with those datasets: ``` GET /api/v2/entities/10d0fc3e-5bf3-4065-9d28-a3125c1be200?attributes=datasets HTTP/1.1 200 OK { "data": { "datasets": [ "https://host.com/api/v2/datasets/2", ] } } ``` If the `datasets` field is updated like this: ``` PATCH /api/v2/entities/10d0fc3e-5bf3-4065-9d28-a3125c1be200 { "data": { "datasets": [ "https://host.com/api/v2/datasets/1", "https://host.com/api/v2/datasets/3" ] } } HTTP/1.1 200 OK ``` Then, it will overwrite the existing ones with the one in the update query: ``` GET /api/v2/entities/10d0fc3e-5bf3-4065-9d28-a3125c1be200?attributes=datasets HTTP/1.1 200 OK { "data": { "datasets": [ "https://host.com/api/v2/datasets/1", "https://host.com/api/v2/datasets/3" ] } } ``` In order to control the relationships atomically, please refer to: - `PUT /api/v2/entities//datasets` - `DELETE /api/v2/entities//datasets` - `PUT /api/v2/entities//datasets/` - `DELETE /api/v2/entities//datasets/` ## URI Length Restriction The API relies on `GET` endpoints to query the data. Some requests may contain many filters like `?filter[id]=id1&filter[id]=id2&...&filter[id]=id1000` that result in very long URI. The server may put a restriction on this length and reject it with a `414`. To circumvent it, it is possible to convert any `GET` call to a `POST` alternative. The same URI path must be used but the query string is moved to the payload and the header `Content-Type` is `application/x-www-form-urlencoded`. The query string schemata are respecting the same one that the equivalent `GET` endpoint. Also, those `POST` endpoints return `200` on success. For a POST request, if both a payload as `application/x-www-form-urlencoded` and a query string is provided then the latter is ignored and only the payload will be used. Original GET call: ```http GET https://example.com/api/v2/attacks ?filter[id]=TA0001 &filter[matrix]=ics-attack ``` Converted POST call: ```http POST https://example.com/api/v2/attacks HTTP/1.1 Content-Type: application/x-www-form-urlencoded filter[id]=TA0001&filter[matrix]=ics-attack ``` ## Datetime A datetime field is based on the ISO 8601 format. - As input, any format is supported like `2024-01-01` or `2025-06-01T22:50:36+00:00` - The returned value is always the full format with a timezone like `2017-11-30T10:04:07.890853+00:00`. By default UTC, but it may be aligned to another one if specified by the API. If the datetime is provided as a filter, the same input requirements are applied. As a result the timezone is honored as well. If the timezone is not provided in the input, the system will infer in this order of priority: 1. The user preference 2. The IC preference 3. UTC # Release Notes ## V2 ### Changes - Added `GET /api/v2/csv-mappings/supported-fields` to list all supported Entity fields that can be used by CSV Mappings. - Added `/api/v2/csv-mappings` and `/api/v2/csv-mappings/` APIs to provide complete CRUD operations for CSV Mapping Configurations, which are later used in Uploaded Blobs or Incoming Feeds for ingestion of CSV files. - Added `PATCH /api/v2/relationships/` to update a single entity relation. - The `/api/v2/relationships` endpoints accept new fields: `data.description`, `meta.estimated_threat_start_time`, `meta.estimated_threat_end_time` and `meta.tlp_color`. - Added `PUT /api/v2/relationships` to allow bulk upserting of entity relations. - Added `GET /api/v2/aggregations/entities/counts` to get count entities aggregation on the field value usages, for specific set of fields. - A response from the endpoint `/api/v2/relationships` can return `strict_stix_1` and `strict_stix_2` fields. - Performance change: endpoints querying the total count in PostgreSQL (i.e. `GET /api/v2/observables/`) will return an estimated count of total entries if there are more entries than a set number. Default is `10_000`. - Added new entity types: - Attack Pattern - Location - Malware - Tool - Infrastructure - Intrusion set - Identity - Malware Analysis - Added `remove_taxonomies` field on entity rule, a list of taxonomies removed from the matched entity if the rule has `remove_tags` action. - Added `remove_tags` field on entity rule, a list of tags removed from the matched entity if the rule has `remove_tags` action. - Added `eiqjson2_entity_type` field on entity rule, which is a required target type for conversion if the rule has `convert_to_eiqjson2` action. - Added `GET /api/v2/content-blocks` to list content blocks. - Added `GET /api/v2/content-blocks/` to get content block by id. - It is possible to attach `attachments` on `/api/v2/entities` to any entity type and not only `report`. - For `/api/v2/entities`, as a security measure, it is not possible to reference an attachment as an image `

` in `data.description` or `data.short_description` without having that attachment also related in `attachments`. If this is not respected a `400` is returned. - The `/api/v2/tickets` API accepts the blank value `""` for `status`. If no `status` is provided, then `"OPEN"` is the default instead of `""`. - The `/api/v2/observables` API allows to filter by `filter[entities]=` to return only the observables related to that entity. - Added `POST /api/v2/entities/relational-search` that exposes `search entities by relationships`. - Added `POST /api/v2/entities/update-tasks` to start a background task that apply a change to the entities that match the specified search query. - Added `POST /api/v2/entities/delete-tasks` to start a background task that delete the entities that match the specified search query. - Added `POST /api/v2/entities/enrich-tasks` to start a background task that enrich the observables of entities that match the specified search query. - Added `POST /api/v2/entities/export-tasks` to expose possibility to export the entities that match the specified search query in a specified content-type. - Added `GET /api/v2/uploaded-blobs` and `GET /api/v2/uploaded-blobs/` that lists and gets uploaded blobs. - Added `POST /api/v2/uploaded-blobs` to expose IC functionality for files/blobs upload. - Added `filter[_lucene_search]` entity and relation filter that exposes Lucene for advanced queries, which should be on par with search in UI. - Added the capacity for the attachment created with `POST /api/v2/attachments` to be attached to some `entities` at the creation time. - Added `GET /api/v2/export-blocks//content` to allow downloading of files generated by bulk export. - Added `meta.is_unresolved_idref`, `meta.ingest_time` and `meta.first_ingest_time` attributes to the `Entity` endpoints. - Added `user_data` attribute on the `User` resource. It contains settings related to the user. - Deprecate `/api/v2/files//download` and `/api/v2/attachments//download` endpoints. - Added `/api/v2/files//content` and `/api/v2/attachments//content` endpoints instead of deprecated `/download`. - Added `default_source` to the `User` endpoint. - On `Entity` creation, the `sources`, `data.confidence` and `meta.tlp_color` is automatically set based on the `User`'s defaults if defined. Those are respectively in the `User` at `default_source`, `user_data.default_values.entity.confidence` and `user_data.default_values.entity.tlp`. - Added `POST /api/v2/observables/export-tasks` to expose possibility to export the observables that match the specified search query in a specified content-type. - Added a new parameter `include_indirectly_related` to the request payload of `POST /api/v2/entities/relational-search` to also include the entities that are indirectly related. - Added new entity type: Note. - Added validation for POST `/api/v2/rules/entities/observables` and PUT `/api/v2/rules/observables/` to verify that at least one of parameters serving as matching criteria for a rule is present. - Added `'relational_search'` field to dataset object for `/api/v2/datasets/` endpoints. - Added `relational_query` parameter for `/api/v2/entities/export-tasks` . Either `entities_query` or `relational_query` must be provided for a task. - Added `relational_query` parameter for `/api/v2/entities/update-tasks` . Either `entities_query` or `relational_query` must be provided for a task. - Added `relational_query` parameter for `/api/v2/entities/delete-tasks` . Either `entities_query` or `relational_query` must be provided for a task. - Added `relational_query` parameter for `/api/v2/entities/enrich-tasks` . Either `entities_query` or `relational_query` must be provided for a task. - Added `POST /api/v2/datasets//delete-tasks` endpoint for removing dataset in a background task. - Added `POST /api/v2/observables/update-tasks` to expose possibility to update the observables that match the specified search query. - Added `POST /api/v2/observables/enrich-tasks` to expose possibility to enrich the observables that match the specified search query. - Added `POST /api/v2/observables/delete-tasks` to expose possibility to delete the observables that match the specified search query. - Added `/api/v2/attack-analyses` and `/api/v2/attack-analysis-annotations` to expose Attack Analysis resource and its related Note resource. - Added `PUT/DELETE /api/v2/attack-analyses//entities` and `PUT/DELETE /api/v2/attack-analyses//datasets/` endpoints to manage the attack analysis scope. - Added `meta.total_resources_aggregated` to the payload of `GET /api/v2/aggregations/entities/counts` to know how many entities were aggregated. - Added `PUT /api/v2/datasets//entities` to expose possibility to update the dataset with passed entities. - Added `POST /api/v2/datasets//add-tasks` to expose possibility to update the dataset with entities that match the query. - Added the capacity to filter Attack by matrix with `/api/v2/attacks?filter[matrix]=enterprise-attack`. - Added `entities` parameter to the request payload of `POST /api/v2/datasets` to include entities in dataset on creation. - Added `ignore_exemptions` flag for `/api/v2/entities/delete-tasks` to control exemptions for deletion. - Added `time_zone` parameter for `/api/v2/entities/export-tasks`, `/api/v2/entities/update-tasks`, `/api/v2/entities/delete-tasks`, `/api/v2/entities/enrich-tasks`, `/api/v2/observables/update-tasks`, ` /api/v2/observables/enrich-tasks`, `/api/v2/observables/enxport-tasks`, `/api/v2/observables/enxport-tasks`, `/api/v2/datasets//add-tasks` to specify timezone - Added `/api/v2/attack-defenses` and `/api/v2/attack-defense-relationships` to fetch the ATTACK objects `data-source`. `data-component`, `mitigation` and their relationships to techniques (`mitigates` and `detects`). - Added the capacity to call any `GET` endpoint with a `POST` alternative to circumvent the URI length limit. Please refer to the documentation for more information. - Added support for a new configuration available for a discovery rule (`api/v2/discovery_rules`). - Added `attack classifications` as a filter on `/api/v2/entities` and also as a aggregatable field on `/api/v2/aggregations/entities/counts`. The field behaves like `meta.attacks` except that it does not include the ATT&CK parents if they are not explicitly used in classifications. - Added `/api/v2/risk-score/policies` route to expose creation/modification/deletion/viewing Observable Risk Score Policies. - Added GET `/api/v2/risk-score/policies//parameters` endpoint to expose listing of Parameters for an Observable Risk Score Policy. - Added `GET/PATCH /api/v2/risk-score/policies//parameters/` to expose fetching a parameter object and modifying state of a parameter. - Added `/api/v2/widgets` endpoints to manage the Widget resource. - Added `GET/PATCH/DELETE /api/v2/risk-score/policies//parameters//values/` and `GET/POST/DELETE /api/v2/risk-score/policies//parameters//values/` to expose creating/fetching/modifying and deleting a parameter value objects. - Added `/api/v2/dashboards` route to expose creation/modification/deletion/viewing dashboards - Added `filter[_lucene_search]` capacity on `/api/v2/observables`. - Added `/api/v2/dashboards` route to expose creation/modification/deletion/viewing dashboards. - Added GET`/api/v2/observables//score-updates` endpoint to allow querying risk score modifications for an observable and POST`/api/v2/observables//score-updates` endpoint to allow user to modify score. - Added `/api/v2/overview-dashboards` route to expose creation/modification/deletion/viewing overview dashboards - Added POST `/api/v2/risk-score/policies/` route to make possible to view the information about task run groups, with an overview of the number of tasks it includes and their statuses. - Added `/api/v2/report-templates` route to expose creation/modification/deletion/viewing of report templates. - Added `/api/v2/content-generation-prompts` resource to expose creation/modification/deletion/viewing of content generation prompts for AI providers. - Added `/api/v2/font-families` route to expose viewing/upload/deletion of font families. - Added `/api/v2/fonts` route to expose download of fonts. - Added `/api/v2/notifications` route to expose viewing of notifications and marking them read. - Added `/api/v2/custom-attributes` route to expose creation/modification/deletion/viewing/aggregations/mappings of custom attributes. - Added `/api/v2/custom-entity-schemas` route to expose creation/modification/deletion/viewing/aggregations of custom entity schemas. ### Breaking Changes - Added: The payload of `/api/v2/relationships` requires a `sources` property. By providing a list of source ids, you can define the relationship sources. - The `/api/v2/relationships` endpoints expect that `data.key` better aligns with our new model based on STIX 2.1. The value of this property must be in ASCII, no longer than 256 characters and is limited to characters a–z (lowercase ASCII), 0–9, and hyphen (-). - The `/api/v2/relationships` endpoints expect that `data.subtype` can only accept `stix_update_of` value. - The `type` of an entity is now nested inside the data dictionary. See old behaviour first: ```json { "type": "indicator", "data": { "title": "Entity Old", "description": "Test entity with old schema" }, "meta": {} } ``` In the new example the type field is nested inside: ```json { "data": { "type": "indicator", "title": "Entity New", "description": "Test entity with new schema" }, "meta": {} } ``` - The field `data.source` property of `/api/v2/entities/rules` is replaced with `data.sources` which contain an array of sources' ids which the rule applies to. If the array is empty, the rule is applied to all sources. - `taxonomies` field is renamed to `add_taxonomies` - `overwrite_tags` and `overwrite_taxonomies` query parameters are no longer supported - The payload of `/api/v2/datasets` requires at least one relationship for `workspaces`. The `workspaces` relationship field is also returned on the response. - The payload for a `PUT` request does not require a another nested `data` property. From: ```json { "data": [{ "data": {} }, { "data": {} }] } ``` To: ```json { "data": [{}, {}] } ``` - A query parameter to filter a related resource if the wrong id type is put will return a 400 instead of a 200 where the filter is ignored. Example: `GET /api/v2/tickets?filter[entities]=1111` will return `400` as `filter[entities]` is expecting a UUID. - Threat Actor schema is replaced with the strict EIQ JSON v2 schema - Required entity data fields normalised to `type` and `title` for all entity types ### Bug Fixes - Fixed: Knowledge packs can be deleted via API with only read knowledge pack permission - Update of `attachments` on `/api/v2/entities` used to be ignored. Now, the new `attachments` provided will overwrite the current ones. - The public API for relationship and entities used to not recognized STIX id of some format when queries like: `/api/v2/entities/{my-namespace}threat-actor-dc07abbd-ea1a-4ac1-acfd-e56328299635` or `/api/v2/entities/indicator--34818854-03ba-4b9a-b99b-319694c1d392`. A `400` was returned. Now, either a `200` with the entity is returned or a `404` if it does not exist. - Providing multiple values to a similar range filter used to only consider the first one. Both Entity and Relationship endpoints were impacted. Example: `?filter[>created_at]=2024-01-01&filter[>created_at]=2024-06-06` - Filter observables on `sources` is fixed: `/api/v2/observables?filter[sources]=`