Skip to content
Embabel Worlds

Install the reviewed proposal: a PROVISIONAL realm, queryable immediately, or a database description

POST
/api/v1/learn/{id}/install
curl --request POST \
  --url http://localhost:11044/api/v1/learn/example/install \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "acknowledgedWarnings": [ "example" ], "description": "example", "revision": "example" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Id of the held review to install: a realm draft installs as a provisional realm, a database-description review saves its reviewed description. 404 when it is unknown, expired or another user’s

Request Body

Section titled “Request Body”

Optional for a realm draft. revision and acknowledgedWarnings claim the review the installer read: when either is given, the revision must be the draft’s current one (409 REVISION_STALE) and every warning the review shows must be acknowledged by id (400 WARNINGS_NOT_ACKNOWLEDGED; an unknown id is 409 WARNINGS_STALE); both absent installs unacknowledged. For a database-description review, description is the reviewed wording to save and is required (400 when absent); it is ignored for a realm draft

Media typeapplication/json

What the installer reviewed, sent to POST /learn/{id}/install. The body is optional: with revision and acknowledgedWarnings both absent the realm still installs, and its receipt records it as unacknowledged

object
acknowledgedWarnings

Ids of the review’s warnings the installer acknowledges. Once revision or this is given, every warning the review shows must be here (400 WARNINGS_NOT_ACKNOWLEDGED), and an id it no longer shows is 409 WARNINGS_STALE

Array<string>
description

The reviewed wording of a database-description proposal; required for one (400 when absent), ignored for a realm proposal

string
revision

The revision the installer reviewed; one that is no longer current is refused 409 REVISION_STALE. Absent skips the check

string

Example generated

{
  "acknowledgedWarnings": [
    "example"
  ],
  "description": "example",
  "revision": "example"
}

Responses

Section titled “Responses”

400

Section titled “400”

WARNINGS_NOT_ACKNOWLEDGED: a warning the review shows was not acknowledged

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

409

Section titled “409”

REVISION_STALE or WARNINGS_STALE: the review changed; fetch it again. SOURCE_CHANGED: the source served another description since; learn it again

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