Create a watch

POST

/api/v1/watches

curl --request POST \
  --url http://localhost:11044/api/v1/watches \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "cron": "example", "delivery": { "channel": "example", "format": "example", "headers": { "additionalProperty": "example" }, "secret": "example", "tier": "example", "url": "example" }, "diffSpec": { "compareFields": [ "example" ], "ignoreFields": [ "example" ], "keyPath": "example", "keyedListFields": { "additionalProperty": "example" }, "resultMode": "AUTO", "setFields": [ "example" ], "transitions": [ { "crossesAbove": 1, "crossesBelow": 1, "field": "example", "from": {}, "name": "example", "to": {} } ] }, "enabled": true, "firstRunPolicy": "ESTABLISH_BASELINE", "lensId": "example", "name": "example", "params": { "additionalProperty": "example" } }'

• Your world, at the port the installer gives it

Authorizations

• apiKeyAuth
• basicAuth

Request Body^required

The watch to create over one of the caller’s saved lenses. lensId must name a lens the caller can open (400 otherwise); name defaults to the lens id; params are the lens arguments every run uses. cron is a Spring six-field cron expression (seconds first) that schedules runs, and omitted or blank means runs happen only on request; an unparseable one is 400. diffSpec chooses what counts as a change, delivery where changes are sent (omitted: kept in history only), firstRunPolicy whether the first run only records a baseline (ESTABLISH_BASELINE, the default) or reports everything as new (EMIT_CURRENT), and enabled (default true) whether it runs at all

Media typeapplication/json

The body of POST /watches: which saved lens to watch with what arguments, when to run it, and how to compare and deliver what changes.

object

cron

Spring cron expression, six fields with seconds first (such as 0 0 8 * * *), evaluated in the server’s time zone. Omitted or blank, the watch runs only when POST /watches/{watchId}/runs asks

string

delivery

Where each diff is sent: channel notification (the inbox), signal (the agent bus) or webhook. Omitted or null, diffs are kept in the watch’s history only

object

channel

required

The adapter: notification (the inbox, the default), signal (the bus, for agents) or webhook (a URL). A lowercase adapter id

string

format

required

A webhook’s body: json (the whole diff, the default) or slack (a text summary an incoming webhook shows as-is)

string

headers

required

Extra headers sent on every webhook delivery, e.g. an Authorization. At most 16; X-World-* and Content-Type cannot be set. Values are write-only: a read masks each, and an update that sends a mask back keeps that value

object

key

additional properties

string

secret

When set, a webhook body is signed with HMAC-SHA256 under it, sent as X-World-Signature: sha256=<hex>. Write-only: a read returns ••••••••, and an update that sends that back keeps the stored secret

string

tier

required

The inbox tier a notification delivery is filed at: AMBIENT (the default), DEFERRED, TIMELY, INTERRUPTIVE, ACTING or ESCALATING, case-insensitive; anything else files as AMBIENT. Read by no other channel

string

url

The http(s) URL a webhook delivery is POSTed to. Required for webhook; unused otherwise

string

diffSpec

required

How a run’s result is compared with the previous complete run’s; omitted takes every DiffSpec default

object

compareFields

required

The fields compared. Empty compares a structured item whole; an entity always compares source, id, name, description and labels, and these are added to them

Array<string>

unique items

ignoreFields

required

Fields removed before comparing, so a change to one is never a change. May not overlap compareFields

Array<string>

unique items

keyPath

The path to each item’s key in a structured result. Required when the result is an array; for a single object it is optional. Unused for entities, which are keyed by source and id

string

keyedListFields

required

Array fields of objects, each mapped to the path of the key within an element: elements are ordered by that key before comparing, so a reordering is not a change

object

key

additional properties

string

resultMode

required

ENTITIES compares the lens’s graph entities, STRUCTURED its structured data, and AUTO (the default) picks STRUCTURED only when the lens returned no entities but did return data

string

Allowed values: AUTO ENTITIES STRUCTURED

setFields

required

Array fields compared as unordered sets, so a reordering is not a change

Array<string>

unique items

transitions

required

Named transitions to recognise among an updated item’s field changes

Array<object>

A named domain transition: matched when one field of an updated item changes in the stated way. Every condition given must hold, and at least one must be given

object

crossesAbove

Matches a numeric field going from at or below this value to above it

number format: double

crossesBelow

Matches a numeric field going from at or above this value to below it

number format: double

field

required

The dotted path of the field watched. Must be in compareFields, or one of an entity’s own source, id, name, description or labels

string

from

The JSON value the field must have changed from. Absent matches any

object

name

required

What to call the transition; reported as the kind of each one detected

string

to

The JSON value the field must have changed to. Absent matches any

object

enabled

required

False creates the watch switched off, so it is not scheduled and runs are refused; true when omitted

boolean

firstRunPolicy

required

ESTABLISH_BASELINE (the default): the first run records what the lens shows and produces no diff. EMIT_CURRENT: the first run is diffed against nothing, so everything it finds is reported

string

Allowed values: ESTABLISH_BASELINE EMIT_CURRENT

lensId

required

Id of the saved lens to watch; it must be one the signed-in user can open

string

name

required

Label for the watch; the lensId when omitted or blank

string

params

required

Arguments given to the lens on every run, by parameter name; empty runs it on its defaults

object

key

additional properties

Responses

200

OK

Media typeapplication/json

object

Example ^generated

{}