Install a realm
const url = 'http://localhost:11044/api/v1/realms';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"confirmed":true,"path":"example","ref":"example","repo":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:11044/api/v1/realms \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "confirmed": true, "path": "example", "ref": "example", "repo": "example" }'Installs a realm by cloning a git repository into the world. Use owner/repo shorthand for GitHub repos, or a full URL. Optionally specify a branch or commit SHA via the ref field. With realm admission on, installing also approves the realm’s handlers and browser apps; admission in the response says whether it did: admitted, unchanged, not-admitted, declarative (no WASM program, so it loads from its directory) or off.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Where the realm comes from: either repo, an owner/repo GitHub shorthand or a git URL (https://, git@, file://), cloned into the world under the repository’s name, with an optional ref branch or commit to check out; or path, a realm directory already mounted into the appliance, loaded in place under its directory name with nothing cloned or copied. path wins when both are given, and ref and confirmed are ignored with it. On a repo install, confirmed: true is the user’s explicit go-ahead for an experimental realm, which is otherwise refused with 409 needs-confirmation
Where to install a realm from, the body of POST /realms: a git repository to clone, or a realm directory already mounted into the appliance
object
Set true only once the user has confirmed installing an experimental realm, after a 409 with status needs-confirmation. Ignored for a path install
Absolute path, inside the appliance container, of a mounted realm directory with a realm.yml, such as /realms/realm-esg. Loaded in place, never cloned or copied; the directory’s name becomes the realm’s. Takes precedence over repo
Branch, tag or commit SHA to check out. Null for the repository’s default branch. Ignored for a path install
The repository to clone: owner/repo for GitHub, or a full clone URL. Required unless path is given, and ignored when it is
Example generated
{ "confirmed": true, "path": "example", "ref": "example", "repo": "example"}Responses
Section titled “Responses”Realm installed
object
Neither repo nor path was given, or the path is not a mounted realm directory
A refusal from the realms surface: the word error and the reason
object
Why the request was refused, written to be shown. A failed install or update carries the underlying failure’s message
Always error
Realm already exists, or the realm is experimental and needs confirmed: true; status says which
A refusal from the realms surface: the word error and the reason
object
Why the request was refused, written to be shown. A failed install or update carries the underlying failure’s message
Always error
Not a failure: the realm is experimental and asks the owner to confirm. Retrying with confirmed: true installs it
object
What the realm says the owner is confirming
The realm that asked
Always needs-confirmation
Install failed
A refusal from the realms surface: the word error and the reason
object
Why the request was refused, written to be shown. A failed install or update carries the underlying failure’s message
Always error