API overview
Pushizo public REST API — base URL, authentication and scopes, request/response conventions, error envelope, rate limits, pagination, idempotency, webhook signatures, versioning, data residency, SDKs, MCP, OpenAPI and Postman.
The public REST API lives under https://api.pushizo.com/v1/… (OpenAPI 3.1, 306 operations, 33 tags). The contract is the openapi.yaml file and no breaking changes are made to it; all operations are documented on per-resource pages, with parameters, schemas, responses and examples in 8 languages for each operation. Interactive docs (Scalar) and "Try it" links: api.pushizo.com/docs.
Authentication
API keys, scope list, app/org scoping, proof of ownership and identity verification on SDK endpoints.
Rate limits
Plan-based request rate, X-RateLimit headers, 429 and Retry-After, IP limits, quotas.
Idempotency
Idempotency-Key header, 24-hour retention, conflict and in-progress request behavior.
Pagination
Cursor-based lists: limit, cursor, next_cursor, has_more; filtering and sorting.
Versioning
/v1 compatibility policy, addition rules, deprecation, API changelog.
Error catalog
HS_* codes, HTTP statuses, retry rules.
Base URLs
| Environment | URL |
|---|---|
| Production (global) | https://api.pushizo.com |
| Data region cells | A regional root based on the org's region (e.g. EU/TR); a request sent to the wrong cell returns 421 HS_WRONG_CELL + details.api_url, and the SDKs follow it automatically (data residency) |
| Your own server | API_URL / PUBLIC_API_URL (e.g. https://api.pushizo.com) |
| Local development | http://localhost:4000 (/docs, /openapi.json) |
Authentication (summary)
Authorization: Bearer hs_live_…Keys are scoped: notifications:write, users:read, users:write, events:write, segments:read, analytics:read, mcp:write, admin. The scope each operation requires is listed under the operation title. Client SDK endpoints (/sdk/v1/…) don't use API keys; they work with proof of ownership and identity verification. Details: authentication, API keys.
Request and response conventions
- Bodies are JSON (
Content-Type: application/json); imports usemultipart/form-data. Field names aresnake_case, timestamps are ISO 8601 UTC (2026-10-17T09:00:00Z). - IDs are prefixed ULIDs:
app_,usr_,sub_,msg_,dlv_,seg_,tpl_,cmp_,jrn_,whe_,key_,cvs_(conversation),adu_(ad audience),wcp_(web campaign),frm_,srv_,lpg_… - Every response carries
x-request-id; it matches therequest_idin the error envelope and can be searched on the dashboard Logs screen. The error code is also returned in thex-hs-error-codeheader. - Multilingual texts are given as objects:
{ "tr": "…", "en": "…" }; if the recipient's language is missing,enis used, and if that is missing too, the first language. DELETE/POSTresponses with an empty body return{ "ok": true }or204;PATCHis merge-patch (only the fields you send change,nulldeletes).- Clients that don't support the
PATCH/DELETEmethods can usePOSTwithX-HTTP-Method-Override. - All responses carry the
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Resetheaders.
Error envelope
{
"error": {
"code": "HS_VALIDATION_ERROR",
"message": "The request could not be validated.",
"details": { "issues": [{ "path": "contents", "message": "Required" }] },
"request_id": "req_01…",
"doc_url": "https://docs.pushizo.com/errors#HS_VALIDATION_ERROR"
}
}See the error catalog for 400 HS_VALIDATION_ERROR schema errors, 401 HS_UNAUTHENTICATED, 403 HS_FORBIDDEN (scope/IP), 404 HS_NOT_FOUND (resources of other tenants also return 404), 409 HS_CONFLICT / HS_IDEMPOTENCY_*, 422 HS_NO_RECIPIENTS / HS_CONTENT_INVALID / HS_CHANNEL_NOT_CONFIGURED, 429 HS_RATE_LIMITED / HS_QUOTA_EXCEEDED, and 5xx.
Resources
| Tag | Page | Key operations |
|---|---|---|
| Notifications | notifications | POST /v1/notifications, estimate, status, deliveries, cancel |
| Users and subscriptions | users | upsert, alias, subscription, search, export/delete, events |
| Event definitions | events | definition list, conversion flag |
| Segments | segments | CRUD, preview, estimate |
| Templates | templates | versions, render, duplicate |
| Campaigns | campaigns | lifecycle, statistics, A/B |
| Journeys | journeys | definition, publish, runs |
| In-app, notification inbox and shared inbox settings, preferences, suppression | in-app, inbox, preferences, suppressions | canned responses, teams, agents, inbox metrics |
| Conversations (live chat, WhatsApp, SMS, email) | conversations | list, messages, reply, assignment, status, read, tags |
| Ads | ads | ad audience sync, lookalike, campaign/budget, spend, attribution, LTV, Conversions API, budget alerts |
| Web growth tools | web-campaigns, forms, surveys, landing-pages | pop-up/banner, form submissions, NPS report, landing page publishing |
| Channels, Live Activities, deliverability, dynamic content | channels, live-activities, email-deliverability, dynamic-content | |
| Webhooks, analytics, export/import, data warehouse, integrations, MCP | webhooks, analytics, exports, warehouse, integrations, mcp | |
| Apps, organization, API and identity keys, system | apps, organization, api-keys, identity-keys, system | |
| SDK endpoints (client) | sdk | config, subscription, login/logout, events, delivery feedback, in-app, inbox, live chat, web campaigns, form and survey submission |
All object schemas: Schemas. Changes: API changelog.
Webhook signature
Outgoing webhooks carry a Pushizo-Signature: t=<unix>,v1=<hex> header; v1 = HMAC-SHA256(secret, t + "." + ham_gövde) (ham_gövde = raw body), 5-minute tolerance, two v1 values during a rotation window. Verification examples and the event list: Webhooks.
SDKs
| Language | Package | Status |
|---|---|---|
| Web (browser) | script tag /sdk-web/PushizoSDK.js, GTM, WordPress; @pushizo/web (npm) | Available (npm 0.1.0) |
| Server: REST (cURL) | — | Available |
| Node.js, Go, Java, .NET, PHP, Python, Ruby | @pushizo/node, github.com/pushizo/pushizo-go, com.pushizo:pushizo-java, Pushizo (NuGet), pushizo/pushizo-php, pushizo (PyPI), pushizo (RubyGems) | Available (npm / Go proxy / Maven Central / NuGet / Packagist / PyPI / RubyGems 0.1.0) |
| iOS (SPM), Android, React Native, Capacitor, Cordova | Pushizo (SPM), com.pushizo:pushizo-android (+ pushizo-android-hms), @pushizo/react-native, @pushizo/capacitor, cordova-plugin-pushizo | Available (SPM, Maven Central 0.1.0, npm 0.1.0). CocoaPods coming soon |
| Flutter | pushizo_flutter | Available (pub.dev 0.1.0) |
| Unity | com.pushizo.unity (OpenUPM) | Available (OpenUPM 0.1.0) |
| .NET MAUI | Pushizo.Maui | Coming soon (macOS build); can be installed from source |
The server SDKs are generated from OpenAPI; the examples in this reference are verified against the real method names. Guides: SDKs.
MCP server
The MCP server for AI assistants (Claude, Cursor…) connects via OAuth 2.1; read tools query reports and resources, while write tools only create campaign/segment drafts (mcp:write) and never send anything. Setup: MCP; endpoints: API → MCP.
Downloadable contract
Rust SDK
The pushizo crate on crates.io — Rust 1.71+, ureq; models and services generated from OpenAPI, retries, idempotency, pagination, webhook signature verification.
Authentication
Bearer API keys, scopes and app/org context for the public API; proof of ownership (token_hash) and identity verification (identity_hash HMAC or ES256 JWT) on client SDK endpoints; error responses.