# API overview

> Automate Proteside stores, scripts, alerts and PCI DSS reports with the v1 REST API, and receive events via webhook.

URL: https://docs.proteside.com/en/docs/api

The public v1 API gives you programmatic access to almost everything you do in the dashboard. Use it to integrate
Proteside with your CI/CD, SIEM, ticketing tool or partner dashboard, and use webhooks to react to events without
polling the API.

## What you can automate
* **Stores:** create a store, get the SDK key and installation snippet, adjust the SDK configuration, rotate the key
  and check whether the SDK is installed.
* **Payment pages:** register the checkout URLs the SDK should protect.
* **Scripts:** list the inventory and authorize or block scripts with a justification (PCI DSS 4.0, requirement
  6.4.3).
* **Rules:** create, enable, disable and delete block or allow rules by domain, URL or hash.
* **Approval policies:** create, simulate and apply policies that decide on scripts automatically.
* **Alerts:** list, view, resolve and reopen alerts.
* **PCI DSS reports:** generate and download reports in JSON, PDF or CSV, and schedule weekly or monthly delivery.
* **Webhooks:** register endpoints, Slack and Microsoft Teams channels, and send test events.
* **Partners:** create child organizations, act on them and track each one's usage.

## Before you start
| Item           | Value                                    |
| -------------- | ---------------------------------------- |
| Base URL       | `https://app.proteside.com/api/v1`       |
| Transport      | HTTPS, JSON request bodies and responses |
| Field names    | `snake_case`                             |
| Authentication | `Authorization: Bearer ps_live_…`        |
| Rate limit     | 120 requests per minute per organization |

> **There's no test environment**
>
> Every token issued is `ps_live_` and every call acts on your production data. To experiment, use a staging store
> and tokens with read-only scopes.

The API is designed for server-to-server calls: authenticated routes don't respond to CORS, so calls made directly
from the browser are blocked. Keep the token on your backend.

## Quick start
### Create a token
In **Settings → API**, click **New token**, give it a name, check the **read-only** shortcut and click
**Create token**. Copy the token in the **Copy your token now** window: it's shown only once. The full walkthrough is
in [Tokens and scopes](https://docs.proteside.com/en/docs/api/authentication).

### Make your first request
List your organization's stores:

```bash
export PROTESIDE_TOKEN="ps_live_YOUR_TOKEN"

curl -s "https://app.proteside.com/api/v1/stores?limit=2" \
  -H "Authorization: Bearer $PROTESIDE_TOKEN"
```

### Read the response
Lists always come in `data`, with `next_cursor` to fetch the next page (`null` when there are no more):

```json
{
  "data": [
    {
      "id": "0c1d2e3f-1111-4222-8333-444455556666",
      "org_id": "7f3c1e2a-0b4d-4c8e-9f10-2a3b4c5d6e7f",
      "name": "My Store",
      "domain": "mystore.com",
      "country": "BR",
      "timezone": "America/Sao_Paulo",
      "status": "active",
      "sdk_key": "pk_live_YOUR_KEY",
      "safe_slug": "mystore-ps3fa9c1",
      "emergency_contact": null,
      "created_at": "2026-09-27T10:01:00.000Z",
      "updated_at": "2026-09-27T10:01:00.000Z",
      "sdk_config": {
        "mode": "monitor",
        "payment_methods": ["pix", "card"],
        "release_channel": "stable"
      }
    }
  ],
  "next_cursor": null
}
```

The `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers show how much of the per-minute limit you have left. See
[Conventions](https://docs.proteside.com/en/docs/api/conventions) for pagination, errors and limits.

## OpenAPI specification
The full API contract is at [`https://app.proteside.com/api/v1/openapi.json`](https://app.proteside.com/api/v1/openapi.json)
(OpenAPI 3.1, public, no token required). Import that address into Postman, Insomnia or your language's client
generator. This documentation's [endpoint reference](https://docs.proteside.com/en/docs/api/reference/stores/listStores) is generated from it.

> **Note**
>
> When this documentation and the spec disagree, what's described here prevails: the conceptual pages document the
> API's actual behavior, including the places where the spec is still out of date.

## Next steps
- [Tokens and scopes](https://docs.proteside.com/en/docs/api/authentication): Create, use and revoke tokens with the least privilege possible.
- [Conventions](https://docs.proteside.com/en/docs/api/conventions): Pagination, errors, rate limits and idempotency.
- [Webhooks](https://docs.proteside.com/en/docs/api/webhooks): Receive signed events and validate the signature.
- [Partners](https://docs.proteside.com/en/docs/api/partners): Manage child organizations with a single token.
- [Recipes](https://docs.proteside.com/en/docs/api/recipes): End-to-end flows with curl, from registering a store to the PCI report.

## Endpoint reference
- [Stores](https://docs.proteside.com/en/docs/api/reference/stores/listStores): Create, configure, suspend and rotate the SDK key.
- [Pages](https://docs.proteside.com/en/docs/api/reference/pages/listPages): Protected payment pages.
- [Scripts](https://docs.proteside.com/en/docs/api/reference/scripts/listScripts): Inventory, authorization and blocking.
- [Rules](https://docs.proteside.com/en/docs/api/reference/rules/listRules): Block and allow by domain, URL or hash.
- [Policies](https://docs.proteside.com/en/docs/api/reference/policies/listPolicies): Automatic approval policies.
- [Alerts](https://docs.proteside.com/en/docs/api/reference/alerts/listAlerts): View, resolve and reopen.
- [Reports](https://docs.proteside.com/en/docs/api/reference/reports/getPciReport): PCI DSS report and schedules.
- [Webhooks](https://docs.proteside.com/en/docs/api/reference/webhooks/listWebhooks): Webhook, Slack and Teams channels.
- [Organizations](https://docs.proteside.com/en/docs/api/reference/organizations/listOrganizations): Child organizations and usage.
- [Meta](https://docs.proteside.com/en/docs/api/reference/meta/getOpenApi): OpenAPI document.
