Skip to content
Embabel Worlds

Store a tour somebody exported, or a client recorded

POST
/api/v1/tours/import
curl --request POST \
  --url http://localhost:11044/api/v1/tours/import \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "yaml": "example" }'

yaml carries a tour FILE, not a JSON rendering of a tour: the exchange format and the storage format are the same thing, so what is imported is what a realm would ship and what /export returned. A name a realm or this world already owns is refused with 409 rather than written, because the loader keeps what it finds and the write would never load.

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

Request Bodyrequired

Section titled “Request Bodyrequired”

A tour file in yaml, in the format GET /tours/{id}/export returns and a realm ships; every tour in it is stored as the acting user’s own. 409 when a realm or the world already owns a tour of that name, 400 when the file cannot be read

Media typeapplication/json

A tour file to store

object
yaml
required

The tour’s YAML, as exported or as a realm would ship it

string

Example generated

{
  "yaml": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The tours as stored, with the ids this world gave them

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

409

Section titled “409”

A tour of that name is already shipped here — error names which one

Media typeapplication/json

Why a tour was refused, in the server’s own words

object
error
required

The refusal, as a sentence to show the user

string

Example generated

{
  "error": "example"
}