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

# API reference

> Call pgw's admin API: the base URL, JSON bodies, size limits, and the playground on this site.

Every `pgw` command that manages a running gateway calls this API, so anything that you can do by hand you can also automate. Use the API from a provisioning system that creates users, from a sign-in service that signs users out, or from a dashboard that reads the push log.

The API is served on the admin listener, under `/api/v1`:

```text theme={null}
http://127.0.0.1:8080/api/v1
```

The admin listener defaults to `127.0.0.1:8080`, so only processes on the pgw host can reach it. If you changed `admin_listen`, use its address in the base URL.

To check that the API answers, get your tenant.

```bash theme={null}
curl -s -H "Authorization: Bearer $PGW_API_KEY" http://127.0.0.1:8080/api/v1/tenant
```

```json theme={null}
{"id":"DcHpsqWx_FKNm02Ie3Z-Gg","name":"test","created_at":"2026-11-15T23:53:01Z"}
```

## Requests and responses

* Request and response bodies are JSON. A request body is one JSON object.
* A request body can be up to 1 MiB, or 16 MiB for `POST /api/v1/config/sync`.
* pgw refuses a body with a field that the endpoint doesn't know, or with data after the JSON object.
* Every `GET` endpoint also answers `HEAD`.
* Responses carry `Cache-Control: no-store`, because a response can hold an API key.

## Use the playground

Each endpoint page has a **Try it** button that sends the request from your browser directly to your pgw. pgw must allow this site's origin, and your browser must reach the admin listener.

**1. Allow this site's origin**

In the pgw configuration file, add this site to `admin_cors_origins`.

```yaml theme={null}
admin_cors_origins:
  - https://docs.pgw.sipmicro.services
```

You can set `PGW_ADMIN_CORS_ORIGINS=https://docs.pgw.sipmicro.services` instead, with commas between several origins. With the default empty list, pgw sends no CORS headers, and browsers block the playground's requests.

**2. Restart pgw**

pgw reads `admin_cors_origins` only when it starts.

```bash theme={null}
sudo systemctl restart pgw
```

**3. Forward the admin port**

If pgw runs on another host, forward the admin listener's port to your computer over SSH, and keep the session open. Replace `pgw.example.com` with your pgw host.

```bash theme={null}
ssh -L 8080:127.0.0.1:8080 pgw.example.com
```

**4. Check the base URL**

The playground's default base URL is `http://127.0.0.1:8080/api/v1`. If the admin listener has another address on your computer, edit it.

**5. Send the request**

Enter your API key. For an endpoint that takes the bootstrap token, type the word `Bootstrap`, a space, and the token. Then choose **Send**. When Chrome asks whether this site may access devices on your local network, allow it.

## Next steps

> [card] [Authenticate API requests](https://docs.pgw.sipmicro.services/api/authentication.md)
>
> Choose between the API key and the bootstrap token.

> [card] [Handle errors](https://docs.pgw.sipmicro.services/api/errors.md)
>
> Look up the status that a refused request gets, and read the error body.


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