Events API

An event is how you start a workflow from outside Duraton. POST /events ingests one event; Duraton matches it against every workflow trigger in the project and returns what it started. Every ingested event is also kept in a durable event log you can read and tail.

Send an event

import { createClient } from "@duraton/sdk/client";

const duraton = createClient({ url: process.env.DURATON_URL! });
const res = await duraton.events.send({
  name: "ticket.created",
  app: "support-app",
  data: { ticketId: "T-421" },
});

from duraton.client import AsyncDuratonClient, SendEventInput

async with AsyncDuratonClient() as dx:
    res = await dx.events.send(SendEventInput(name="ticket.created", app="support-app", data={"ticketId": "T-421"}))
    res.run_id

import (
	"context"
	"encoding/json"

	"duraton.dev/sdk-go/client"
)

dx := client.New(client.Options{})

res, err := dx.Events.Send(context.Background(), client.SendEventInput{
	Name: "ticket.created", App: "support-app", Data: json.RawMessage(`{"ticketId":"T-421"}`),
})
res.RunID

curl -X POST $DURATON_URL/events \
  -d '{"name":"ticket.created","app":"support-app","data":{"ticketId":"T-421"}}'

Request body

app, runner, targetApp, dedupeId, and session are each bounded at 256 characters; a longer value, a blank name, or unparseable data returns 400. tags is bounded too: at most 20 tags per run, each key up to 64 characters matching [A-Za-z0-9_.-] and each value up to 256 characters - an over-limit tag returns 400.

Unsupported characters

An event must not carry a NUL character (\u0000). Duraton's durable event log has no representation for it, so an event carrying one could never be stored. Duraton rejects it at ingest with a 400 - before any workflow is matched or any run is started - rather than accepting the event and failing later.

The check covers every text field (name, app, runner, dedupeId, targetApp, session) and the whole data payload, at any depth: a NUL inside a nested string, an array element, or even a JSON object key is rejected.

curl -X POST $DURATON_URL/events \
  -d '{"name":"ticket.created","app":"support-app","data":{"note":"bad\u0000byte"}}'
# 400

Response

202 Accepted. The body reports what the event did:

{
  "runId": "01HXYZ...",
  "woke": 0,
  "triggered": [
    { "workflow": "fulfillment", "runId": "01H..." },
    { "workflow": "audit", "runId": "01H..." }
  ]
}

An event that matches nothing still returns 202 with an empty triggered - it is recorded, not lost.

Each triggered entry's runId resolves to a run, and that run records the event back: its eventId is this event's id (see runs). List every run one event fanned out with GET /runs?eventId=<id>. Cron, child (step.runWorkflow), and on-failure runs carry no eventId - they have no triggering event.

Two kinds of deduplication

Two independent mechanisms can each report deduped: true, and they mean different things. Knowing which one fired matters, because one throws the event away and the other only suppresses a single run.

In short: dedupeId is event-level and total - the exact same event is collapsed to a no-op, nothing is recorded, and nothing is woken. It is the safety net for an at-least-once caller retrying POST /events. idempotency is run-level and partial - the event still lands, still wakes waiters, and still runs every other matching workflow; only a second run of the idempotent workflow for the same derived key is suppressed within the window.

Because both surface deduped: true, tell them apart by the rest of the response: an event-level drop returns no triggered array and no runId, whereas an idempotency drop still carries the event's triggered fan-out with deduped set on the affected entry.

Reading the log

The log records every event with what it did, newest first.

curl "$DURATON_URL/events?app=support-app&name=ticket.created&limit=20"

Each record carries the event (name, app, data), its source (api for an external POST, emit for a workflow's step.emit), when it arrived, and the triggered fan-out:

{
  "id": "9f2b...",
  "name": "ticket.created",
  "app": "support-app",
  "source": "api",
  "data": { "ticketId": "T-421" },
  "receivedAt": "2026-06-15T09:00:00Z",
  "woke": 0,
  "triggered": [{ "workflow": "fulfillment", "runId": "01H..." }]
}