Intelligence Requirements

An Intelligence Requirement (IR) is a collection of topics or a research question reflecting an organization’s cyber threat–related priorities that guides a security or threat intelligence team’s research and analysis efforts.

Endpoint: /api/v3/intelRequirements

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/intelRequirements endpoint:

OPTIONS /v3/intelRequirements

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/intelRequirements endpoint:

OPTIONS /v3/intelRequirements/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/intelRequirements endpoint:

OPTIONS /v3/intelRequirements/tql

Schemas

Request Body (POST)

The following is the request body schema for a POST request to the /v3/intelRequirements endpoint:

active: <Boolean> Specifies whether the IR’s status is set to active (true) or inactive (false). When an IR is active, it is currently retrieving results (or will retrieve results after the start date of its query data range is reached). When an IR is inactive, it is no longer retrieving results. If an IR has a query date range and the current date and time are before the end date of the query date range, the IR’s status is automatically set to active. Once the end date for the query date range is reached, the IR’s status is automatically set to inactive.
associatedArtifacts: <Object> A list of Artifacts associated to the IR.
- data: <Array of Artifact Objects> The details of the Artifacts.
associatedCases: <Object> A list of Cases associated to the IR.
- data: <Array of Case Objects> The details of the Cases.
associatedGroups: <Object> A list of Groups associated to the IR.
- data: <Array of Group Objects> The details of the Groups.
associatedIndicators: <Object> A list of Indicators associated to the IR.
- data: <Array of Indicator Objects> The details of the Indicators.
associatedVictimAssets: <Object> A list of Victim Assets associated to the IR.
- data: <Array of Victim Asset Objects> The details of the Victim Assets.
category: <Object> The IR’s category. To specify the category, use its ID number, name, or both.
- id: <Integer> The IR category’s ID number.
- name: <String> The IR category’s name.
description: <String> A description of the IR.
earliestTimestamp: <DateTime> The start date in an IR query date range (ISO 8601).
keywordSections: <Array> REQUIRED The sections that the IR’s keyword query contains.
- compareValue: <String> REQUIRED Specifies whether the section is an includes or excludes section. (Accepted values: includes, excludes)
- keywords: <Array of Objects> REQUIRED A list of keywords that the section contains. Note that the total number of keywords added to an IR must not exceed the IR keyword limit configured by your System Administrator (the default limit is 300 keywords). Otherwise, a 400 Bad Request error will be returned.
  
  value: <String> REQUIRED The keyword’s value. For best practices on defining keywords in IR keyword queries, see the Best Practices: Keywords for Intelligence Requirements knowledge base article.
- sectionNumber: <Integer> REQUIRED The section number for the keyword section.
latestTimestamp: <DateTime> The end date in an IR query date range (ISO 8601).
requirementText: <String> REQUIRED The IR’s summary (i.e., the question, topic, or statement on which the IR focuses). The summary provided cannot be the same as the summary for an existing IR on the ThreatConnect instance.
resetResults: <Boolean> Specifies whether to include results that have been archived or marked as false results the next time results are retrieved for the IR.
subtype: <Object> REQUIRED The IR’s subtype.
- id: <Integer> REQUIRED The ID of the subtype.
tags: <Object> A list of Tags applied to the IR.
- data: <Array of Tag Objects> The details of the Tags.
uniqueId: <String> REQUIRED The IR’s unique ID. The ID provided cannot be the same as the ID for an existing IR on the ThreatConnect instance.
xid: <String> The IR’s unique XID. The XID provided cannot be the same as the XID for an existing IR on the ThreatConnect instance.

Example

{
    "active": true,
    "associatedArtifacts": {
        "data": [
            {
                "<artifactsFieldName>": "<artifactsFieldValue>"
            }
        ]
    },
    "associatedCases": {
        "data": [
            {
                "<casesFieldName>": "<casesFieldValue>"
            }
        ]
    },
    "associatedGroups": {
        "data": [
            {
                "<groupsFieldName>": "<groupsFieldValue>"
            }
        ]
    },
    "associatedIndicators": {
        "data": [
            {
                "<indicatorsFieldName>": "<indicatorsFieldValue>"
            }
        ]
    },