Skip to content

Remove a realm

DELETE
/api/v1/realms/{name}
curl --request DELETE \
--url 'http://localhost:11044/api/v1/realms/example?keepData=false' \
--header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'

Removes an installed realm from the world, with the reference nodes it seeded and the documents its sources ingested unless keepData is set; data in the response counts them. Removing also withdraws the realm’s approval, so installing it again approves the version installed then. admission in the response says what happened to it: revoked, none, kept (another copy is still installed) or failed.

name
required
string

Realm name

keepData
boolean

Keep the reference nodes the realm seeded and the documents it ingested; the response counts what stays

Realm removed

Media type*/*

The realm was removed

object
admission
required

What happened to the realm’s approval

string
Allowed values: revoked none kept failed off
data

What became of the nodes the realm seeded and the documents it ingested, counted per type and per source. Absent when removal touched no data

object
key
additional properties
any
name
required

The realm removed

string
status
required

Always removed

string
Allowed values: removed

Nothing installed answers to that name (code REALM_NOT_FOUND)

Media type*/*

A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly

object
code
required

Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own

string
detail

Extra context where there is some: a sentence, such as the fields a body may carry, or an object of machine fields in the server’s own words, such as api_approval_unapprovable’s reason (the declaration reader’s code, MALFORMED or FIELD_INVALID), field (where it points, [0].headers[1] or apis/spec.json#/paths/~1things/post) and rule (the sentence the reader states for it), or a refused Realm capture’s reason (SYMLINK, TOO_LARGE, …) and file (the path relative to the Realm root); never the caller’s or a Realm’s text; null otherwise

message
required

A plain-language explanation, written to be shown. Never carries an exception message

string

The realm is served from the appliance’s shared realms directory, which no one world owns; a realm a template, org or default-world manifest supplies is removed from this world (code REALM_CONFLICT)

Media type*/*

A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly

object
code
required

Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own

string
detail

Extra context where there is some: a sentence, such as the fields a body may carry, or an object of machine fields in the server’s own words, such as api_approval_unapprovable’s reason (the declaration reader’s code, MALFORMED or FIELD_INVALID), field (where it points, [0].headers[1] or apis/spec.json#/paths/~1things/post) and rule (the sentence the reader states for it), or a refused Realm capture’s reason (SYMLINK, TOO_LARGE, …) and file (the path relative to the Realm root); never the caller’s or a Realm’s text; null otherwise

message
required

A plain-language explanation, written to be shown. Never carries an exception message

string

Realm operation unavailable

Media type*/*

A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly

object
code
required

Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own

string
detail

Extra context where there is some: a sentence, such as the fields a body may carry, or an object of machine fields in the server’s own words, such as api_approval_unapprovable’s reason (the declaration reader’s code, MALFORMED or FIELD_INVALID), field (where it points, [0].headers[1] or apis/spec.json#/paths/~1things/post) and rule (the sentence the reader states for it), or a refused Realm capture’s reason (SYMLINK, TOO_LARGE, …) and file (the path relative to the Realm root); never the caller’s or a Realm’s text; null otherwise

message
required

A plain-language explanation, written to be shown. Never carries an exception message

string

Realm storage could not be written

Media type*/*

A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly

object
code
required

Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own

string
detail

Extra context where there is some: a sentence, such as the fields a body may carry, or an object of machine fields in the server’s own words, such as api_approval_unapprovable’s reason (the declaration reader’s code, MALFORMED or FIELD_INVALID), field (where it points, [0].headers[1] or apis/spec.json#/paths/~1things/post) and rule (the sentence the reader states for it), or a refused Realm capture’s reason (SYMLINK, TOO_LARGE, …) and file (the path relative to the Realm root); never the caller’s or a Realm’s text; null otherwise

message
required

A plain-language explanation, written to be shown. Never carries an exception message

string