Postman & OpenAPI
The API describes itself in two machine-readable formats. Both are generated from the same source as the API, so they always match the endpoints that are available.
| Format | URL | Use it for |
|---|---|---|
| OpenAPI 3.1 | https://app.bookyourpto.com/api/v1/openapi.json | API tools, client generators, contract tests, the API Reference |
| Postman collection (v2.1) | https://app.bookyourpto.com/api/v1/postman.json | Exploring and trying requests in Postman |
Neither needs a token, so you can download them before you have one.
You can also open both from inside the app: the API Reference card on Settings > API links to the interactive reference at /developers/api, which offers the Postman collection and the OpenAPI document as downloads.
Importing into Postman
- Download the collection:
curl -o api-v1.postman_collection.json https://app.bookyourpto.com/api/v1/postman.json - In Postman, choose Import and select the downloaded file.
- Open the collection's Variables and set
apiTokento your token. Keep it in the Current value column so it is not synced or shared with the collection. Every request uses it as a Bearer token. - Send Inspect the current token (
GET /token) to confirm everything works.
The baseUrl variable is set from the address you downloaded the collection from.
Using the OpenAPI document
Most API tools can import the specification directly from its URL or from a downloaded file:
curl -o bookyourpto-openapi.json https://app.bookyourpto.com/api/v1/openapi.json
- Insomnia, Bruno, Hoppscotch and similar clients import OpenAPI 3.1 to create a request collection.
- Client generators (for example OpenAPI Generator) can build a typed client for your language. Regenerate when the specification changes.
- Contract tests can validate your integration's assumptions against the published schemas.
Each operation includes its required scope in an x-required-scope field, and any field-tier scopes in x-field-scopes, alongside its parameters, request and response examples and error responses.
The document's webhooks section describes every webhook event as a request your endpoint receives: its signature headers, its payload schema and an example payload. Tools that read OpenAPI 3.1 webhooks can generate receiver types from it. The Postman collection includes the webhook management requests (/webhooks and /webhook-events), not the events themselves.
Trying requests
The API Reference on this site documents every operation but does not send requests, because the API is for server-to-server use and does not accept calls from other websites. To try requests, import the Postman collection or use curl. The in-app reference at /developers/api shows the same operations with your organization's base URL, and its Test Request button sends a real request with a token you paste in. The token is kept only for that page view and never stored in the browser.