Get started
Color

The API documentation page

Open your server's public Developers page for the API reference, sign-in and key rules, webhook setup and code in curl, JavaScript and Python.

For
OwnerAdministrator
Hosting
Any hosting
Devices
All devices
Business
All businesses

Checked against Pop Dispatch 0.1.0

Every Pop Dispatch server hosts a documentation page for its API. You will be able to hand it to a developer, who can build an integration from it without asking you for anything but a key.

Before you start #

Nothing. The page is public and needs no sign-in, so it opens for anyone who can reach your server's address. It holds no business data: only how the API works.

Steps #

  1. Open Settings, then Integration keys, and choose the Developers link. The same link sits at the end of the main menu for owners and managers. It opens /developers on your server in a new tab, for example https://your-address/developers.
  2. Use the list on the left to jump to a section. On a phone the list sits above the text.
  3. Read the guide sections in order: Overview and conventions, Authentication, API keys, Webhooks, Pagination, Idempotency, Errors, Rate limits and Examples.
  4. Open the Endpoint reference. Endpoints are grouped by area. Choose one to see the role needed, the key scopes that reach it, and code in curl, JavaScript (fetch) and Python (requests).
  5. Choose OpenAPI document to download the machine-readable description from /developers/openapi.json. Import it into Postman, Insomnia or a code generator.

What the page holds #

  • Overview and conventions: the base address, JSON, times in UTC, money in cents and request ids.
  • Authentication: sign-in tokens, integration keys, roles and the four key scopes.
  • API keys: how an owner or manager makes a key in Settings, Integration keys, and which scope to choose.
  • Webhooks: adding an endpoint, the events, the signing secret and how to verify a signature.
  • Pagination, idempotency, errors and rate limits: the rules every call follows.
  • Examples: sign in, list customers, create a job and verify a webhook signature, each in the three languages.
  • Endpoint reference: every route your server offers.
Technical details
  • The reference is built from the server's own route table when the page is requested, so it lists exactly what your server version offers. The addresses in the examples use the host name the browser asked for.
  • The page loads nothing from other websites: one built-in style block, no scripts, no fonts and no images. Its security headers refuse framing and send no referrer.
  • The same OpenAPI document is at /developers/openapi.json and at GET /api/v1/openapi.json. A copy is kept in the program's source as docs/api/openapi.json, and a test fails when that copy is out of date.
  • The page answers before the web console does, so /developers always shows the documentation.

If something goes wrong #

  • You see the console instead of the documentation: the server is an older version. Update it. See "Updates and your license".
  • The examples show the wrong host name: open the page through your public address instead of an internal one.
  • A call from the examples answers 401: the key is missing, ended or typed wrongly. See "Integration keys and scopes".