API Reference
Overview
notifito exposes two API surfaces:
- Public API (
edge) — consumed by the widget, seller integrations, and provider webhooks - Internal API (
core) — consumed by other notifito services (dashboard, admin, dispatch)
All API keys are prefixed: pk_ (publishable) for client-side use, sk_ (secret) for server-to-server.
Public API (edge)
Base URL: http://edge:8000
Widget Endpoints
Get attribute schema
GET /v1/widget/schema
Returns the attribute schema for an item type. Cached. No authentication required (origin-restricted).
Query Parameters:| Parameter | Required | Description |
|---|---|---|
key | Yes | Publishable API key (pk_live_xxx) |
item_type | Yes | Item type slug |
{
"id": "uuid",
"name": "Sneaker",
"slug": "sneaker",
"schema_version": 1,
"attributes": [
{
"key": "size",
"label": "Size",
"type": "enum",
"options": ["40", "41", "42"],
"required": true,
"matchable": true,
"multiple": false
}
]
}
Submit subscription
POST /v1/widget/subscriptions
Creates a new subscription (pending confirmation). Requires pk_ key in Authorization header and valid Origin header.
{
"key": "pk_live_xxx",
"item_type": "sneaker",
"item_id": "uuid (optional)",
"attributes": {
"size": "42"
},
"contact_value": "consumer@example.com"
}
201 Created
{
"subscription_id": "uuid",
"status": "pending_confirmation"
}
422 with error details on failure.
Confirm subscription
GET /c/{token}
Confirms a subscription via the signed, expiring, single-use token sent to the consumer. Returns 302 Redirect to the seller's action URL (or a success page).
Unsubscribe
GET /u/{token}
One-click unsubscribe via signed token. No login required. Returns 302 Redirect to a confirmation page.
Push API
Report availability
POST /v1/availability
Seller signals that a product or service is available. Requires sk_ key in Authorization header.
{
"item_type_id": "uuid",
"item_id": "uuid (optional)",
"attributes": {
"size": "42"
},
"capacity": 10,
"available_from": "2026-09-01T00:00:00Z",
"available_until": "2026-09-08T00:00:00Z",
"idempotency_key": "unique-key-123"
}
202 Accepted
{
"event_id": "uuid",
"status": "accepted"
}
idempotency_key prevents duplicate processing. Retrying with the same key returns the same response.
Validation: Attribute bag validated against the schema with requireRequired: false (omitted attributes are wildcards).
Webhook Endpoints
Delivery status
POST /webhooks/postmark
Provider webhook for delivery status updates. Authenticated via HTTP Basic (Postmark webhook credentials).
Request:{
"delivery_id": "uuid",
"status": "delivered",
"provider_message_id": "pm-123",
"detail": null,
"occurred_at": "2026-08-28T10:05:00Z"
}
Rate Limiting
All public endpoints are rate-limited:
| Scope | Limit | Window |
|---|---|---|
| Per API key | 100 requests | 1 minute |
| Per IP | 60 requests | 1 minute |
| Widget submit | 10 requests | 1 minute |
Internal API (core)
Base URL: http://core:8000
All internal endpoints require the X-Notifito-Internal-Secret header.
Authentication
POST /internal/auth/login
Authenticates a dashboard/admin user. Returns user and tenant data.
Key Resolution
POST /internal/keys/resolve
Resolves an API key to its tenant.
Item Types
| Method | Path | Purpose |
|---|---|---|
| GET | /internal/tenants/{tenant}/item-types | List item types for a tenant |
| POST | /internal/tenants/{tenant}/item-types | Create a new item type |
| GET | /internal/tenants/{tenant}/item-types/{itemType} | Get item type detail |
Subscriptions
| Method | Path | Purpose |
|---|---|---|
| POST | /internal/subscriptions | Create a subscription |
| POST | /internal/subscriptions/confirm | Confirm a subscription |
| POST | /internal/subscriptions/unsubscribe | Unsubscribe |
Availability
POST /internal/availability
Ingests an availability event (used by dashboard notify form).
Dashboard Key
POST /internal/tenants/{tenant}/keys/dashboard
Issues a dashboard API key for a tenant.
Admin Internal API (core)
Base URL: http://core:8000
All admin endpoints are under /internal/admin/* and require both the X-Notifito-Internal-Secret header and an admin session.
Authentication
| Method | Path | Purpose |
|---|---|---|
| POST | /internal/admin/auth/login | Authenticate admin user |
| POST | /internal/admin/auth/logout | Destroy admin session |
Tenant Management
| Method | Path | Purpose |
|---|---|---|
| GET | /internal/admin/tenants | List all tenants with counts |
| POST | /internal/admin/tenants | Create a new tenant |
| GET | /internal/admin/tenants/{tenant} | Get tenant detail |
| PUT | /internal/admin/tenants/{tenant} | Update tenant |
| GET | /internal/admin/tenants/{tenant}/users | List users for a tenant |
| POST | /internal/admin/tenants/{tenant}/users | Create a user for a tenant |
| GET | /internal/admin/tenants/{tenant}/keys | List API keys for a tenant |
| POST | /internal/admin/tenants/{tenant}/keys | Issue a new API key |
| DELETE | /internal/admin/tenants/{tenant}/keys/{key} | Revoke an API key |
Cross-Tenant Search
| Method | Path | Purpose |
|---|---|---|
| GET | /internal/admin/subscriptions | Search subscriptions across tenants |
| GET | /internal/admin/subscriptions/{subscription} | Subscription detail |
| GET | /internal/admin/deliveries | Recent deliveries across tenants |
tenant_id, status, email, item_type_id (paginated, 50 per page).
Delivery log filters: tenant_id, status, date_range (paginated, 50 per page).
Error Responses
All endpoints return consistent error formats:
Validation error (422)
{
"message": "The given data was invalid.",
"errors": {
"email": ["The email field is required."],
"attributes.size": ["Size must be one of: 40, 41, 42."]
}
}
Authentication error (401)
{
"message": "Invalid credentials."
}
Not found (404)
{
"message": "Not found."
}
Rate limited (429)
{
"message": "Too many requests.",
"retry_after": 60
}