Skip to content
Embabel Worlds

Create or update a handler, gated on TypeScript compilation

POST
/api/v1/admin/handlers/save
curl --request POST \
  --url http://localhost:11044/api/v1/admin/handlers/save \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "autonomous": true, "description": "example", "inputTypeNames": [ "example" ], "name": "example", "outputTypeName": "example", "schedule": "example", "signalType": "example", "skills": [ "example" ], "source": "example" }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The handler to create, or to replace when the caller’s world already has one of that name; persisted only when source passes the tsc gate, else ok: false with the reason. signalType * (the default) means no signal trigger, schedule is an optional 6-field cron expression, autonomous marks a handler that writes, and inputTypeNames with outputTypeName make it planner-chainable. A blank description falls back to the name

Media typeapplication/json

A handler to create or update, with its triggers.

object
autonomous

When true the handler may apply external/write effects; when false, the default, it runs observe-only.

boolean
description

One line describing what it does. Defaults to the name.

string
inputTypeNames

Domain types this action consumes. Declaring them makes it planner-chainable rather than reaction-only.

Array<string>
unique items
name
required

The handler’s name. Saving under an existing name replaces that handler.

string
outputTypeName

Domain type the body returns, bound on the blackboard so later actions chain on it. ‘void’ for a side-effecting action.

string
schedule

Optional 6-field cron expression; null = not scheduled.

string
signalType

Signal.typeName (or simple name) that fires this handler; ‘*’ = none.

string
skills

Skills bundled with this agent, put in front of the model that writes and refines it.

Array<string>
source
required

The TypeScript handler body. Type-checked first: a body that does not compile is not saved.

string

Example generated

{
  "autonomous": true,
  "description": "example",
  "inputTypeNames": [
    "example"
  ],
  "name": "example",
  "outputTypeName": "example",
  "schedule": "example",
  "signalType": "example",
  "skills": [
    "example"
  ],
  "source": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

Whether it was persisted, and the server’s own sentence about it

Media typeapplication/json

Whether the mutation landed, and what the server has to say about it.

object
message
required

The server’s own sentence about the outcome; on a failed save, the TypeScript errors. Show it rather than replace it.

string
ok
required

Whether the save or delete landed. A save that does not type-check is not persisted.

boolean

Example generated

{
  "message": "example",
  "ok": true
}

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"
}