PushizoDocs
API reference

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.

Base URLs

EnvironmentURL
Production (global)https://api.pushizo.com
Data region cellsA 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 serverAPI_URL / PUBLIC_API_URL (e.g. https://api.pushizo.com)
Local developmenthttp://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 use multipart/form-data. Field names are snake_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 the request_id in the error envelope and can be searched on the dashboard Logs screen. The error code is also returned in the x-hs-error-code header.
  • Multilingual texts are given as objects: { "tr": "…", "en": "…" }; if the recipient's language is missing, en is used, and if that is missing too, the first language.
  • DELETE/POST responses with an empty body return { "ok": true } or 204; PATCH is merge-patch (only the fields you send change, null deletes).
  • Clients that don't support the PATCH/DELETE methods can use POST with X-HTTP-Method-Override.
  • All responses carry the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

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

TagPageKey operations
NotificationsnotificationsPOST /v1/notifications, estimate, status, deliveries, cancel
Users and subscriptionsusersupsert, alias, subscription, search, export/delete, events
Event definitionseventsdefinition list, conversion flag
SegmentssegmentsCRUD, preview, estimate
Templatestemplatesversions, render, duplicate
Campaignscampaignslifecycle, statistics, A/B
Journeysjourneysdefinition, publish, runs
In-app, notification inbox and shared inbox settings, preferences, suppressionin-app, inbox, preferences, suppressionscanned responses, teams, agents, inbox metrics
Conversations (live chat, WhatsApp, SMS, email)conversationslist, messages, reply, assignment, status, read, tags
Adsadsad audience sync, lookalike, campaign/budget, spend, attribution, LTV, Conversions API, budget alerts
Web growth toolsweb-campaigns, forms, surveys, landing-pagespop-up/banner, form submissions, NPS report, landing page publishing
Channels, Live Activities, deliverability, dynamic contentchannels, live-activities, email-deliverability, dynamic-content
Webhooks, analytics, export/import, data warehouse, integrations, MCPwebhooks, analytics, exports, warehouse, integrations, mcp
Apps, organization, API and identity keys, systemapps, organization, api-keys, identity-keys, system
SDK endpoints (client)sdkconfig, 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

LanguagePackageStatus
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, CordovaPushizo (SPM), com.pushizo:pushizo-android (+ pushizo-android-hms), @pushizo/react-native, @pushizo/capacitor, cordova-plugin-pushizoAvailable (SPM, Maven Central 0.1.0, npm 0.1.0). CocoaPods coming soon
Flutterpushizo_flutterAvailable (pub.dev 0.1.0)
Unitycom.pushizo.unity (OpenUPM)Available (OpenUPM 0.1.0)
.NET MAUIPushizo.MauiComing 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

On this page