Freeze an annotation plan: validate and select matching nodes, writing nothing

POST

/api/v1/admin/kg/annotations/dry-run

curl --request POST \
  --url http://localhost:11044/api/v1/admin/kg/annotations/dry-run \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "params": { "additionalProperty": "example" }, "statement": "example" }'

• Your world, at the port the installer gives it

Authorizations

• apiKeyAuth
• basicAuth

Parameters

Query Parameters

username

string

Optional, and never needed: the call always acts as the signed-in principal. Naming the principal changes nothing; naming anyone else is refused with 403.

Request Body^required

The annotation statement to validate and select with, writing nothing: a read prefix, WITH DISTINCT <target> ORDER BY … LIMIT n, then exactly one SET <target>.<property> = <value> on a property the world declares annotatable. params binds the statement’s $name parameters and may be omitted. 409 when the statement falls outside that grammar

Media typeapplication/json

An annotation statement to freeze into a plan, writing nothing; the body of POST /admin/kg/annotations/dry-run

object

params

required

Values for the statement’s $parameters, by name, resolved when the plan freezes; empty when absent

object

key

additional properties

statement

required

One Cypher annotation statement: a read prefix (MATCH, OPTIONAL MATCH, WITH), then WITH DISTINCT [, AS ] ORDER BY … LIMIT n, then SET . = <literal | $parameter | alias>. The property must be one the world’s annotatable declarations allow on the target’s label

string

Example ^generated

{
  "params": {
    "additionalProperty": "example"
  },
  "statement": "example"
}

Responses

200

The frozen plan and the diffs it would write

Media typeapplication/json

A frozen annotation plan: what WOULD be written, with nothing written yet.

object

diffs

required

One proposed change per selected node, as it would be written.

Array<object>

One proposed property change, as it would be written.

object

after

The value the write would set. Null means the write clears the property.

before

The value before the write, or null when the property is new.

identity

The target’s identity property value. Type depends on the label’s identity property.

property

required

The property the write sets; the plan’s allowlisted property, the same on every diff.

string

expiresAt

required

When the frozen plan lapses, ISO-8601. Echo it back verbatim.

string

label

required

The node label the statement targets; annotation writes must be allowed on it in the world’s annotatable declarations.

string

planId

required

Pass this to /apply or /undo. Single-use and time-limited.

string

property

required

The allowlisted property the statement SETs on each selected node.

string

selected

required

How many nodes the statement selected.

integer format: int32

Example ^generated

{
  "diffs": [
    {
      "after": "example",
      "before": "example",
      "identity": "example",
      "property": "example"
    }
  ],
  "expiresAt": "example",
  "label": "example",
  "planId": "example",
  "property": "example",
  "selected": 1
}

401

No authenticated principal

Media typeapplication/json

A refusal carrying only a human-readable reason.

object

error

required

What went wrong, in the terms the caller can act on.

string

Example ^generated

{
  "error": "example"
}

403

Annotation writes disabled by feature flag, or username names someone other than the signed-in principal

Media typeapplication/json

A refusal carrying only a human-readable reason.

object

error

required

What went wrong, in the terms the caller can act on.

string

Example ^generated

{
  "error": "example"
}

409

Plan rejected, expired, or frozen for another user

Media typeapplication/json

A refusal carrying only a human-readable reason.

object

error

required

What went wrong, in the terms the caller can act on.

string

Example ^generated

{
  "error": "example"
}