---
title: "REST API Guide"
slug: "rest-api-v2-guide"
updated: 2026-04-28T16:58:11Z
published: 2026-04-28T16:58:11Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catchpoint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](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](https://io.catchpoint.com/api/v2/commandcontrol)

Visit [Catchpoint REST API Swagger UI](https://io.catchpoint.com/api/swagger/index.html) 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](https://io.catchpoint.com/api/swagger/index.html)**. ![rest-api-v2-guide-image-kwovfg5n](https://cdn.document360.io/cb4af8f9-6751-4fd2-b39c-07aae832badb/Images/Documentation/rest-api-v2-guide-image-kwovfg5n.jpg)
2. Click on **Authorize** ![rest-api-v2-guide-image-3y383lbz](https://cdn.document360.io/cb4af8f9-6751-4fd2-b39c-07aae832badb/Images/Documentation/rest-api-v2-guide-image-3y383lbz.png)
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.  

![Picture1.png](https://cdn.document360.io/cb4af8f9-6751-4fd2-b39c-07aae832badb/Images/Documentation/Picture1.png)
  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**.  

![Picture2.png](https://cdn.document360.io/cb4af8f9-6751-4fd2-b39c-07aae832badb/Images/Documentation/Picture2.png)
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.

## Rotational API Key Support

Rotational API key support enables managed lifecycle control for REST API credentials used with Catchpoint’s REST API. This functionality allows API consumers to create, expire, and rotate API keys without interrupting existing integrations.

### API Key Expiration

API key expiration is configured as an account-level setting. The expiration timeframe defined at the account level applies to all REST API keys created for the account. Once enabled, all newly generated API keys automatically inherit the configured expiration timeframe. Existing API keys are not retroactively updated.

#### Configure API Key Expiration

To set the API key expiration timeframe:

1. Navigate to Settings → Info
2. Locate the API key expiration setting
3. Set the desired expiration timeframe (in number of days)
4. Save the setting

#### Behavior Notes

- Supported expiration values range from 30 days to 2 years.
- The configured timeframe applies to all newly created API keys for the account.
- When an API key reaches its expiration date, it is automatically invalidated and can no longer be used to authenticate API requests.
- Up to two API keys can be active at the same time for an API consumer, allowing a new key to be introduced before an existing key expires.

#### Multiple Active API Keys per Consumer

Each API consumer supports up to two API keys active at the same time. This supports staged key rotation by allowing:

- A new API key to be created while an existing key remains active
- Application integrations to transition to the new key before the original key expires or is deleted

This approach allows API key rotation to occur without downtime or coordination windows.

## 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. ![rest-api-v2-guide-image-ycw1u6oi](https://cdn.document360.io/cb4af8f9-6751-4fd2-b39c-07aae832badb/Images/Documentation/rest-api-v2-guide-image-ycw1u6oi.png)

**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. ![rest-api-v2-guide-image-osj2m3st](https://cdn.document360.io/cb4af8f9-6751-4fd2-b39c-07aae832badb/Images/Documentation/rest-api-v2-guide-image-osj2m3st.png)

**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. ![rest-api-v2-guide-image-rlh02upu](https://cdn.document360.io/cb4af8f9-6751-4fd2-b39c-07aae832badb/Images/Documentation/rest-api-v2-guide-image-rlh02upu.png)

## 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.

*Note that the daily REST API call count is reset at 00:00:00 UTC.*

## 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.