Star
API reference

Workflows and events

Workflows run multi-step sequences that can wait for days. Define them in code with workflow(), or as JSON through this API.

Create a JSON workflow

POST/v1/workflows

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Stores a workflow definition, replacing any with the same name. A workflow registered in code with workflow() under the same name takes precedence.

Body

FieldTypeRequiredDescription
namestringyesThe name you trigger it by.
stepsobject[]yesRun in order. See the step types below.

Step types

StepFields
notifypayload: any notify body. With no user, segment or topic it sends to the instance's user.
waitduration: a number with ms, s, m, h or d, like "3d" or "1.5h".
waitForEventevent: the event name. options.timeout: a duration, default "24h". options.match: fields the event's properties must equal (dot paths allowed).

JSON workflows can't branch. Use a code workflow for conditions. An invalid duration is accepted here and fails the instance when the step runs.

Responses

{
  "name": "onboarding"
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "steps.0.action",
      "message": "Invalid discriminator value. Expected 'notify' | 'wait' | 'waitForEvent'"
    }
  ]
}
Common errors (401, 400, 403, 429, 413, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "forbidden",
  "message": "API key is read-only"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "malformed_json",
  "message": "malformed_json"
}
{
  "error": "payload_too_large",
  "message": "payload_too_large"
}
{
  "error": "internal_error"
}

Example

curl -X POST http://localhost:3000/v1/workflows \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "onboarding",
    "steps": [
      { "action": "notify", "payload": { "template": "welcome" } },
      { "action": "wait", "duration": "1d" },
      { "action": "notify", "payload": { "template": "tips" } }
    ]
  }'
await notifkit.createWorkflow({
  name: "onboarding",
  steps: [
    { action: "notify", payload: { template: "welcome" } },
    { action: "wait", duration: "1d" },
    { action: "notify", payload: { template: "tips" } },
  ],
});

List JSON workflows

GET/v1/workflows

Auth: Project key, or the admin key or a session with x-project-id.

Definitions stored through this API. Workflows registered in code don't appear.

Query parameters

NameTypeDefaultDescription
searchstringSubstring of the name.
limitnumberall1 to 100.

Responses

{
  "workflows": [
    {
      "id": "c3e1a2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d",
      "projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "onboarding",
      "steps": [
        {
          "action": "notify",
          "payload": {
            "template": "welcome"
          }
        },
        {
          "action": "wait",
          "duration": "1d"
        },
        {
          "action": "notify",
          "payload": {
            "template": "tips"
          }
        }
      ],
      "createdAt": "2026-11-10T12:00:00.000Z"
    }
  ]
}
{
  "workflows": []
}
Common errors (401, 400, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl http://localhost:3000/v1/workflows -H "Authorization: Bearer $NK_KEY"
const { workflows } = await notifkit.listWorkflows({ search: "onboarding" });

Trigger a workflow

POST/v1/workflows/trigger

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Starts one instance. Steps without a target send to input.user.id, so trigger one instance per user. An unknown name still answers 202, and the instance never starts, so GET on it returns 404.

Body

FieldTypeRequiredDescription
namestringyesCode or JSON workflow name.
inputobjectnoPassed to the handler as event.
userstring or objectnoShorthand for input.user. An object is an inline user, saved first. If saving fails, the instance still starts.

Responses

{
  "messageId": "1731837600000-0",
  "instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83"
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "name",
      "message": "Invalid input: expected string, received undefined"
    }
  ]
}
Common errors (401, 400, 403, 429, 413, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "forbidden",
  "message": "API key is read-only"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "malformed_json",
  "message": "malformed_json"
}
{
  "error": "payload_too_large",
  "message": "payload_too_large"
}
{
  "error": "internal_error"
}

Example

curl -X POST http://localhost:3000/v1/workflows/trigger \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "onboarding", "user": "usr_123" }'
const { instanceId } = await notifkit.triggerWorkflow({ name: "onboarding", user: "usr_123" });

Get an instance

GET/v1/workflows/instances/{id}

Auth: Project key, or the admin key or a session with x-project-id.

status is pending (waiting to start, or suspended on a wait), running, completed, failed or canceled. steps holds each finished step in call order. A notify step stores what notify returned, a wait step stores its wake-up time in milliseconds, a run step stores its result, and a waitForEvent step stores null while waiting, then the event's properties, or { "timedOut": true }. waiters lists any open waitForEvent.

Path parameters

NameTypeDescription
idstringinstanceId from the trigger.

Responses

{
  "id": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
  "projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "invite",
  "status": "pending",
  "input": {
    "user": {
      "id": "usr_123"
    }
  },
  "createdAt": "2026-11-17T10:00:00.000Z",
  "updatedAt": "2026-11-20T10:00:05.000Z",
  "steps": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
      "stepIndex": "0",
      "action": "notify",
      "output": {
        "success": true,
        "messageId": "1731837600000-4",
        "notificationId": "d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f6a"
      },
      "error": null,
      "createdAt": "2026-11-17T10:00:00.420Z"
    },
    {
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
      "stepIndex": "1",
      "action": "wait",
      "output": {
        "scheduledAt": 1732096800420
      },
      "error": null,
      "createdAt": "2026-11-17T10:00:00.431Z"
    },
    {
      "id": "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f",
      "projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
      "stepIndex": "2",
      "action": "waitForEvent",
      "output": null,
      "error": null,
      "createdAt": "2026-11-20T10:00:05.000Z"
    }
  ],
  "waiters": [
    {
      "id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
      "projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
      "eventName": "invite.accepted",
      "matchCriteria": {
        "userId": "usr_123"
      },
      "expiresAt": "2026-11-21T10:00:05.000Z",
      "createdAt": "2026-11-20T10:00:05.000Z"
    }
  ]
}
{
  "error": "workflow_not_found",
  "id": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83"
}
Common errors (401, 400, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl http://localhost:3000/v1/workflows/instances/9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83 -H "Authorization: Bearer $NK_KEY"
const instance = await notifkit.getWorkflow(instanceId);

Cancel an instance

DELETE/v1/workflows/instances/{id}

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Cancels a pending or running instance and removes its waiters. Remaining steps never run.

Path parameters

NameTypeDescription
idstringInstance id.

Responses

No body.
{
  "error": "workflow_not_cancelable",
  "id": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83"
}
Common errors (401, 400, 403, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "forbidden",
  "message": "API key is read-only"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl -X DELETE http://localhost:3000/v1/workflows/instances/9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83 -H "Authorization: Bearer $NK_KEY"
await notifkit.cancelWorkflow(instanceId);

Send an event

POST/v1/events

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Wakes every instance waiting on this event name whose match fields equal the event's properties. The waiting step resolves to properties. An event nobody waits for is accepted and does nothing.

Headers

HeaderTypeDescription
x-timestampdateWith x-expiry: when the event happened.
x-expirysecondsRejects the event once x-timestamp plus this has passed.

Body

FieldTypeRequiredDescription
namestringyesEvent name, like invite.accepted.
propertiesobjectyesEvent data. Match criteria are checked against it.

Responses

{
  "messageId": "1731837600000-5",
  "eventId": "5d7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c"
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "properties",
      "message": "Invalid input: expected record, received undefined"
    }
  ]
}
{
  "error": "event_expired",
  "message": "Webhook event is expired"
}
{
  "error": "invalid_timestamp",
  "message": "x-timestamp and x-expiry must be a date and a number of seconds"
}
Common errors (401, 400, 403, 429, 413, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "forbidden",
  "message": "API key is read-only"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "malformed_json",
  "message": "malformed_json"
}
{
  "error": "payload_too_large",
  "message": "payload_too_large"
}
{
  "error": "internal_error"
}

Example

curl -X POST http://localhost:3000/v1/events \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "invite.accepted", "properties": { "userId": "usr_123" } }'
await notifkit.ingestEvent({ name: "invite.accepted", properties: { userId: "usr_123" } });