Try the new beta v2 API! Learn more in our v2 Documentation

Introduction

Welcome to the Threat Stack API.

This API is based on REST principles and designed to have predictable, resource-oriented URL and Response Codes.

API Endpoint: https://app.threatstack.com/api/v1

/api/v1/agents          - Agents in current Organization
/api/v1/alerts          - Alerts
/api/v1/policies        - Policies
/api/v1/organizations   - Organizations
/api/v1/logs            - Audit Logs

Query Example

Here you can see an example of a query you can make against the Threat Stack REST API.
The purpose of the query is to retrieve all the alerts (in the context of __ORG_ID__)that happened between 2015-04-01 20:58:54 to 2015-04-01 20:59:00 showing only the fields id, title and created_at of every alert.


curl https://app.threatstack.com/api/v1/alerts -G  \
    -H 'Authorization: __API_KEY__'                \
    -H 'Organization: __ORG_ID__'                  \
    -d fields=id,title,created_at                  \
    --data-urlencode start="2015-04-01 20:58:54"   \
    --data-urlencode end="2015-04-01 20:59:00"

Partial Response

Specific fields can be retrieved using the partial response feature supported by the query parameter fields. This allows to retrieve only the data you need specifying the resource attributes as comma separated values fields=foo,bar.

# fields default: all

curl "https://app.threatstack.com/api/v1/alerts" -G \
  -H 'Authorization: __API_KEY__' \
  -d fields=title,type,severity

Pagination

Some resources support pagination through the use of the page and count parameters.
page starts from 0 and count should be greater or equal to 1. You can use limit as an alias for count too. By default count has a value of 50.

Get 100 entries from the offset 40


# default page: 0
# default count: 50

curl "https://app.threatstack.com/api/v1/alerts" -G \
  -H 'Authorization: __API_KEY__' \
  -d page="3" \
  -d count="100"

Time Ranges

You can specify the time slices by providing either timestamps or ISO8601 dates. The parameters to be modified are start and end. They default to a 24h interval.

Query the raw events from May 28 to June 4, 2014.

curl "https://app.threatstack.com/api/v1/logs" -G \
  -H 'Authorization: __API_KEY__' \
  -d start="2014-05-28" \
  -d end="2014-06-04"

Organization Context

By default, every resource query is done in the context of your default organization. Whenever you want to access resources from another organization you belong to, you can provide the query parameter organization=__ORG_ID__ with the organization id as value, or through an HTTP header Organization: __ORG_ID__.

curl "https://app.threatstack.com/api/v1/agents" -G \
  -H 'Authorization: __API_KEY__' \
  -H 'Organization: __ORG_ID__'

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://app.threatstack.com/api/v1/agents" \
  -H "Authorization: __API_KEY__"

Make sure to replace __API_KEY__ with your API key.

To authenticate to the Threat Stack API you just need to provide an API key either via the Authorization header (recommended) or as a query parameter in the URL. All communication should be send through SSL.

Authorization: __API_KEY__

or

/alerts?apiKey=__API_KEY__

Agents

Get All Agents

curl "https://app.threatstack.com/api/v1/agents" \
  -H "Authorization: __API_KEY__"

The above command returns JSON structured like this:

[
  {
    "activated_at": "2014-01-31T14:36:24.359Z",
    "pause": false,
    "online": false,
    "enabled": true,
    "updated_at": "2014-01-31T01:32:54.000Z",
    "last_reported_at": "2014-02-03T22:39:28.912Z",
    "created_at": "2014-01-31T01:32:54.000Z",
    "ip_address": "189.173.23.133",
    "version": "1.0.8",
    "status": "active",
    "name": "precise64",
    "description": "",
    "hostname": "webserver-1",
    "agent_id": "524c4a59a086e11959000009-6cc8d9b0-8a17-11e3-a2e3-ffced68b988625dda8300db4f719",
    "id": "52eafd46e5777f3a26000008",
    "policy_id": "524c4b9aa086e1195900000d",
    "organization_id": "524c4a59a086e11959000002"
  }
]

List all agents assigned to your active organization.

HTTP Request

GET https:/app.threatstack.com/api/v1/agents

Query Parameters

Parameter Default Description
organization Owner’s Setting the id of an organization you belong allows retrieve data in that context
page 0 Set the page to retrieve related to the count
count 20 Set the limit/total of entries to receive per page
start A week ago Set the start of the date range
end Today Set the end of the date range

Get Agent by id

Get details of an specific agent resource. The id to use is id, not agent_id.

curl "https://app.threatstack.com/api/v1/agents/{AGENT_ID}" \
  -H "Authorization: __API_KEY__"

The above command returns JSON structured like this:

{
  "activated_at": "2014-01-31T14:36:24.359Z",
  "pause": false,
  "online": false,
  "enabled": true,
  "updated_at": "2014-01-31T01:32:54.000Z",
  "last_reported_at": "2014-02-03T22:39:28.912Z",
  "created_at": "2014-01-31T01:32:54.000Z",
  "ip_address": "189.173.23.133",
  "version": "1.0.8",
  "status": "active",
  "name": "precise64",
  "description": "",
  "hostname": "webserver-1",
  "agent_id": "524c4a59a086e11959000009-6cc8d9b0-8a17-11e3-a2e3-ffced68b988625dda8300db4f719",
  "id": "52eafd46e5777f3a26000008",
  "policy_id": "524c4b9aa086e1195900000d",
  "organization_id": "524c4a59a086e11959000002"
}

HTTP Request

GET https://app.threatstack.com/api/v1/agents/{AGENT_ID}

URL Parameters

Parameter Description
fields Comma separated values of the attributes to be exclusively render (fields=title,severity)

Alerts

Get All Alerts

This endpoint has been decommissioned and is available on API V2. Please visit https://apidocs.threatstack.com/ for V2 documentation and implementation guides.

Get Alert by id

This endpoint has been decommissioned and is available on API V2. Please visit https://apidocs.threatstack.com/ for V2 documentation and implementation guides.

Get All Policies

curl "https://app.threatstack.com/api/v1/policies" \
  -H "Authorization: __API_KEY__"

The above command returns JSON structured like this:

[
  {
      "file_integrity_rules": [],
      "updated_at": "2013-10-25T17:42:42.446Z",
      "created_at": "2013-10-02T16:36:42.000Z",
      "read_only": true,
      "firewall_enabled": true,
      "enabled": true,
      "description": "This is the default policy",
      "name": "Default Policy",
      "id": "524c4b9aa086e1195900000d",
      "organization_id": "524c4a59a086e11959000009",
      "alert_policy_id": "524c4b9aa086e1195900000c",
      "agent_count": 1,
      "firewall_rule_count": 3,
      "alert_rule_count": 2
  }
]

Policies object manage the alerts that will be triggered when certain events matches.
A default policy is applied to each agent on creation and custom ones can be created or assigned via the User Interface. Note that we’ve introduced the term ruleset to supersede policies – the API will be updated shortly, but any existing references to policies will still work as expected.

HTTP Request

GET https://app.threatstack.com/api/v1/policies

Query Parameters

Parameter Default Description
organization Owner’s Setting the id of an organization you belong allows retrieve data in that context
page 0 Set the page to retrieve related to the count
count 20 Set the limit/total of entries to receive per page

Get Policy by id

curl "https://app.threatstack.com/api/v1/policies/{POLICY_ID}" \
  -H "Authorization: __API_KEY__"

The above command returns JSON structured like this:

{
    "file_integrity_rules": [],
    "updated_at": "2013-10-25T17:42:42.446Z",
    "created_at": "2013-10-02T16:36:42.000Z",
    "read_only": true,
    "firewall_enabled": true,
    "enabled": true,
    "description": "This is the default policy",
    "name": "Default Policy",
    "id": "524c4b9aa086e1195900000d",
    "organization_id": "524c4a59a086e11959000009",
    "alert_policy_id": "524c4b9aa086e1195900000c",
    "agent_count": 1,
    "firewall_rule_count": 3,
    "alert_rule_count": 2
}

To retrieve details of a single policy object, just append the id as a route parameter /policies/{POLICY_ID}.

HTTP Request

GET https://app.threatstack.com/api/v1/policies/{POLICY_ID}

URL Parameters

Parameter Description
fields Comma separated values of the attributes to be exclusively render (fields=name,enabled)

Organizations

Get All Organizations

curl "https://app.threatstack.com/api/v1/organizations" \
  -H "Authorization: __API_KEY__"

The above command returns JSON structured like this:

[
    {
        "id": "acbd18db4cc2f85cedef654fccc4a4d8",
        "name": "Foo's Organization",
        "role": "user"
    },
    {
        "id": "37b51d194a7513e45b56f6524f2d51f2",
        "name": "Bar's Organization",
        "role": "owner"
    }
]

This resource retrieve all organizations you own or are part of.

HTTP Request

GET https://app.threatstack.com/api/v1/organizations

Get Users in an organization

curl "https://app.threatstack.com/api/v1/organizations" \
  -H "Authorization: __API_KEY__"

The above command returns JSON structured like this:

[
    {
        "display_name": "John Doe",
        "email": "[email protected]",
        "id": "1010101010ababababab2020",
        "name": {
            "first": "Eduardo",
            "last": "Urias"
        },
        "organization_id": "37b51d194a7513e45b56f6524f2d51f2",
        "role": "owner",
        "updated_at": "2013-10-02T16:31:21.000Z"
    },
    {
        "display_name": "Charles Xavier",
        "email": "[email protected]",
        "id": "1010101010ababababab2021",
        "name": {
            "first": "Charles",
            "last": "Xavier"
        },
        "organization_id": "acbd18db4cc2f85cedef654fccc4a4d8",
        "role": "user",
        "updated_at": "2013-09-16T21:24:06.000Z"
    }
]

This resource retrieves all users that are part of your default or active (if you use the organization parameter). To change the context just add organization={ORG_ID} to do requests on that organization context.

HTTP Request

curl "https://app.threatstack.com/api/v1/organizations/{ORG_ID}/users"
  -H "Authorization: __API_KEY__"

URL Parameters

Parameter Description
fields Comma separated values of the attributes to be exclusively rendered (fields=display_name,role)

Audit Logs

Get All Audit Logs

curl "https://app.threatstack.com/api/v1/logs" \
  -H "Authorization: __API_KEY__"

The above command returns JSON structured like this:

[
  {
    "timestamp": 1398277257000,
    "user": "John Doe",
    "email": "[email protected]",
    "type": "queue",
    "action": "add",
    "description": "Event of type \"audit\" added to Queue",
    "context": [
        {
          "id": "20c2bac3-86c2-88c3-2f1c-12c2b5c3b153",
          "type": "audit",
          "agent": {
            "name": "precise64",
            "policy_id": "524c4b9aa086e1195900000d",
            "id": "52fd46e3277f3a26000008"
          },
          "name": "/bin/nc.openbsd"
        }
    ],
    "source": "queue:add",
    "user_id": "524c4a59a086e11959000008",
    "organization_id": "524c4a59a086e11959000009"
  }
]

HTTP Request

GET https://app.threatstack.com/api/v1/logs

Query Parameters

Parameter Default Description
organization Owner’s Setting the id of an organization you belong allows retrieve data in that context
page 0 Set the page to retrieve related to the count
count 20 Set the limit/total of entries to receive per page
start A week ago Set the start of the date range
end Today Set the end of the date range

Using the q parameter you can do arbitrary search on logs that match that specific string pattern. For example, you can do search of q=queue, [email protected], etc.

curl "https://app.threatstack.com/api/v1/logs?q={STRING_PATTERN}" \
  -H "Authorization: __API_KEY__"

The above command returns JSON structured like this:

[
  {
    "timestamp": 1398277257000,
    "user": "John Doe",
    "email": "[email protected]",
    "type": "queue",
    "action": "add",
    "description": "Event of type \"audit\" added to Queue",
    "context": [  ]
    ...
  }
]

HTTP Request

GET https://app.threatstack.com/api/v1/logs?q=queue

URL Parameters

Parameter Description
fields Comma separated values of the attributes to be exclusively render (fields=user,type,action)

Errors

Cloud Sight API uses the following error codes:

Error Code Meaning
400 Bad Request – There might be something wrong with your request
401 Unauthorized – Your API key sent is invalid
404 Not Found – The specified resource could not be found
405 Method Not Allowed – You tried to access a resource with an invalid method
410 Gone – The resource requested has been removed from our servers
429 Too Many Requests – The user has sent too many requests in a fixed amount of time.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.