# REST API

## Overview

Panther offers a REST API to interact with certain parts of your Panther instance. Currently, you can interact with the following entities through the REST API:

* [Alerts](https://docs.panther.com/panther-developer-workflows/api/rest/alerts)
* [Alert Comments](https://docs.panther.com/panther-developer-workflows/api/rest/alert-comments)
* [Alert Context Tags](https://docs.panther.com/panther-developer-workflows/api/rest/alert-context-tags)
* [API Tokens](https://docs.panther.com/panther-developer-workflows/api/rest/api-tokens)
* [Correlation Rules](https://docs.panther.com/panther-developer-workflows/api/rest/correlation-rules)
* [Data Models](https://docs.panther.com/panther-developer-workflows/api/rest/data-models)
* [Globals](https://docs.panther.com/panther-developer-workflows/api/rest/globals)
* [Log sources](https://docs.panther.com/panther-developer-workflows/api/rest/log-sources)
* [Queries](https://docs.panther.com/panther-developer-workflows/api/rest/queries)
* [Roles](https://docs.panther.com/panther-developer-workflows/api/rest/roles)
* [Rules](https://docs.panther.com/panther-developer-workflows/api/rest/rules)
* [Scheduled rules](https://docs.panther.com/panther-developer-workflows/api/rest/scheduled-rules)
* [Simple/YAML rules](https://docs.panther.com/panther-developer-workflows/api/rest/simple-rules)
* [Policies](https://docs.panther.com/panther-developer-workflows/api/rest/policies)
* [Users](https://docs.panther.com/panther-developer-workflows/api/rest/users)

Additional operations are available in the [GraphQL API](https://docs.panther.com/panther-developer-workflows/api/graphql).

### Discover the Panther REST API schema

{% tabs %}
{% tab title="OpenAPI specification" %}
Discover the REST API schema by downloading the OpenAPI specification file:

{% file src="<https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-92ac408a8e96ab4254db2b221a79a4f051129333%2Fpanther_open_api_v3_spec.yaml?alt=media>" %}
{% endtab %}

{% tab title="API Playground " %}
You can discover the API schema by browsing the API Playground in your Panther Console. Learn more on [API Playground](https://docs.panther.com/panther-developer-workflows/api/api-playground).
{% endtab %}
{% endtabs %}

## How to use the Panther REST API

### Step 1: Identify your Panther REST API URL

To locate your REST API URL:

* In the upper-right corner of your Panther Console, click the gear icon, then **API Tokens**. At the top of the page, see the **API URL**.

  * If you are running a [SaaS](https://docs.panther.com/system-configuration/panther-deployment-types#saas) deployment of Panther, your REST URL will be the portion shown below:

  <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-f9b58befbc5316bcf67d46db823deb37d131c63d%2FScreenshot%202023-12-13%20at%2011.35.41%20AM.png?alt=media" alt="An &#x22;API Tokens&#x22; section shows a blurred-out API URL"><figcaption></figcaption></figure>

  * If you are running a [Cloud Connected](https://docs.panther.com/system-configuration/panther-deployment-types#cloud-connected) or [self-hosted](https://docs.panther.com/system-configuration/panther-deployment-types#self-hosted-legacy) deployment of Panther, the URL will be the portion shown below (inclusive of `/v1`):

  <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-7ee3d76233bab269b7a576612d0b748b05e36d4a%2FScreenshot%202023-12-13%20at%2011.53.34%20AM.png?alt=media" alt="An &#x22;API Tokens&#x22; section shows a blurred-out API URL"><figcaption></figcaption></figure>

{% hint style="warning" %}
Note that all REST URLs exclude `/public/graphql` from the end of the value.
{% endhint %}

### Step 2: Generate an API token

* See [these instructions on how to create an API token](https://docs.panther.com/panther-developer-workflows/api/..#how-to-create-a-panther-api-token). You can find required permissions for each REST API operation on each entity's page (nested under this one). See [Permission names in the Console and API](https://docs.panther.com/system-configuration/rbac#permission-names-in-the-console-and-api) for additional information.

### Step 3: Invoke the Panther REST API

In addition to testing with the [API Playground](https://docs.panther.com/panther-developer-workflows/api/api-playground) in the Console, you can invoke the REST API using Swagger, Postman, or this documentation:

{% tabs %}
{% tab title="Swagger" %}
**Using Swagger to access the REST API**

1. In a web browser, navigate to the [Swagger Editor](https://editor.swagger.io/).
2. In the code editor on the left-hand side, paste in the Panther REST OpenAPI specification file found above, in [Discover the Panther REST API schema](#discover-the-panther-rest-api-schema).
3. On the right-hand side, under **Server variables**, in **api\_host**, enter your Panther REST API URL without the protocol (i.e., excluding `https://`).\
   ![A "Server variables" section shows an api\_host](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-ad21510c92ca6e994a4020bf0c7fcc0cc27bbd75%2FScreenshot%202023-12-11%20at%204.21.46%20PM.png?alt=media)
4. Click **Authorize**.\
   ![An Authorize button](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-b06f008348e3e869375cc2752c3c7eef4d2b0a04%2FScreenshot%202023-12-11%20at%204.27.00%20PM.png?alt=media)
5. In the **Available authorizations** modal:
   1. Under **Value**, enter your API token value.
   2. Click **Authorize**.
   3. Click **Close**.\
      ![An "Available authorizations" section shows "ApiKeyAuth" section, with a "Value" field. There are "Authorize" and "Close" buttons.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-695da28655f44ba6ecd6804fd04ddc580ea19715%2FUntitled.png?alt=media)
6. You can now try invoking the API:
   1. Choose an endpoint, and expand it by clicking the arrow pointing down.
   2. Click **Try it out**.\
      ![A  "GET /globals" section has a "Try it out" button](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-67bdeb17bbb6d523b4f57decbb0f33ab1d3d87b6%2FScreenshot%202023-12-11%20at%204.36.55%20PM.png?alt=media)
   3. Click **Execute**.
      {% endtab %}

{% tab title="Postman" %}
**Using Postman to access the REST API**

You will import the Panther Postman collection, create a new environment with URL and API variables, then try making a request.

1. Download the `Panther_REST_API_postman_collection.json` file at the bottom of this tab.
2. In your Postman application, click **File** > **Import**.
3. Choose the `Panther_REST_API_postman_collection.json` file.
   * Under **Collections**, there will now be a **Panther Rest API** collection.
4. Click **Environments**, then click the plus sign (**+**).\
   ![A "My Workspace" section has a plus button with the tooltip "Create new environment"](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-9a6f0eb387487414f1ee19bef6f094fd7de6ec95%2FScreenshot%202023-12-12%20at%204.50.38%20PM.png?alt=media)
5. Enter a name for your environment—e.g., "Panther."
6. In the table on the right-hand side, enter the following two variables:
   * `restHost`: For the **Current value**, enter your full Panther REST API URL.
     * You can find this value by following the instructions in [Step 1: Identify your Panther REST API URL](#step-1-identify-your-panther-rest-api-url).
   * `restApiToken`: For the **Current value**, enter your Panther API token. In the **Type** column, select **secret**.

     <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-8908857f5542b6786c044134480fcd5217d86b80%2FScreenshot%202024-03-12%20at%203.25.43%20PM.png?alt=media" alt="A table is shown with two rows filled in: one for restHost and one for restApiToken. There is a Type and Current value for each."><figcaption></figcaption></figure>
7. In the upper-right corner, click **Save**.
8. You can now try making a request:
   1. In the upper-right hand corner, click the environment dropdown, and select the one you created in the previous step.\ <img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-471a8e8281f8a38d0886de2f280d3af0895413bc%2FScreenshot%202023-12-12%20at%205.01.03%20PM.png?alt=media" alt="A drop-down field shows two options: &#x22;No Environment&#x22; and &#x22;Panther&#x22;" data-size="original">
   2. Click **Collections**.
   3. Expand the **Panther Rest API** collection, then select a request.
   4. Click **Send**.

{% file src="<https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-c99b09024de00a73825ba379556a2485e2a8883f%2FPanther%20Rest%20API.postman_collection.json?alt=media>" %}
{% endtab %}

{% tab title="This documentation" %}
**Using the Panther documentation to access the REST API**

1. Navigate to one of the REST API entity pages (nested under this page), and locate the operation you'd like to perform.
2. In the bottom-right corner of the operation's **Request** tile, click **▶Test it**.

   <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-5d9b6f8d7c631e15596f2d26cf2050b3e8780cc8%2FScreenshot%202025-04-15%20at%2012.56.58%E2%80%AFPM.png?alt=media" alt="A &#x22;Get an alert&#x22; section includes cards for &#x22;Path parameters,&#x22; &#x22;Responses,&#x22; and &#x22;Authorizations.&#x22; The &#x22;Test it&#x22; button is circled."><figcaption></figcaption></figure>
3. In the modal that pops up, in the endpoint displayed at the top, click `{api_host}`.\
   ![In a URL value, the {api\_host} section is circled.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-3a580b6b8d3df90c15946ec26f3db56faa67e280%2FScreenshot%202025-04-15%20at%201.00.48%E2%80%AFPM.png?alt=media)
4. In the **api\_host** field, enter the REST API URL you identified in [Step 1](#step-1-identify-your-panther-rest-api-url), without the protocol (i.e., excluding `https://`).\
   ![There is a circle around "api\_host: my-REST-API-URL."](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-9869e45120a0a5e68289790979661c645de297bc%2FScreenshot%202025-04-15%20at%201.02.38%E2%80%AFPM.png?alt=media)
5. In the **Authentication** section, click the **Auth Type** dropdown.
   1. Under **Required authentication**, check the box next to **ApiKeyAuth**.\
      ![Under an "Authentication" header, an arrow is drawn from an "ApiKeyAuth" button to a value labeled "ApiKeyAuth."](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-9cc187a88f9aa27fd161c46bde4ce546e862cc8f%2FScreenshot%202025-04-15%20at%201.17.21%E2%80%AFPM.png?alt=media)
   2. Under **Authentication**, **Name** and **Value** fields will populate. In **Value**, enter the API token you generated in [Step 2](#step-2-generate-an-api-token).
6. In the **Variables** section, if the operation has required path variables, such as `{id}`, provide value(s) in the `VALUE` column.\
   ![Under a "Get an alert" title, there are sub-sections titled Authentication, Variables, and Cookies. The value of "id" within Variables is circled.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-1404542376554e8a09346e0c6a24529f1d692ec0%2FScreenshot%202025-04-15%20at%201.04.28%E2%80%AFPM.png?alt=media)
7. If there are values in the **Query Parameters** section, if you would like them to apply to this invocation, click their checkboxes in the right-hand column.\
   ![A "Query Parameters" header is over a table with columns for "KEY," "VALUE," and a three-lines icon. There are two rows filled in, and the third column is circled.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-30046c73238bc09d3dbb79c5f94bbf60b522cfee%2FScreenshot%202024-03-28%20at%2011.42.58%20AM.png?alt=media)
8. If a request body is required for your request, add content within **Body**.
9. Click **Send Request**.
   {% endtab %}
   {% endtabs %}