Skip to content
Embabel Worlds

Promote a reviewed provisional realm to a name you stand behind

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Id of the held realm-draft review whose installed provisional realm is promoted; 404 when it is unknown, expired or another user’s. The review is released once the promotion succeeds

Request Bodyrequired

Section titled “Request Bodyrequired”

name is the realm name to promote to: it becomes the realm’s directory under the world’s realms and the name in its manifest. Promotion never overwrites, so an existing realm of that name is refused with 409, as is a provisional realm whose files or revision no longer match its install receipt

Media typeapplication/json

The name to promote a reviewed provisional realm to, sent to POST /learn/{id}/promote

object
name
required

The promoted realm’s directory name in this world; a realm of that name already existing is refused 409, since promotion never overwrites

string

Example generated

{
  "name": "example"
}

Responses

Section titled “Responses”

409

Section titled “409”

A realm of that name already exists — promotion never overwrites; REVISION_STALE: the installed realm came from another revision of this source; or DIGEST_STALE: the realm’s files changed since its install receipt

Media typeapplication/json

A refusal that names a machine-readable code beside its explanation

object
code
required

The refusal’s code, for a client that branches rather than reads. Every value comes from the sealed LearningReviewRefusal hierarchy, except SOURCE_UNREADABLE which the 502 path builds directly.

string
Allowed values: REVISION_STALE WARNINGS_STALE WARNINGS_NOT_ACKNOWLEDGED DIGEST_STALE SOURCE_CHANGED LEARNING_IN_PROGRESS DECISION_UNKNOWN CHANGE_INVALID SOURCE_UNREADABLE
error
required

What was refused and what to do about it, written to be shown to the person reviewing

string

Example 

{
  "code": "REVISION_STALE"
}