Skip to content
Embabel Worlds

Run a TypeScript handler observe-only against a sample or the most recent matching signal

POST
/api/v1/admin/handlers/dry-run
curl --request POST \
  --url http://localhost:11044/api/v1/admin/handlers/dry-run \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "sample": { "additionalProperty": "example" }, "signalType": "example", "source": "example" }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The TypeScript source to run and what to run it against. A sample is bound as the signal when given, its typeName and id keys naming it; otherwise the most recent signal of signalType in the caller’s graph is used, and with signalType omitted, *, or no such signal in the graph the handler runs against a cron tick. Observe-only: nothing is saved and nothing external changes

Media typeapplication/json

A handler body to run observe-only, and what to run it against.

object
sample

A sample signal to bind INSTEAD of sampling the graph — for an event not yet received.

object
key
additional properties
signalType

The signal type to sample a real recent event from. Null or ‘*’ means a cron tick.

string
source
required

The TypeScript handler body to run. Nothing is saved, and the run applies no external effects.

string

Example generated

{
  "sample": {
    "additionalProperty": "example"
  },
  "signalType": "example",
  "source": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

What the run saw, logged, and how it ended

Media typeapplication/json

The outcome of an observe-only handler run: what it saw, what it logged, and how it ended.

object
error

The failure message when the body threw. Serialized as null otherwise — consumers test for the key.

string
ok
required

False when the body threw; error then carries the message.

boolean
output

What the body RETURNED, when it returned something. A handler that ends with return rows and never logs is not silent — this is its result. Absent when the body returned nothing.

ranAgainst
required

The signal the run actually bound, which may differ from the one asked for.

object
signalId
required

Id of the signal bound: the sampled signal’s id, a sample’s id (else sample), or cron for a cron tick.

string
signalType
required

Simple type name of the signal bound: the sampled signal’s, or for a sample its typeName (else the requested type, else SampleSignal), or CronTick when nothing matching was on record.

string
stdout
required

Everything the body logged. The brief tells a handler to log every effect, so this IS the feedback surface.

string

Example generated

{
  "error": "example",
  "ok": true,
  "output": "example",
  "ranAgainst": {
    "signalId": "example",
    "signalType": "example"
  },
  "stdout": "example"
}

401

Section titled “401”

No authenticated principal

Media typeapplication/json

A refusal carrying only a human-readable reason.

object
error
required

What went wrong, in the terms the caller can act on.

string

Example generated

{
  "error": "example"
}