Skip to content
Embabel Worlds

Revise existing Cypher per an instruction, without running it

POST
/api/v1/admin/kg/refine
curl --request POST \
  --url http://localhost:11044/api/v1/admin/kg/refine \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "cypher": "example", "instruction": "example" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “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.

scope
string

The ask scope to use, as GET /ask/scopes lists them. Omitted means the whole graph.

Request Bodyrequired

Section titled “Request Bodyrequired”

The current, possibly hand-edited Cypher in cypher and what to change about it in instruction; the revision is written within scope when one is given, validated but never run, and the response’s question echoes the instruction

Media typeapplication/json

Cypher to revise and what to change about it — the body of /refine.

object
cypher
required

The current Cypher, possibly hand-edited, that the revision starts from.

string
instruction
required

What to change, in plain language. Echoed back as the response’s question.

string

Example generated

{
  "cypher": "example",
  "instruction": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The revised cypher, its verdict, and what the engine will do

Media typeapplication/json

Generated cypher and what the engine will do with it, without running it.

object
attempts
required

How many generate-validate rounds it took.

integer format: int32
cypher
required

The Cypher written for the question — or, when view is set, that view’s invocation. Nothing has been executed.

string
durationMs
required

Wall-clock milliseconds the call took, view matching or generation plus the explanation.

integer format: int64
explain
required

What the engine will do when this runs. Best-effort; never fails the call.

string
question
required

What the user typed, echoed back: the question, or for /refine the instruction.

string
valid
required

Whether the final attempt passed the strict preflight.

boolean
view

Present when a saved view already answers the question: cypher is then that view’s invocation, attempts is 0, and nothing was generated. Absent when the Cypher was written for this question.

object
args
required

The arguments the selector bound from the question, by parameter name.

object
key
additional properties
name
required

The saved view’s name, as GET /views lists it.

string
reason

The selector’s one line on why this view.

string
violations
required

What the strict preflight objected to in the final attempt, one entry per defect.

Array<string>

Example generated

{
  "attempts": 1,
  "cypher": "example",
  "durationMs": 1,
  "explain": "example",
  "question": "example",
  "valid": true,
  "view": {
    "args": {
      "additionalProperty": "example"
    },
    "name": "example",
    "reason": "example"
  },
  "violations": [
    "example"
  ]
}

401

Section titled “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

Section titled “403”

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

500

Section titled “500”

Refinement failed

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