Skip to content
Embabel Worlds

Declare what this screen can be told to do

POST
/api/v1/ui/surface
curl --request POST \
  --url http://localhost:11044/api/v1/ui/surface \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "fields": [ "example" ], "panels": { "additionalProperty": { "controls": [ "example" ], "fields": [ "example" ] } }, "surface": "example", "version": 1 }'

The surface’s own tour dictionary, sent verbatim. The assistant may then offer to fill the fields it names. states and dynamic are a tour’s business and are ignored. Controls are recorded and never pressed.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The screen’s tour dictionary, sent verbatim: surface names the screen (console, me), version the dictionary format, and panels maps each panel to its fields and controls. The field names across every panel become what the assistant may offer to fill; states, dynamic and any other key are ignored. Replaces whatever dictionary this user last published, from any screen

Media typeapplication/json

What a connected surface says it can be told to do: its tour dictionary, sent to POST /ui/surface. Unknown keys (a tour’s states and dynamic) are ignored.

object
fields
required

Derived from panels: every panel’s field names in the order declared, duplicates dropped. A client need not send it

Array<string>
panels
required

Published panel name to the fields and controls that panel offers; empty when omitted

object
key
additional properties

One panel’s published vocabulary in a surface dictionary: the fields the assistant may fill and the controls a tour may press

object
controls
required

Names of controls the surface can press. Recorded only: the assistant has no verb that presses one

Array<string>
fields
required

Names of the fields on this panel the assistant may offer to fill; empty when omitted

Array<string>
surface
required

Which surface this is, e.g. console or me. Recorded and echoed back, not yet acted on

string
version
required

Version of the dictionary format the client writes, so a newer client can be recognised rather than misread

integer format: int32

Example generated

{
  "fields": [
    "example"
  ],
  "panels": {
    "additionalProperty": {
      "controls": [
        "example"
      ],
      "fields": [
        "example"
      ]
    }
  },
  "surface": "example",
  "version": 1
}

Responses

Section titled “Responses”

200

Section titled “200”

Recorded; the fields now offered are echoed back

Media typeapplication/json

The surface recorded, and the fields the assistant will now offer to fill

object
fields
required

Field names the assistant may now fill

Array<string>
surface
required

The surface recorded

string

Example generated

{
  "fields": [
    "example"
  ],
  "surface": "example"
}

401

Section titled “401”

Basic-auth challenge failed