REST API Overview
Base URL, versioning, authentication, and the common request/response shape.
Base URL
https://api.zeepnotti.example/v1TBD - the production SaaS domain isn't finalized yet; replace this
placeholder once it is. All endpoints below are relative to this base,
including the /v1 prefix - there is currently only one API version.
Authentication
ZeepNotti has three ways to authenticate a request. Which one applies depends on the endpoint - most routes accept exactly one, a few accept either of two:
| Auth method | Header / mechanism | Used for |
|---|---|---|
| REST key | Authorization: Bearer rk_... | Server-to-server calls: Notifications, Templates, Segments, Webhooks |
| Client key | Authorization: Bearer ck_... | Device-facing calls only: device registration (Devices) |
| Admin session | Session cookie (POST /v1/auth/login) | Dashboard-only management: Apps |
- Devices is the one route group that accepts either a REST key or a Client key - a Client key is meant to ship inside a mobile/web client, so it is scoped to registering and updating that client's own device.
- Notifications, Templates, Segments, Webhooks accept an admin session or a REST key - use the REST key for any server-side integration; the session path exists for the dashboard itself.
- Apps (creating an App, rotating its keys) is admin-session-only. There is no REST-key path to create or modify an App - keys authenticate as an App, they don't manage Apps.
Both key types are generated per App (rk_ + 32 hex bytes for REST, ck_ +
32 hex bytes for Client), shown in full exactly once at creation or rotation
time. ZeepNotti stores only a hash - if you lose a key, rotate it, you cannot
retrieve the original value again. See
the Apps API Reference and Get Started with ZeepNotti for the
creation and rotation calls.
An invalid, missing, or expired credential returns 401:
{ "error": { "code": "unauthorized", "message": "missing or invalid API key" } }Request / response shape
Request bodies are JSON, sent with Content-Type: application/json.
Success responses return the resource directly - there is no data
envelope:
{ "id": "ntf_...", "status": "pending", "app_id": "app_..." }Errors always come back as a JSON object under an error key with a stable
code and a human-readable message:
{ "error": { "code": "invalid_target", "message": "target_type and target_value are required" } }Common code values you'll see across endpoints: unauthorized /
unauthenticated (401), forbidden (403), idempotency_conflict (409),
invalid_target / invalid_content / invalid_body / not_scheduled
(422), internal_error (500). Exact codes are documented per endpoint in
each handler group's reference page.