# 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:
[**Download `panther-labs-api.yaml`**](https://openapi.gitbook.com/o/-LgddDaIOc7MA4mxoaPa/spec/panther-labs-api.yaml)
{% 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:
* 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`):
{% 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://`).\
4. Click **Authorize**.\
5. In the **Available authorizations** modal:
1. Under **Value**, enter your API token value.
2. Click **Authorize**.
3. Click **Close**.\
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**.\
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 (**+**).\
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**.
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.\
2. Click **Collections**.
3. Expand the **Panther Rest API** collection, then select a request.
4. Click **Send**.
{% file src="" %}
{% 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**.
3. In the modal that pops up, in the endpoint displayed at the top, click `{api_host}`.\
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://`).\
5. In the **Authentication** section, click the **Auth Type** dropdown.
1. Under **Required authentication**, check the box next to **ApiKeyAuth**.\
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.\
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.\
8. If a request body is required for your request, add content within **Body**.
9. Click **Send Request**.
{% endtab %}
{% endtabs %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.panther.com/panther-developer-workflows/api/rest.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
2. Click **Collections**.
3. Expand the **Panther Rest API** collection, then select a request.
4. Click **Send**.
{% file src="