Graph API Version

ThreatDescriptor

A subjective opinion about a ThreatIndicator that was submitted by a ThreatExchangeMember.

Fields

Parameter	Description	Type
`id`	Unique identifier of the threat descriptor. Automatically assigned at create time, and non-editable.	`number`
`added_on`	The datetime this descriptor was first uploaded. Automatically computed; not directly editable.	`string`
`confidence`	A rating, from 0-100, on how confident the publisher is of the threat indicator's status. 0 is meant to be least confident, with 100 being most confident.	`number`
`description`	A short summary of the indicator and threat.	`string`
`expired_on`	Datetime the indicator is no longer considered a threat, as subjectively determined by the owner of the descriptor.	`number`
`first_active`	The datetime when this opinion first became valid, as subjectively determined by the owner of the descriptor.	`string`
`last_active`	The datetime when this opinion stopped being valid, as subjectively determined by the owner of the descriptor.	`string`
`indicator`	The ThreatIndicator described by the descriptor: for example, a URL or a hash string. Non-editable after the descriptor is created.	`ThreatIndicator`
`last_updated`	Datetime the threat descriptor was last updated. Automatically computed; not directly editable.	`string`
`my_reactions`	A list of reactions that you have added to this descriptor.	`ReactionType`
`owner`	The ThreatExchangeMember that submitted the descriptor. Non-editable.	`ThreatExchangeMember`
`precision`	The degree of accuracy of the descriptor.	`PrecisionType`
`privacy_type`	The level of privacy applied to the descriptor. Also known as "visibility".	`PrivacyType`
`raw_indicator`	A raw, unsanitized string of the indicator being described.	`string`
`reactions`	A list of reactions to reacting application.	`ReactionType`
`review_status`	Describes how the indicator was vetted.	`ReviewStatusType`
`severity`	Dangerousness of threat associated with the indicator.	`SeverityType`
`share_level`	A designation of how the indicator may be shared, based on the US-CERT's Traffic Light Protocol.	`ShareLevelType`
`source_uri`	A publicly accessible URL containing further context or details about the descriptor.	`string`
`status`	If the indicator is known to be malicious or not.	`StatusType`
`type`	The type of indicator.	`IndicatorType`

Connections

Parameter	Description	Type
`tags`	The tags applied to this descriptor.	`string`

For additional documentation on ThreatTags, see ThreatTag Object

Reading

Example query for a specific descriptor: 29552573304386008

curl \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v25.0/29552573304386008
  

Open In Graph API Explorer

Data returned:

{
  "added_on": "2025-05-20T13:49:06+0000",
  "confidence": 99,
  "description": "An example of a publicly visible Descriptor for the docs at https://developers.facebook.com/docs/threat-exchange/reference/apis/threat-descriptor",
  "id": "29552573304386008",
  "indicator": {
    "id": "2821805551224300",
    "indicator": "https://developers.facebook.com/docs/threat-exchange/reference/apis/threat-descriptor",
    "type": "URI"
  },
  "last_updated": "2025-05-20T13:49:06+0000",
  "owner": {
    "id": "316842935455502",
    "name": "Meta ThreatExchange"
  },
  "privacy_type": "VISIBLE",
  "raw_indicator": "https://developers.facebook.com/docs/threat-exchange/reference/apis/threat-descriptor",
  "review_status": "REVIEWED_MANUALLY",
  "severity": "INFO",
  "share_level": "WHITE",
  "status": "NON_MALICIOUS",
  "type": "URI"
}

Creating

We can send a POST request to /threat_descriptors. The example below will create a piece of data that shared only with other members in Example Program. Note to run this call, you must join Example Program.

curl -X POST https://graph.facebook.com/v24.0/threat_descriptors \
  -F "access_token=<ACCESS_TOKEN>" \
  -F "type=URI" \
  -F "indicator=https://developers.facebook.com/docs/threat-exchange/reference/apis/threat-descriptor" \
  -F "description=A malicious URL shared via the ThreatDescriptor API" \
  -F "privacy_type=HAS_PRIVACY_GROUP" \
  -F "share_level=GREEN" \
  -F "status=MALICIOUS" \
  -f "privacy_members=1012185296055235"
  

Open In Graph API Explorer

Data returned:

{
  "success": true,
  "id": "25702495966077851"
}

Updating

To make an update to an existing ThreatDescriptor, make a POST request to /{threat_descriptor_id}.

curl -X POST https://graph.facebook.com/v24.0/25702495966077851 \
  -F "access_token=<ACCESS_TOKEN>" \
  -F "description=Updated description via the ThreatDescriptor API"
  

Open In Graph API Explorer

Data returned:

{
  "success": true
}

Deleting

To remove an existing ThreatDescriptor, make a DELETE request to /{threat_descriptor_id}.

curl -X DELETE https://graph.facebook.com/v24.0/25702495966077851 \
  -F "access_token=<ACCESS_TOKEN>"
  

Open In Graph API Explorer

Data returned:

{
  "success": true
}