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

# Quick start with Plerion API

> This section describes how to quickly get started with the Plerion API using curl. For a more detailed guide, see the sections below.

## Getting started with curl

<Steps>
  <Step title="Install curl if it isn't already installed on your machine">
    To check if curl is installed, execute `curl --version` in the command line. If the output is information about the version of curl, it is installed. If you get a message similar to `command not found: curl`, you need to download and install `curl`. For more information, see the [curl project download page](https://curl.se/download.html)
  </Step>

  <Step title="Create a Tenant API key">
    Create a Tenant API key accessing [Tenant API Keys dashboard](https://app.plerion.com/settings/api-keys)

    <Frame caption="Go to Settings > API Keys">
      <img src="https://mintcdn.com/pleriondocs/rGvQ5xgTVRw_KLys/images/product/api-keys/image01.png?fit=max&auto=format&n=rGvQ5xgTVRw_KLys&q=85&s=a37bc1edd73068052a6d75b6f60f8b68" alt="API Key" width="2001" height="884" data-path="images/product/api-keys/image01.png" />
    </Frame>

    <br />

    <Frame caption="Add a API Key name and Create API Key">
      <img src="https://mintcdn.com/pleriondocs/rGvQ5xgTVRw_KLys/images/product/api-keys/image02.png?fit=max&auto=format&n=rGvQ5xgTVRw_KLys&q=85&s=d925964aa3c02909d4bbf3d413a72015" alt="API Name" width="3158" height="910" data-path="images/product/api-keys/image02.png" />
    </Frame>

    <Warning>
      Treat your API key like a password. Do not store it as plain text or expose it in any code base.
    </Warning>
  </Step>

  <Step title="Use the curl command to make your request">
    Pass your API key in an Authorization header. Replace `{PLERION_API_KEY}` with your API key.

    ```
    export PLERION_API_URL={region}.api.plerion.com
    export PLERION_API_KEY=PLERION_API_KEY

    curl --request GET \
            --url "https://$PLERION_API_URL/v1/tenant/findings" \
                    --header "Authorization: Bearer $PLERION_API_KEY"
    ```
  </Step>
</Steps>

## Overview

Plerion API uses API keys to authenticate requests. You can view and manage your API keys in the Tenant API Keys dashboard.

API responses are JSON-encoded.

### Authentication

To authenticate to Plerion API send the API Key using bearer auth in the Authorization header.
`Authorization: Bearer $PLERION_API_KEY`
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

### Errors

Plerion uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted). Codes in the 5xx range indicate an error with Plerion's servers.

Some 4xx errors that could be handled programmatically include an error code that briefly explains the error reported. Detailed description for the status code can be found in the **Response Status Codes** section.

### Response Status Codes

The Plerion API endpoints return the following HTTP response status codes.

| Status Code | Definition            | Description                                                                                                                                                                                     |
| ----------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200         | OK                    | The request has succeeded.                                                                                                                                                                      |
| 201         | Created               | The request has been fulfilled and resulted in a new resource being created.                                                                                                                    |
| 204         | No Content            | The server has fulfilled the request but does not need to return an entity-body.                                                                                                                |
| 400         | Bad Request           | The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.                                                      |
| 401         | Unauthorized          | The request requires user authentication. If the request already included Authorization credentials, then the 401 response indicates that authorization has been refused for those credentials. |
| 403         | Forbidden             | The server understood the request, but is refusing to fulfill it. Authorization will not fix the issue and the request SHOULD NOT be repeated.                                                  |
| 404         | Not Found             | The server has not found anything matching the Request-URI.                                                                                                                                     |
| 405         | Method Not Allowed    | The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.                                                                                         |
| 409         | Conflict              | The request could not be completed due to a conflict with the current state of the resource.                                                                                                    |
| 429         | Too Many Requests     | Too many requests occurred during the allotted time period and rate limiting was applied.                                                                                                       |
| 500         | Internal Server Error | The request did not complete due to an internal error on the server side. The server encountered an unexpected condition which prevented it from fulfilling the request.                        |
| 503         | Service Unavailable   | The server is currently unable to handle the request due to a temporary overloading or maintenance of the server.                                                                               |