Workgroup API Resources

You can complete the following workgroup management related tasks via the API:

View a complete list of workgroups in your organization. See Workgroup API.
Restrict intelligence visibility to specific workgroups in bulk. See Bulk Workgroups API.
Lift workgroup visibility restrictions from individual observables. See Removing Workgroup Restrictions.
Restrict visibility of observables during imports to specific workgroups. See Import API.

Workgroup API

Use the Workgroup API to return a complete list of organization workgroups and related information, including workgroup IDs.

Tip: Workgroup IDs are needed to complete other workgroup management tasks via the API, such as associating intelligence with workgroups in bulk.

Request

/api/v1/workgroup/

HTTP Method: GET

Response

Format: JSON

Number of rows returned (by default): 20

Attributes: See table below

Attributes

Attribute	Description
created_ts	Timestamp when the workgroup was created.
id	ID associated with the workgroup.
members	Number of users that belong to the workgroup.
name	Name of the workgroup.
owner_org	Your organization ID, name, and Resource URI.

Examples

Request:

Copy

curl 'https://api.threatstream.com/api/v1/workgroup/' -H 'Authorization: apikey <username>:<api_key>'

Response:

Copy

{
  "meta": {
    "limit": 20,
    "next": "/api/v1/workgroup/?limit=20&offset=20",
    "offset": 0,
    "previous": null,
    "total_count": 51
  },
  "objects": [
    {
      "avatar_s3_url": null,
      "created_ts": "2016-09-02T20:31:11.211401",
      "id": 2,
      "members": 8,
      "modified_ts": "2016-09-02T20:31:11.211401",
      "name": "Threat Intel Team",
      "owner_org": {
        "id": "2",
        "name": "Anomali1",
        "resource_uri": "/api/v1/userorganization/2/"
      },
      "resource_uri": "/api/v1/workgroup/2/"
    }
  ]
}

In this example, the limit attribute was not specified and, therefore, the default limit of 20 was enforced. To return the complete results, use the next field of the returned metadata to make iterative API calls until all results have been returned. Repeat this process iteratively until next = null.

Bulk Workgroups API

Use the Bulk Workgroups API to associate observables with workgroups in your organization, thus restricting the visibility of the intelligence to the workgroups you specify.

Request

/api/v2/intelligence/bulk_workgroups/

HTTP Method: POST

Attributes: See the table below

Request Attributes

Attribute	Type	Description
ids	string	A comma-separated list of observable IDs corresponding to observables whose visibility you want to restrict to specified workgroups.
workgroups	string	A comma-separated list of workgroup IDs corresponding to the workgroups to which you want to give exclusive accesses to specified observables.

Response

The response contains the following attributes.

Attribute	Description
workgroups	IDs of the workgroups specified in the request.
success	Whether the submission was successful or not. Possible values: `true`, `false`

Examples

To restrict the visibility of a set of observables to specific workgroups:

Copy

curl -XPOST 'https://api.threatstream.com/api/v2/intelligence/bulk_workgroups/' -d '{"ids":[observable_id_1,observable_id_2],"workgroups":[workgroup_id_1,workgroup_id_2]}' -H 'Authorization: apikey <username>:<api_key>' -H 'Content-Type: application/json'

Removing Workgroup Restrictions

Use the Intelligence API to remove workgroup restrictions from individual observables, thus expanding visibility to your entire organization. This involves specifying a blank workgroups attribute in the request.

Note: Workgroup restrictions cannot be lifted from observables in bulk.

Request

/api/v1/intelligence/<observable_id>

HTTP Method: PATCH

Example

To open visibility of a workgroup restricted observable to all users in your organization:

Copy

curl -v -XPATCH ‘https://api.threatstream.com/api/v2/intelligence/5873243/' -d ‘{“workgroups”:[]}’ -H ‘Content-Type: application/json’ -H 'Authorization: apikey <username>:<api_key>'

In the above request, the observable associated with the ID 5873243 is made visible to your organization users by specifying a blank workgroups attribute.

Import API

Use the Import (with approval) API to restrict the visibility of observables to specific workgroups during import.

Note: Refer Import (with approval) for complete Import API documentation.

Request

/api/v1/intelligence/import/

HTTP Method: POST

For the purposes of workgroup management, the Import (with approval) API contains the following additional attribute.

Attribute	Type	Description
workgroups	string	A comma-separated list of workgroup IDs corresponding to the workgroups to which you want to give exclusive accesses to imported observables.

Example

To import observables with workgroup visibility restrictions:

Copy

curl -X POST 'https://api.threatstream.com/api/v1/intelligence/import/'  -F confidence=30 -F severity=very-high -F classification=private -F workgroups=2,5 -F notes=notes -F expiration_ts= "2017-01-26T00:00:00" -F "datatext=<text_to_parse_and_import>" -H 'Authorization: apikey <username>:<api_key>'

In the above request, the visibility of imported observables is restricted to the workgroups associated with the workgroup IDs 2 and 5.