/v1/workspaces/{workspace_id}/notification-types/by-key/{key}AuthCreate 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 · uuidId of the workspace.
key*stringThe type key.
Request body
namestringDisplay name.
Example: "Invoice paid"
descriptionstringWhat the notification is for.
category_keystringKey of the category; it must exist (create categories first, or apply an export).
Example: "billing"
routingobjectRouting.
criticalbooleanCritical 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_secondsintegerDeliveries not sent within this many seconds expire.
default_localestringLocale used when the recipient locale has no template (BCP 47).
Example: "en"
email_quiet_hoursbooleanHold email during the recipient quiet hours too (push is always held, the inbox never).
throttleobjectPer-recipient cap for this type; null removes it.
templates*arrayThe 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 · uuidType id.
key*stringKey used when sending.
Example: "invoice.paid"
name*stringDisplay name.
description*stringDescription.
category_id*string · uuidCategory id.
category_key*stringCategory key.
routing*objectRouting.
critical*booleanWhether the type is critical.
ttl_seconds*integerTime to live of a delivery, in seconds.
default_locale*stringFallback locale.
email_quiet_hours*booleanWhether email is held during quiet hours.
throttle*objectPer-recipient cap.
archived_at*string · date-timeWhen archived; archived types cannot be sent.
version*integerIncreases on every change of the type.
templates*arrayThe templates (bodies under `…/templates/{channel}/{locale}`).
created_at*string · date-timeCreated.
updated_at*string · date-timeLast 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"
}