Alert & Incident API

Introduction

The DigitalStakeout Scout Alert & Incident API provides a way to consume alerts and incidents from DigitalStakeout Scout through a REST API. This document serves as a guide for developers to effectively utilize the API.

API Documentation

Detailed developer documentation is available in the DigitalStakeout Portal.

API Keys

Generation and Retrieval: API keys are necessary for making requests. You can generate a new key or retrieve an existing one under the Integrations tab in 'My Account'.
Saving the Key: After generating a Token, ensure to click 'SAVE'.

API Access

User-Based Access: API keys are "PINNED" to a user, meaning they have access to the same data the user can access in the Portal.

Rate Limits

Limits: API requests are subject to rate limits within a 15-minute period, per API key and endpoint.
Exceeding Limits: If the limit is exceeded, an HTTP 429 error (Too Many Requests) will be returned. It is advised not to query the API more than once per second. A typical polling rate is once every 60 seconds.

Pseudo Exporting

Copyright Restrictions: The API is not intended as a mechanism for exporting all results from your DigitalStakeout Scout instance.
Rate Limiting on Tagging: If your Alert volume is greater than 5% of your aggregate collection volume, data tagging for API consumption will be rate limited.

Error Codes

DigitalStakeout's API utilizes the following error codes:

400: Bad Request

Meaning: Your request is improperly formatted or missing required parameters.

401: Unauthorized

Meaning: Your API key is incorrect or missing.

404: Not Found

Meaning: The specified URL or resource could not be found.

405: Method Not Allowed

Meaning: You tried to access the API with an invalid method (e.g., using GET instead of POST).

406: Not Acceptable

Meaning: The requested format is not supported; the API supports JSON format only.

429: Too Many Requests

Meaning: You are sending too many requests in a short period. Please slow down to adhere to the rate limits.

500: Internal Server Error

Meaning: There is a problem with the DigitalStakeout Scout server. Try again later.

503: Service Unavailable

Meaning: The DigitalStakeout Scout service is temporarily offline for maintenance. Please try again later.

Conclusion

The Scout Alert & Incident API is a powerful tool for integrating DigitalStakeout Scout capabilities into your applications. Proper understanding and adherence to guidelines regarding API keys, access, rate limits, and data exporting are crucial for effective and compliant use of this API.