API Reference

Overview

notifito exposes two API surfaces:

  1. Public API (edge) — consumed by the widget, seller integrations, and provider webhooks
  2. 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:
ParameterRequiredDescription
keyYesPublishable API key (pk_live_xxx)
item_typeYesItem type slug
Response:
json
{

"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.

Request:
json
{

"key": "pk_live_xxx",

"item_type": "sneaker",

"item_id": "uuid (optional)",

"attributes": {

"size": "42"

},

"contact_value": "consumer@example.com"

}

Response: 201 Created
json
{

"subscription_id": "uuid",

"status": "pending_confirmation"

}

Validation: Attribute bag validated against the item type's schema. Returns 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.

Request:
json
{

"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"

}

Response: 202 Accepted
json
{

"event_id": "uuid",

"status": "accepted"

}

Idempotency: The 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:
json
{

"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:

ScopeLimitWindow
Per API key100 requests1 minute
Per IP60 requests1 minute
Widget submit10 requests1 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

MethodPathPurpose
GET/internal/tenants/{tenant}/item-typesList item types for a tenant
POST/internal/tenants/{tenant}/item-typesCreate a new item type
GET/internal/tenants/{tenant}/item-types/{itemType}Get item type detail

Subscriptions

MethodPathPurpose
POST/internal/subscriptionsCreate a subscription
POST/internal/subscriptions/confirmConfirm a subscription
POST/internal/subscriptions/unsubscribeUnsubscribe

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

MethodPathPurpose
POST/internal/admin/auth/loginAuthenticate admin user
POST/internal/admin/auth/logoutDestroy admin session

Tenant Management

MethodPathPurpose
GET/internal/admin/tenantsList all tenants with counts
POST/internal/admin/tenantsCreate a new tenant
GET/internal/admin/tenants/{tenant}Get tenant detail
PUT/internal/admin/tenants/{tenant}Update tenant
GET/internal/admin/tenants/{tenant}/usersList users for a tenant
POST/internal/admin/tenants/{tenant}/usersCreate a user for a tenant
GET/internal/admin/tenants/{tenant}/keysList API keys for a tenant
POST/internal/admin/tenants/{tenant}/keysIssue a new API key
DELETE/internal/admin/tenants/{tenant}/keys/{key}Revoke an API key

Cross-Tenant Search

MethodPathPurpose
GET/internal/admin/subscriptionsSearch subscriptions across tenants
GET/internal/admin/subscriptions/{subscription}Subscription detail
GET/internal/admin/deliveriesRecent deliveries across tenants
Subscription search filters: 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)

json
{

"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)

json
{

"message": "Invalid credentials."

}

Not found (404)

json
{

"message": "Not found."

}

Rate limited (429)

json
{

"message": "Too many requests.",

"retry_after": 60

}