Skip to main content

API Clients (Postman, Insomnia, Bruno)

Zyphr publishes a full OpenAPI 3 specification of every endpoint. Any modern API client — Postman, Insomnia, Bruno, Hoppscotch, Yaak — can import this spec directly to generate a complete, always-current collection of every endpoint, organized by tag, with example payloads.

The OpenAPI spec is the single source of truth and is regenerated automatically alongside the API. There is no separate hand-maintained Postman file to fall out of date.

Where to get the OpenAPI spec​

The spec is available at:

  • Live API: https://api.zyphr.dev/v1/openapi.yaml
  • Staging: https://api.staging.zyphr.dev/v1/openapi.yaml

The spec is auto-generated at build time from JSDoc annotations on the route handlers, so it stays in sync with the live API without any manual maintenance.

You can also browse the spec interactively in the API Reference section of these docs.

Import into Postman​

  1. Open Postman
  2. Click Import (top-left)
  3. Paste the OpenAPI URL: https://api.zyphr.dev/v1/openapi.yaml
  4. Choose OpenAPI 3.0 when prompted, then Import as Collection
  5. Postman generates a complete collection organized by API tag (Auth, Emails, Push, SMS, Inbox, Subscribers, Templates, etc.)

Import into Insomnia​

  1. Click the workspace dropdown → Import / Export → Import Data → From URL
  2. Paste: https://api.zyphr.dev/v1/openapi.yaml
  3. Choose OpenAPI 3.0 when prompted

Import into Bruno​

  1. Collection → Import Collection → OpenAPI V3 Spec
  2. Paste the URL or upload the YAML file

Setting up authentication​

Most Zyphr endpoints use one of two authentication schemes:

HeaderUsed forFormat
Authorization: Bearer <api_key>Server-side endpoints (emails, push, sms, subscribers, etc.)zy_live_xxxx or zy_test_xxxx
X-Application-Key: za_pub_xxxxAuth-as-a-Service public endpointsApplication public key
X-Application-Secret: za_sec_xxxxAuth-as-a-Service server-side endpointsApplication secret

In Postman, you can configure these as collection-level variables once and they propagate to every request:

  1. Open the imported collection's Variables tab
  2. Set apiKey to your Zyphr API key (zy_live_xxxx or zy_test_xxxx)
  3. If you're using Auth-as-a-Service, set applicationKey and applicationSecret too
  4. Save

Test Mode​

Always start with a test key (zy_test_xxxx) when exploring the API. Test-mode requests don't send real messages, don't consume your live quota, and don't appear in production logs.

When you're ready to go live, swap apiKey to a live key (zy_live_xxxx) in the same collection.

Tips​

  • Request IDs in responses — Every response includes meta.request_id. Save it for debugging or include it when filing a support ticket.
  • Collection Runner — Postman's Collection Runner lets you execute multiple requests in sequence (e.g., create a subscriber → send an in-app notification → mark it as read).
  • Regenerate when needed — If we ship new endpoints, re-import the OpenAPI URL to refresh your collection. Existing requests keep your saved variables and example bodies.

Why no hand-maintained Postman collection?​

We used to ship a hand-curated Zyphr_API.postman_collection.json file. It became a maintenance burden — every API addition required a parallel Postman edit, and it inevitably drifted out of date. Importing the live OpenAPI spec gives you the complete current API surface with zero discipline required from us.

If your team has a strong preference for a shipped collection (for example, to commit alongside your application code), reach out to support@zyphr.dev — we can prioritize an auto-generated Postman collection from the spec if there's demand.