Observable Tags in Bulk

ThreatStream enables you to add and remove observable tags in bulk. You can use the information in this section to manage tags associated with sets of observables through the API.

Adding Observable Tags in Bulk

Request

/api/v2/intelligence/bulk_tagging/

Important: /api/v1/intelligence/ requests are now deprecated. Anomali recommends using /api/v2/intelligence/ for all requests.

HTTP Method: POST

Attributes

Attribute Description
ids Unique IDs of the observables to which you are adding tags.
tags

Tags that will be applied to the specified observables.

Tags must be specified as follows:

tags: [{"name": "my_tag","tlp": "red"},{"name": "my_tag2","tlp": "clear"},{"name": "my_tag3"}]

Tag Attributes:

  • name—name of the tag that you want to add.

  • tlp—the visibility setting for the tag. Possible values: red, amber, amber+strict, green, clear.

  • red—private, or visible to your organization only.

  • white—public, or visible to all ThreatStream users with access to the data. Default: white.

    Note: Adding public tags may be restricted by your Organization Administrator.

    In the example above, my_tag is private and my_tag2 and my_tag3 are public.

By default, you can manage up to 250 tags in bulk. If you need to manage up more than 250 tags in bulk, see Managing up to 10,000 Tags in Bulk for more information.

Example

To add a private tag to a set of observables whose IDs are 61, 52, 8, 50, 34:

Copy 
curl -X POST -d'{"tags": [{"name": "test", "tlp": "red"}], "ids": [61, 52, 8, 50, 34]}' 'https://api.threatstream.com/api/v2/intelligence/bulk_tagging/' -H 'Content-Type:application/json' -H 'Authorization: apikey <username>:<api_key>'
        

Removing Observable Tags in Bulk

Request

/api/v2/intelligence/bulk_tagging/

Important: /api/v1/intelligence/ requests are now deprecated. Anomali recommends using /api/v2/intelligence/ for all requests.

HTTP Method: POST

Attributes

Attribute Description
ids Unique IDs of the observables from which you are removing tags.
tags

Tags that will be removed from the specified observables.

Tags must be specified as follows:

tags: [{"name": "my_tag","tlp": "red"},{"name": "my_tag2","tlp": "clear"},{"name": "my_tag3"}]

Tag Attributes:

  • name—name of the tag that you want to add.

  • tlp—the visibility setting for the tag. Possible values: red, amber, amber+strict, green, clear.

  • red—private, or visible to your organization only.

  • white—public, or visible to all ThreatStream users with access to the data. Default: white.

    Note: Adding public tags may be restricted by your Organization Administrator.

    In the example above, my_tag is private and my_tag2 and my_tag3 are public.

By default, you can manage up to 250 tags in bulk. If you need to manage up more than 250 tags in bulk, see Managing up to 10,000 Tags in Bulk for more information.
remove_tags

Tags must be specified as follows:

remove_tags: [{“name”:"my_tag"},{"name":"my_tag2"},{"name":"my_tag3"}]

Example

To remove two tags from a set of observables whose IDs are 776 and 349:

Copy 
curl -X POST -d'{"remove_tags": [{"name": ["test", "tagB"]}],"ids": [776, 349]}' 'https://api.threatstream.com/api/v2/intelligence/bulk_tagging/' -H 'Authorization: apikey <username>:<api_key>' -H 'Content-Type:application/json'

Managing up to 10,000 Tags in Bulk

By default, you can add and delete up to 250 tags in bulk. If you need to manage up to 10,000 tags, you can do so by specifying a dataset to which tags will be applied or from which tags will be removed.

When you add or remove up to 10,000 tags in bulk, an asynchronous job is created. Once the job is completed successfully, you must get the results of the job to finish the procedure. You can create one job at a time. Otherwise, making this API call will result in an error.

Requests

  1. /api/v2/intelligence/bulk_tagging/?async_result=true—POST request to create an asynchronous job.

    This request requires that you specify payload in JSON format. Payload consists of the query object that creates a dataset, and the list of tags to be added and/or removed from observables in the dataset.

  2. /api/v1/generic_async_result/<id>/—GET request to check the status of the job. The job must have the "done" status

Payload Parameters

Parameter Type Description
query object

Payload object that specifies the dataset and has the following parameters: q, limit, and order_by. The parameters are described in this table below.

For example, query: {"q": "(status = active) and (created_ts >= 2022-10-01T23:00:00)", "limit": 10000, order_by: "-created_ts"}
q string

Parameter in the query object that filters out the observables to which tags will be added or from which the tags will be removed.

For example, q: "(status = active) and (created_ts >= 2022-10-01T23:00:00)" will create a dataset of active observables created at the specified time.
limit integer

Parameter in the query object, maximum number of observables to which tags will be added or from which tags will be removed.

For example, limit: 10000

You can manage up to 10,000 observables in bulk.
order_by string

Parameter in the query object, an observable attribute by which the observables in the dataset will be ordered.

For example, order_by: "-created_ts"
tags array of strings

Tags that will be added to the selected observables.

For example, tags: [{"name":"my_tag", tlp: "red"}]
remove_tags array of strings

Tags that will be removed from the selected observables.

For example, remove_tags: [{"name":"my_tag2", tlp: "red"}]

Example

  1. To add the private my_tag tag and remove the private my_tag2 tag from the active observables created on a specific date and ordered by date of creation:

    Copy 
    curl -X POST 'https://api.threatstream.com/api/v2/intelligence/bulk_tagging/?async_result=true' -H 'Content-Type:application/json' -H 'Authorization: apikey <username>:<api_key>'-d '{"query":{"q": "(status = active) and (created_ts >= 2022-10-01T23:00:00)", "limit": 10000, "order_by": "-created_ts"}, "remove_tags": [{"name":"my_tag2", "tlp": "red"}], "tags": [{"name": "my_tag", "tlp": "red"}]}'

    Results returned are similar to the following:

    created_ts: "2022-11-01T21:10:56.008462"
id: <id>
modified_ts: "2022-11-01T21:10:56.008475"
path: "/api/v2/intelligence/bulk_tagging/"
resource_uri: "/api/vl/generic_async_result/<id>/"
response_status: null
status: "inprogress"

    where <id> is the unique ID of the job. You will use this value to check the status of the job and return the results after its completion.

  2. To check the status of the job using the command listed for resource_uri:

    Copy 
    curl 'https://api.threatstream.com/api/v1/generic_async_result/<id>/' -H 'Content Type:application/json' -H 'Authorization: apikey <username>:<api_key>'

    where <id> is the unique ID of the job.

    Results returned are similar to the following:

    created_ts: "2022-11-01T21:10:56.008462"
id: <id>
modified_ts: "2022-11-01T21:10:56.008475"
path: "/api/v2/intelligence/bulk_tagging/"
resource_uri: "/api/vl/generic_async_result/<id>/"
response_status: null
status: "inprogress"

    Repeat this call until you see the following values:

    response_status: 200
status: "done"

    This indicates that the job is complete and ready to return the results.

  3. Return the results of the completed job:

    Copy 
    curl 'https://api.threatstream.com/api/v1/generic_async_result/<id>/get_result/' -H 'Authorization: apikey <username>:<api_key>'