Skip to main content
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:
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.

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.
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.
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.
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

Authenticate API requests

Choose between the API key and the bootstrap token.

Handle errors

Look up the status that a refused request gets, and read the error body.