Skip to content
Embabel Worlds

Every tour this world offers

GET
/api/v1/tours
curl --request GET \
  --url http://localhost:11044/api/v1/tours \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'

Shipped, realm-contributed and user-saved alike. presentation is whatever the tour’s YAML declared, carried through untouched — the client owns that vocabulary.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
username
string

Username to act as, whose world holds the tours; when it resolves to a user it is used in preference to the authenticated principal. Omitted or blank, the authenticated principal acts; 401 when neither resolves

Responses

Section titled “Responses”

200

Section titled “200”

Every tour declared for the acting user’s world

Media typeapplication/json

Every tour declared for a world

object
tours
required

The tours, shipped, realm-contributed and user-saved alike; on import, only the tours just stored

Array<object>

A tour: its identity, its provenance, and the client’s own declarations

object
declaredId
required

What the tour’s own file called it — the id that survives an export

string
deletable
required

This world can remove it. NOT the same as userSaved: a tour hand-written into a user’s own config is theirs but is not this server’s to delete, so a client offering Delete for it would offer a button that silently does nothing.

boolean
id
required

Unique within this world, and what every other call addresses

string
presentation
required

Everything the tour’s YAML declared beyond id and steps, uninterpreted

object
key
additional properties
source

The realm that shipped it, or absent for a world’s own and a user’s own. Carried rather than derived from the id — a namespace prefix is not something a client can reliably strip.

string
steps
required

The tour’s steps in walking order; a step’s position here is the index the status call takes

Array<object>

One step, as its file declared it — minus the precondition, which stays server-side

object
presentation
required

Everything the step’s YAML declared except its doneWhen and when preconditions, carried through uninterpreted — the client owns that vocabulary

object
key
additional properties
watchable
required

This step HAS a precondition, without saying what it is. A client that hands a step to the user can then poll for it and carry on by itself when the world says the user has done the thing — go and connect a coding agent, and the tour notices. Without this flag a client would have to poll every hand-over blindly, spending a query every few seconds on steps that can never come true.

boolean
userSaved
required

Imported or recorded by this user, rather than shipped by a realm or the world

boolean

Example generated

{
  "tours": [
    {
      "declaredId": "example",
      "deletable": true,
      "id": "example",
      "presentation": {
        "additionalProperty": "example"
      },
      "source": "example",
      "steps": [
        {
          "presentation": {
            "additionalProperty": "example"
          },
          "watchable": true
        }
      ],
      "userSaved": true
    }
  ]
}

401

Section titled “401”

Basic-auth challenge failed