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:
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.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.
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
{
"associatedArtifacts": {
"data": [
{
"<artifactsFieldName>": <artifactsFieldValue>
}
]
},
"associatedCases": {
"data": [
{
"<casesFieldName>": <casesFieldValue>
}
]
},
"associatedGroups": {
"data": [
{
"<groupsFieldName>": <groupsFieldValue>
}
]
},
"associatedIndicators": {
"data": [
{
"<indicatorsFieldName>": <indicatorsFieldValue>
}
]
},
"associatedVictimAssets": {
"data": [
{
"<victimAssetsFieldName>": <victimAssetsFieldValue>
}
]
},
"category": {
"id": <int>,
"name": <string>
},
"description": "<string>",
"keywordSections": [
{
"compareValue": "<string>",
"keywords": [
{
"value": "<string>"
}
],
"sectionNumber": <int>
}
],
"requirementText": "<string>",
"resetResults": <boolean>,
"subtype": {
"id": <int>
},
"tags": {
"data": [
{
"<tagsFieldName>": <tagsFieldValue>
}
]
},
"uniqueId": "<string>",
"xid": "<string>"
}
Request Body (PUT)
The following is the request body schema for a PUT request to the /v3/intelRequirements endpoint:
associatedArtifacts: <Object> A list of Artifacts associated to the IR.data: <Array of Artifact Objects> The details of the Artifacts.mode: <String> Specifies the action to perform with the objects defined in thedatafield. (Accepted values: append, delete, replace; Default value: append).
associatedCases: <Object> A list of Cases associated to the IR.data: <Array of Case Objects> The details of the Cases.mode: <String> Specifies the action to perform with the objects defined in thedatafield. (Accepted values: append, delete, replace; Default value: append).
associatedGroups: <Object> A list of Groups associated to the IR.data: <Array of Group Objects> The details of the Groups.mode: <String> Specifies the action to perform with the objects defined in thedatafield. (Accepted values: append, delete, replace; Default value: append).
associatedIndicators: <Object> A list of Indicators associated to the IR.data: <Array of Indicator Objects> The details of the Indicators.mode: <String> Specifies the action to perform with the objects defined in thedatafield. (Accepted values: append, delete, replace; Default value: append).
associatedVictimAssets: <Object> A list of Victim Assets associated to the IR.data: <Array of Victim Asset Objects> The details of the Victim Assets.mode: <String> Specifies the action to perform with the objects defined in thedatafield. (Accepted values: append, delete, replace; Default value: append).
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.keywordSections: <Array> The sections that the IR’s keyword query contains.compareValue: <String> Specifies whether the section is an includes or excludes section. (Accepted values: includes, excludes)keywords: <Array of Objects> 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> 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> The section number for the keyword section.
requirementText: <String> 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> The IR’s subtype.id: <Integer> 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.mode: <String> Specifies the action to perform with the objects defined in thedatafield. (Accepted values: append, delete, replace; Default value: append).
uniqueId: <String> The IR’s unique ID. The ID provided cannot be the same as the ID for an existing IR on the ThreatConnect instance.
Example
{
"associatedArtifacts": {
"data": [
{
"<artifactsFieldName>": <artifactsFieldValue>
}
],
"mode": "<string>"
},
"associatedCases": {
"data": [
{
"<casesFieldName>": <casesFieldValue>
}
],
"mode": "<string>"
},
"associatedGroups": {
"data": [
{
"<groupsFieldName>": <groupsFieldValue>
}
],
"mode": "<string>"
},
"associatedIndicators": {
"data": [
{
"<indicatorsFieldName>": <indicatorsFieldValue>
}
],
"mode": "<string>"
},
"associatedVictimAssets": {
"data": [
{
"<victimAssetsFieldName>": <victimAssetsFieldValue>
}
],
"mode": "<string>"
},
"category": {
"id": <int>,
"name": <string>
},
"description": "<string>",
"keywordSections": [
{
"compareValue": "<string>",
"keywords": [
{
"value": "<string>"
}
],
"sectionNumber": <int>
}
],
"requirementText": "<string>",
"resetResults": <boolean>,
"subtype": {
"id": <int>
},
"tags": {
"data": [
{
"<tagsFieldName>": <tagsFieldValue>
}
],
"mode": "<string>"
},
"uniqueId": "<string>"
}
Response Body
The default response returned from successful GET, POST, and PUT requests to the /v3/intelRequirements endpoint includes one or more objects with the following fields:
id: <Integer> The IR’s ID number. Note that this is not the same ID as the one specified for the uniqueId field when the IR was created or updated.xid: <String> The IR’s XID. This field is only included in the response body when a value has been assigned to it.createdBy: <Object> The details of the user who created the IR.id: <Integer> The ID of the user’s account.username: <String> The username of the user’s account.firstName: <String> The user’s first name.lastName: <String> The user’s last name.pseudonym: <String> The user’s pseudonym.owner: <String> The Organization to which the user’s account belongs.
lastModified: <DateTime> The date and time when the IR was last modified (ISO 8601 format).webLink: <String> The URL for the IR’s Details screen in ThreatConnect.dateAdded: <DateTime> The date and time when the IR was created (ISO 8601 format).uniqueId: <String> The IR’s unique ID.requirementText: <String> The IR’s summary (i.e., the question, topic, or statement on which the IR focuses).subtype: <Object> The details of the IR’s subtype.name: <String> The name of the IR’s subtype.description: <String> A description of the IR’s subtype.
category: <Object> The details of the IR’s category. This field is only included in the response body when a value has been assigned to it.name: <String> The value of the IR’s category.description: <String> A description of the IR’s category.
description: <String> A description of the IR. This field is only included in the response body when a value has been assigned to it.keywordSections: <Array of Objects> The details of the sections that the IR’s keyword query contains.compareValue: <String> Specifies whether the section is an includes or excludes section.keywords: <Array of Objects> A list of keywords that the section contains.value: <String> The keyword’s value.
resultsLink: <String> A link to view the local and global results for the IR’s keyword query.
Example
{
"id": <int>,
"xid": "<string>",
"createdBy": {
"id": <int>,
"userName": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"pseudonym": "<string>",
"owner": "<string>"
},
"lastModified": "<datetime>",
"webLink": "<string>",
"dateAdded": "<datetime>",
"uniqueId": "<string>",
"requirementText": "<string>",
"subtype": {
"name": "<string>",
"description": "<string>
},
"category": {
"name": "<string>",
"description": "<string>"
},
"description": "<string>",
"keywordSections": [
{
"compareValue": "<string>",
"keywords": [
{
"value": "<string>"
}
]
}
],
"resultsLink": "<string>"
}
Create Intelligence Requirements
Send a request in the following format to create an IR in your Organization. Note that the request body in this example includes only a subset of the fields that can be included.
Request
POST /v3/intelRequirements
Content-Type: application/json
{
"category": {
"name": "CISO Priorities"
},
"description": "This IR is used to track threats to medical device companies.",
"keywordSections": [
{
"compareValue": "includes",
"keywords": [
{
"value": "medical device companies"
},
{
"value": "healthcare"
},
{
"value": "mangled spider"
},
{
"value": "threats to medical"
}
],
"sectionNumber": 0
},
{
"compareValue": "excludes",
"keywords": [
{
"value": "mrap"
}
],
"sectionNumber": 0
}
],
"requirementText": "Threats to Medical Device Companies",
"subtype": {
"id": 1
},
"uniqueId": "IR-010"
}
Response
{
"data": {
"id": 10,
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization"
},
"lastModified": "2023-09-18T14:06:26Z ",
"webLink": "https://app.threatconnect.com/#/details/intel-requirements/10/overview",
"dateAdded": "2023-09-18T14:06:24Z",
"uniqueId": "IR-010",
"requirementText": "Threats to Medical Device Companies",
"subtype": {
"name": "Intelligence Requirement (IR)",
"description": "Threats of overall concern to the organization (e.g., cyber, fraud, geopolitical/physical threats)"
},
"category": {
"name": "CISO Priorities",
"description": "IRs prioritized for the CISO"
},
"description": "This IR is used to track threats to medical device companies.",
"keywordSections": [
{
"compareValue": "includes",
"keywords": [
{
"value": "medical device companies"
},
{
"value": "healthcare"
},
{
"value": "mangled spider"
},
{
"value": "threats to medical"
}
]
},
{
"compareValue": "excludes",
"keywords": [
{
"value": "mrap"
}
]
}
],
"resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=10"
},
"message": "Created",
"status": "Success"
}
Retrieve Intelligence Requirements
Retrieve All Intelligence Requirements
Send the following request to retrieve data for all IRs:
Request
GET /v3/intelRequirements
Response
{
"data": [
{
"id": 1,
"createdBy": {
"id": 1,
"userName": "[email protected]",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmith",
"owner": "Demo Organization"
},
"lastModified": "2023-08-29T14:58:55Z",
"webLink": "https://app.threatconnect.com/#/details/intel-requirements/1/overview",
"dateAdded": "2023-08-29T13:18:01Z",
"uniqueId": "IR-001",
"requirementText": "Double Secret Probation",
"subtype": {
"name": "Intelligence Requirement (IR)",
"description": "Threats of overall concern to the organization (e.g., cyber, fraud, geopolitical/physical threats)"
},
"category": {
"name": "CISO Priorities",
"description": "IRs prioritized for the CISO"
},
"description": "Keeping an eye on Delta House",
"keywordSections": [
{
"compareValue": "includes",
"keywords": [
{
"value": "Higher Education"
}
]
}
],
"resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=1"
},
{
"id": 2,
"createdBy": {
"id": 1,
"userName": "[email protected]",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmith",
"owner": "Demo Organization"
},
"lastModified": "2023-08-29T14:54:44Z",
"webLink": "https://app.threatconnect.com/#/details/intel-requirements/2/overview",
"dateAdded": "2023-08-29T13:23:15Z",
"uniqueId": "IR-002",
"requirementText": "SHINRA",
"subtype": {
"name": "Priority Intelligence Requirement (PIR)",
"description": "Focus on threat actors' motives, TTPs, targeting, impact, or attribution in association with IRs"
},
"description": "Intel on Shinra Electric Corp",
"keywordSections": [
{
"compareValue": "includes",
"keywords": [
{
"value": "Electric"
},
{
"value": "Electric Infrastructure"
},
{
"value": "Grid Infrastructure"
},
{
"value": "Electric Grid"
}
]
}
],
"resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=2"
},
{...}
],
"status": "Success"
}
Retrieve a Specific Intelligence Requirement
Send a request in the following format to retrieve data for a specific IR. Note that {intelRequirementId} represents the value of the id field for an IR, not the value of the uniqueId field.
Example Request
GET /v3/intelRequirements/{intelRequirementId}
For example, the following request will retrieve data for the IR whose ID is 10:
Request
GET /v3/intelRequirements/10
Response
{
"data": {
"id": 10,
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization"
},
"lastModified": "2023-09-18T14:06:26Z",
"webLink": "https://app.threatconnect.com/#/details/intel-requirements/10/overview",
"dateAdded": "2023-09-18T14:06:24Z",
"uniqueId": "IR-010",
"requirementText": "Threats to Medical Device Companies",
"subtype": {
"name": "Intelligence Requirement (IR)",
"description": "Threats of overall concern to the organization (e.g., cyber, fraud, geopolitical/physical threats)"
},
"category": {
"name": "CISO Priorities",
"description": "IRs prioritized for the CISO"
},
"description": "This IR is used to track threats to medical device companies.",
"keywordSections": [
{
"compareValue": "includes",
"keywords": [
{
"value": "medical device companies"
},
{
"value": "healthcare"
},
{
"value": "mangled spider"
},
{
"value": "threats to medical"
}
]
},
{
"compareValue": "excludes",
"keywords": [
{
"value": "mrap"
}
]
}
],
"resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=10"
},
"status": "Success"
}
Update Intelligence Requirements
Send a request in the following format to update a specific IR. Note that {intelRequirementId} represents the value of the id field for an IR, not the value of the uniqueId field.
Example Request
PUT /v3/intelRequirements/{intelRequirementId}
Content-Type: application/json
{
"<fieldName>": <fieldValue>
}
For example, the following request will update the keywords used in the keyword query for the IR whose ID is 10 and associate the IR to the Group whose ID is 15:
Warning
When updating the keywords used in an IR’s keyword query, the keywords specified within the keywordSections field will replace all existing keywords used in the query.
Hint
To include the associatedGroups field in the response body, append ?fields=associatedGroups to the end of the request URI.
Request
PUT /v3/intelRequirements/10
Content-Type: application/json
{
"associatedGroups": {
"data": [
{
"id": 15
}
]
},
"keywordSections": [
{
"compareValue": "includes",
"keywords": [
{
"value": "medical device companies"
},
{
"value": "healthcare"
},
{
"value": "mangled spider"
},
{
"value": "threats to medical"
},
{
"value": "medical device"
}
],
"sectionNumber": 0
},
{
"compareValue": "excludes",
"keywords": [
{
"value": "mrap"
}
],
"sectionNumber": 0
}
]
}
Response
{
"data": {
"id": 10,
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"owner": "Demo Organization"
},
"lastModified": "2023-09-18T14:24:06Z",
"webLink": "https://app.threatconnect.com/#/details/intel-requirements/10/overview",
"dateAdded": "2023-09-18T14:06:24Z",
"uniqueId": "IR-010",
"requirementText": "Threats to Medical Device Companies",
"subtype": {
"name": "Intelligence Requirement (IR)",
"description": "Threats of overall concern to the organization (e.g., cyber, fraud, geopolitical/physical threats)"
},
"category": {
"name": "CISO Priorities",
"description": "IRs prioritized for the CISO"
},
"description": "This IR is used to track threats to medical device companies.",
"keywordSections": [
{
"compareValue": "includes",
"keywords": [
{
"value": "medical device companies"
},
{
"value": "healthcare"
},
{
"value": "mangled spider"
},
{
"value": "threats to medical"
},
{
"value": "medical device"
}
]
},
{
"compareValue": "excludes",
"keywords": [
{
"value": "mrap"
}
]
}
],
"resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=10"
},
"message": "Updated",
"status": "Success"
}
Delete Intelligence Requirements
Send a request in the following format to delete an IR. Note that {intelRequirementId} represents the value of the id field for an IR, not the value of the uniqueId field.
Example Request
DELETE /v3/intelRequirements/{intelRequirementId}
For example, the following request will delete the IR whose ID is 10:
Request
DELETE /v3/intelRequirements/10
Response
{
"message": "Deleted",
"status": "Success"
}
Associations
For instructions on creating and managing associations for IRs, see Create and Manage Associations.