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

# API introduction

> Read the data of your Perquery organization from your own code with the read-only Perquery API.

The Perquery API gives your code read access to the data of your organization. Use it to move Perquery data into your own reports, dashboards or data warehouse.

## What you need

* The API access add-on for your organization. Read [Add-ons](https://docs.perquery.ai/en/account/add-ons.md). For prices, go to [perquery.ai/en/pricing](https://perquery.ai/en/pricing).
* An API key. Read [API keys](https://docs.perquery.ai/en/account/api-keys.md).

## Base URL

All requests go to this base URL:

```text theme={null}
https://perquery.ai/api
```

All paths start with `/v1`. For example, the list of your sites is at `https://perquery.ai/api/v1/sites`.

> [!WARNING]
>
> Do not add a slash at the end of a path. The API answers `404` for `/v1/sites/`.

## Main rules

* **Read-only.** The API accepts only `GET` requests. A request with another method gets `403`.
* **JSON.** The API sends JSON responses. Error responses use `application/problem+json`. Read [Errors and limits](https://docs.perquery.ai/en/api/errors-and-limits.md).
* **API key in each request.** Send your key in the `Authorization` header. Read [Authentication](https://docs.perquery.ai/en/api/authentication.md).
* **Same access as the key creator.** A key reads only the data that the roles of its creator allow at the time of the request.
* **UUIDs.** Sites, prompts and other resources have a UUID. Paths use it, for example `/v1/sites/{site_uuid}/prompts`.

## What you can read

An API key can read these types of data:

* Your sites, prompts, personas and competitors.
* The results of visibility scans and the answers of the AI engines.
* The results of content analysis, technical analysis, authority and bot logs.
* Opportunities and impact tracking.
* The status of your integrations.

An API key cannot read or change account data, team data or billing data. Use the Perquery app for these.

## Your first request

**1. Create an API key**

Create a key on the **API Keys** page of the app. Copy the key when the app shows it. Read [API keys](https://docs.perquery.ai/en/account/api-keys.md).

**2. Send a request**

Replace `pq_xxxxxxxxxxxx_your_secret` with your key and run this command:

```bash theme={null}
curl https://perquery.ai/api/v1/sites \
  -H "Authorization: ApiKey pq_xxxxxxxxxxxx_your_secret"
```

**3. Read the response**

The API answers `200` with a JSON object. The `sites` list holds the sites of your organization. Use the `uuid` of a site in the paths of the other endpoints.

## Cached responses

Some endpoints send an `ETag` header. Send this value back in the `If-None-Match` header of the next request. When the data did not change, the API answers `304` with no body.

## Endpoints reference

The **Endpoints** group in the **API reference** tab lists each endpoint with its parameters and its response.

## Related pages

* [Authentication](https://docs.perquery.ai/en/api/authentication.md)
* [Errors and limits](https://docs.perquery.ai/en/api/errors-and-limits.md)
* [API keys](https://docs.perquery.ai/en/account/api-keys.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.