---
title: "REST API"
description: "The PgBeam REST API. Control-plane endpoints for projects, databases, policies, agents, analytics, and platform state, described by an OpenAPI 3.1 spec at https://pgbeam.com/openapi.json."
canonical: "https://pgbeam.com/docs/api"
last-updated: "2026-10-30T13:45:52.000Z"
---

# REST API

> The PgBeam REST API. Control-plane endpoints for projects, databases, policies, agents, analytics, and platform state, described by an OpenAPI 3.1 spec at https://pgbeam.com/openapi.json.

URL: https://pgbeam.com/docs/api

The PgBeam API is the control plane behind the dashboard and CLI. Use it when you want to automate project creation, database setup, usage reporting, cache configuration, or onboarding from your own tooling.

**Base URL:** `https://api.pgbeam.com`

> **Prefer the CLI?**
>
> The [PgBeam CLI](/docs/cli) wraps the same API and is usually the fastest way
> to explore the platform from a terminal. Reach for the raw API when you need
> custom automation, CI integration, or your own internal tooling.

## What this API is good at

| Area       | Use it for                                                                      |
| ---------- | ------------------------------------------------------------------------------- |
| Projects   | Create, inspect, update, and delete PgBeam projects                             |
| Databases  | Register origin databases, test connectivity, and adjust pool or cache settings |
| Agents     | Issue, inspect, and revoke scoped agent and human credentials                   |
| Policies   | Manage policy profiles: access mode, allowlists, row filters, masking, budgets  |
| Approvals  | List, approve, and reject held writes and DDL                                   |
| Webhooks   | Configure HMAC-signed webhook and SIEM audit export endpoints                   |
| Anomalies  | List and triage anomaly alerts                                                  |
| Migrations | Lint DDL for locks, rewrites, and unsafe changes                                |
| Analytics  | Read usage, activity, metrics, and query insights                               |
| Platform   | Discover regions, plans, and health                                             |
| Account    | Export account data and track onboarding progress                               |

## Authentication

Most endpoints require `Authorization: Bearer ...`. The credential can be either:

| Credential      | How to get it                                                            | Header                            |
| --------------- | ------------------------------------------------------------------------ | --------------------------------- |
| Dashboard token | Sign in to the dashboard and reuse the session token in trusted tooling  | `Authorization: Bearer <token>`   |
| API key         | Create one from the dashboard for scripts, CI, and long-lived automation | `Authorization: Bearer <api-key>` |

**Bearer token**

```bash
curl -H "Authorization: Bearer <token>" \
  https://api.pgbeam.com/v1/projects
```

**API key**

```bash
curl -H "Authorization: Bearer <api-key>" \
  https://api.pgbeam.com/v1/projects
```

`/v1/health` is public. Everything else in the public API expects auth.

See [API Keys](/docs/api-keys) for key creation and rotation.

## OpenAPI & Codegen

The public spec is available at [api.pgbeam.com/openapi.json](https://api.pgbeam.com/openapi.json). It is the source for our SDK and the generated endpoint pages in this section.

### Download the spec

```bash
curl -o openapi.json https://api.pgbeam.com/openapi.json
```

### Generate a client

Feed the spec to your OpenAPI tooling of choice. For example, with [openapi-generator](https://openapi-generator.tech/):

```bash
openapi-generator generate \
  -i openapi.json \
  -g typescript-fetch \
  -o ./generated-client
```

> **Official TypeScript SDK**
>
> If you are working in TypeScript, use the official [PgBeam SDK](/docs/ts-sdk)
> instead of generating a client. It is maintained alongside the API and
> provides tag-based access, error handling, and full type safety out of the
> box.

## Next steps

* [Response Conventions](/docs/api/response-conventions) — status codes, pagination, and error envelopes