Download OpenAPI specification:Download
NOTE
Threat Stack is transitioning to a new brand: App Infrastructure Protection (AIP). Until this process completes in December 2022, documentation will use "Threat Stack" and "AIP" interchangeably. For more information, see Introduction to AIP.
The AIP Rest API provides a way to connect to a AIP organization and extract key information around security concerns in your environment.
View the API Changelog here.
Hawk is a protocol that implements hash message authentication code (HMAC) signing based on the API key provided. Hawk was designed to allow two parties to verify the sender of a message by a signed header in the HTTP request. If there is a body to the request, such as sending data via the API, you can verify the integrity of the body as well.
To get started with Hawk:
Before you can use the AIP API v2, you must authenticate using the three environment variables:
You can find the API key and the IDs on the Application Keys tab within the Settings page.
AIP has implemented supported HAWK starter clients for Java, NodeJs, and Python for you to use!
You can clone them from the AIP GitHub repository.
With your credentials from step 1, you can make a test request to our API that confirms your successful Hawk configuration.
After you successfully authenticate, you can start using the available API endpoints!
For more details on our Hawk implementations, review one of the following frameworks:
Some of the API endpoints return data that spans across a wide time range. To help refine the responses, you can specify the time ranges by modifying the from and until parameters. All date and time parameters follow ISO-8601 standards.
The API uses UTC timestamps:
| Date, Time, Date and Time | Format | Example |
|---|---|---|
| Date | yyyy-mm-dd | 2022-09-05 |
| Combined date and time (hours) | yyyy-mm-ddThh | 2022-09-05T15 |
| Combined date and time (minutes) | yyyy-mm-ddThh:mm | 2022-09-05T15:53 |
| Combined date and time (seconds) | yyyy-mm-ddThh:mm:ss | 2022-09-05T15:53:00 |
To return resources created after a specific date, use the from parameter:
https://api.threatstack.com/v2/alerts?from=2017-08-01
To return resources created before a specific date, use the until parameter:
https://api.threatstack.com/v2/alerts?until=2017-02-01
To return resources created within a window of time bounded by specific dates, use the from and until parameters together:
https://api.threatstack.com/v2/alerts?from=2017-01-01&until=2017-04-01
The Alert, Agent, and Vulnerabilities endpoints paginate and return up to 100 records per query. Use the token value from the response to query for the next page. When the token value is null in the response, you have reached the end of the results list.
The token value is located at the bottom of the response body:
],
"token": "NTk4OGM5MWRmNDUyYWUzZjIzYTk2NWQzLDIwMTctMDgtMDdUMjA6MTA6=="
}
Use this token as an addendum to the query parameter to access the next page:
https://api.threatstack.com/v2/agents?token=NTk4OGM5MWRmNDUyYWUzZjIzYTk2NWQzLDIwMTctMDgtMDdUMjA6MTA6==
NOTE
Each page of results must display before fetching the next page of results.
The rate limit for an organization is 200 requests per minute. Specifically, this describes the organization-Id rate limit. This results in an HTTP 429 error message. You can send the next request after 1 minute.
The AIP API includes HTTP headers on every API response. These headers help you determine how much of your organization's rate limit budget has been used.
If the number of requests from an IP address exceeds 1,000 requests per minute, that results in an HTTP 429 error message and a 15 minute lock out for that IP address.