REST API Guide

Catchpoint’s REST API enables developers to create applications which interact directly with Catchpoint and its functionality. This provides a great opportunity to build or integrate with external tools as per your use case.

API consumers can easily request data by calling any specific API endpoint on the Catchpoint server. The server will then send the requested data.

To use the Catchpoint API, you will need the following:

• The API endpoint address: This starts with https://io.catchpoint.com followed by the specific path of the API endpoint for which you want the data.

For example, to get data about command and control, you would use https://io.catchpoint.com/api/v2/commandcontrol

Visit Catchpoint REST API Swagger UI to access the list of all the available API endpoints and their respective paths.

Authentication

Catchpoint’s REST API authenticates all requests using the API key. All requests must pass this key as a “bearer” token within the authorization header.

To authorize in the Swagger UI to consume all the available endpoints:

1. Navigate to the Catchpoint REST API Swagger UI.
   

2. Click on Authorize
   

3. Retrieve a REST API key from Catchpoint

   1. Log in to the Catchpoint Portal.
   2. Navigate to Integrations > REST API in the left navigation bar.
      
   3. Click Add Consumer under REST API.
   4. Provide a consumer Name and select a Contact. If no contact is present, add the contact information on the contact page.
   5. Click Add Consumer & Show Key.
      

4. Copy the key from the Catchpoint UI and paste it into the Value field in the Swagger UI

5. Click Authorize in Swagger UI.

6. Click the Close button to close the pop up.

7. Now scroll to any endpoint and click on Try it out to begin testing the API.

REST API Key Validity

REST API keys generated in the Catchpoint portal are valid for two years from the time of generation. If a key is regenerated from the UI then the two-year period will start over. A key can also be revoked.

Use a client level key to access client data. Use a division level key to access division data.

Response Format

The REST API returns all results in JSON format. All requests made using the API need to include an accept header with either "*/*", "application/json", "text/json", or "text/plain".

Error Response

Different errors are reported in the same response schema with some variation. Below are some examples:

Example Response 1:
A sample response for any validation error, returns status code 400. In this example a new test was being created with a test name that was already existing.

Example Response 2:
A sample response for post - payload data serialization error, returns status code 400. It will point out the line number and invalid value.

Example Response 3:
A sample response for post - payload required field validation, returns status code 400. This error occurs when required fields are missing in the JSON body.

Parameters

All parameters are case sensitive. In case of multiple parameters in a query, the “AND” operation will be performed. When no parameters are passed then the endpoint executes its default behavior. For example, to retrieve all A-1 instances running CentOS 7, the query string would be: os=CentOS%207&size=A-1.

Pagination

Endpoints that pull large amounts of data use pagination. These endpoints return the maximum number of supported objects based on the endpoint, and in cases where there are more details to pull, it will set the hasMore property in the response to true. This property will be set to true until it reaches the end of the page that does not have more objects to pull.

Date Format

The format for date query parameters such as start/end times is YYYY-MM-DDTHH:MI:SS. All timestamps need to be passed in UTC time zone.
YYYY - The four-digit year
MM - The month from 01 to 12
DD - The day of the month from 01 to 31 HH - The hour of day from 00 to 23
MI - The minute of the hour from 00 to 59
SS – The seconds of the minute from 00 to 59

Usage Limits

The per-second limit thresholds are set based on the requestor's IP address. Requests from different machines using the same key will have these limits applied separately. Other limits apply to analytic calls made by each consumer.

• 7 requests per second
• 20 requests per minute
• 500 requests per hour
• 2000 requests per day

How API limits are enforced

For example, if we have following limits on the account - 90 per minute, 3,000 per hour, 40,000 per day - and if the following consumers make REST API calls (analytic endpoints) within a minute:

• Consumer A makes 50 calls/min from Div A
• Consumer B makes 10 calls/min from Div B
• Consumer C makes 10 calls/min from Div C
• Consumer D makes 10 calls/min from Client Level
• Consumer E makes 10 calls/min from Division C

then:

Consumer F will not be able to make any calls because the 90 calls/min limit has been reached. Consumer F will receive error code 429.

This example shows how limits are applied across the account/divisions/consumers.

REST API Version Support

Catchpoint will support the current major version of the REST API and the prior major version of the REST API for a period of twelve months from when the current major version was announced as stable. If you attempt to access an unsupported version of the API, it will result in an error.