Notify API reference

Notify API · Notification-Types

put/v1/workspaces/{workspace_id}/notification-types/by-key/{key}Auth

Create or replace a notification type by key

Types as code: sets the type and its complete template set in one transaction (the shape `GET /export` returns per type). Fields left out take their defaults; templates not listed are deleted; unchanged templates keep their version. Applying the same body again changes nothing, so the call is safe to retry without an `Idempotency-Key`. Use it to promote types from a staging workspace. An archived type stays archived.

Path parameters

workspace_id*string · uuid

Id of the workspace.

key*string

The type key.

Request body

namestring

Display name.

Example: "Invoice paid"

descriptionstring

What the notification is for.

category_keystring

Key of the category; it must exist (create categories first, or apply an export).

Example: "billing"

routingobject

Routing.

criticalboolean

Critical types (security notices) ignore opt-outs and quiet hours and use their own rate budget. They never bypass hard bounces, spam complaints or Mail suppression.

ttl_secondsinteger

Deliveries not sent within this many seconds expire.

default_localestring

Locale used when the recipient locale has no template (BCP 47).

Example: "en"

email_quiet_hoursboolean

Hold email during the recipient quiet hours too (push is always held, the inbox never).

throttleobject

Per-recipient cap for this type; null removes it.

templates*array

The complete template set: templates not listed are deleted, unchanged ones keep their version. Each `body` is kept exactly as sent.

Response · 200 Replaced (or unchanged).

id*string · uuid

Type id.

key*string

Key used when sending.

Example: "invoice.paid"

name*string

Display name.

description*string

Description.

category_id*string · uuid

Category id.

category_key*string

Category key.

routing*object

Routing.

critical*boolean

Whether the type is critical.

ttl_seconds*integer

Time to live of a delivery, in seconds.

default_locale*string

Fallback locale.

email_quiet_hours*boolean

Whether email is held during quiet hours.

throttle*object

Per-recipient cap.

archived_at*string · date-time

When archived; archived types cannot be sent.

version*integer

Increases on every change of the type.

templates*array

The templates (bodies under `…/templates/{channel}/{locale}`).

created_at*string · date-time

Created.

updated_at*string · date-time

Last change.

Example

Request

PUT https://api.notify.productcraft.co/v1/workspaces/{workspace_id}/notification-types/by-key/{key}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "Invoice paid",
  "description": "string",
  "category_key": "billing",
  "routing": {},
  "critical": false,
  "ttl_seconds": 0,
  "default_locale": "en",
  "email_quiet_hours": false,
  "throttle": {},
  "templates": [
    {
      "channel": "inbox",
      "locale": "string",
      "body": {}
    }
  ]
}

Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "key": "invoice.paid",
  "name": "string",
  "description": "string",
  "category_id": "00000000-0000-0000-0000-000000000000",
  "category_key": "string",
  "routing": {},
  "critical": false,
  "ttl_seconds": 0,
  "default_locale": "string",
  "email_quiet_hours": false,
  "throttle": {},
  "archived_at": "2026-01-01T00:00:00.000Z",
  "version": 0,
  "templates": [
    {
      "channel": {},
      "locale": "pt-PT",
      "version": 0,
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}