API reference

The map of PushMesh's public API documentation — where to start, in what order to read, and what each page answers.

API reference

PushMesh’s public API lives at https://api.pushmesh.io, under the /api/v1 path. Everything an integration needs is here: you do not need an account to read this entire reference, and that is deliberate — we would rather you knew what you are getting into before you decide.

What sets this API apart from every other push API fits in one line: besides successful (“the provider accepted it”), it returns recebidos — how many devices provably received the message, with cryptographic proof coming from the device itself.

The addresses

What	Address	What it is for
API	`https://api.pushmesh.io`	the address for everything in this reference: your server, the SDK and any custom client talk here
Dashboard	`https://app.pushmesh.io`	where the application, the API key and the delivery credentials are created
Site	`https://pushmesh.io`	the storefront, the pricing and this documentation
React Native SDK	`npm install @pushmesh/sdk` — npmjs.com/package/@pushmesh/sdk	device registration, delivery receipts and in-app already solved inside the app
Support	`contato@pushmesh.io`	integration questions, anything that does not match this documentation, or agreeing on volume before you go live

No route in this reference requires an account to read. To call one you need an application and a key — both are created in the dashboard, covered in Applications and keys.

If you have 15 minutes

Read in this order. These are the three pages that take you from zero to a first push with proof of delivery:

Getting started — the commands you copy and run.
Authentication and errors — the key, the error envelope and the status table.
Delivery credentials — what to have in hand for a push to actually leave.

If you are evaluating the product

Four pages answer the questions that usually decide the choice:

Question	Page
“do you really prove delivery, or is it the same old ‘sent’?”	Delivery receipts
“how much work is leaving my current provider?”	Migrating from another provider
“what are all the caps, and what happens when I exceed one?”	Limits
“what do you keep from my base, and for how long?”	Data, retention and privacy

Every page

#	Page	What it answers
1	Getting started	zero to first push with a receipt, through the SDK or straight against the API
2	Authentication and errors	key format, rotation without downtime, error envelope, statuses and edges
3	Devices	register, identify the user, update, read and export the base
4	Send a push	audience, content, scheduling, priority, idempotency and dry run
5	Delivery receipts	the proof of arrival, what it guarantees, and how to read a send’s result
6	In-App messages	in-app campaigns, formats, triggers and the funnel
7	Webhooks	being notified instead of polling, with HMAC signatures and redelivery
8	Migrating from another provider	what is accepted as-is, what changes, and what nobody automates
9	Delivery credentials	FCM and APNs, field by field, including Apple’s environment trap
10	Applications and keys	create an application, rotate the key, and the public Firebase parameters
11	Limits	every cap, including the free plan’s commercial allowance
12	Headers	everything the API accepts and emits, including the `X-Pm-*` set
13	Data, retention and privacy	what personal data comes in, how long it stays, and how to honour a deletion request
14	Versioning	what is frozen by contract and what may change without notice

Three things that will save your first afternoon

successful is not delivery. It is provider acceptance. The proof of arrival is recebidos, and it comes from the device.
Not every 200 is what it looks like. An empty id with recipients: 0 means “nobody reachable”, not failure; and errors may arrive as an array or as an object inside the same 200.
The pm_live_ key never goes into the published app. The routes the device calls were designed to take no credential for exactly that reason.

A note on language

The API’s own text — the errors strings and the explain.causa / explain.como_corrigir fields — is emitted in Brazilian Portuguese, with no language negotiation. Throughout this English reference the JSON examples show those strings exactly as they arrive on the wire, so what you read here matches what your logs will hold, with the English meaning given alongside. Branch your code on the HTTP status and the structured fields, never on the sentence.

If something here does not match reality

Then this page is wrong, and we want to know. Every API response carries the X-Pm-Request-Id header: quote that identifier to contato@pushmesh.io and we will find the exact call.