Skip to content
Embabel Worlds

Generate Cypher and an execution explanation for a question, without running it

POST
/api/v1/kg/studio/generate
curl --request POST \
  --url http://localhost:11044/api/v1/kg/studio/generate \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "question": "example" }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The natural-language question, in question. Cypher is written for it and validated against the caller’s schema, regenerating on failure, but never run; saved views are not consulted first as they are on the admin /admin/kg/generate

Media typeapplication/json

A natural-language question: the body of /ask, and of the studio’s /generate.

object
question
required

The question in plain language. Cypher is written for it and, on /ask, run scoped to the acting user.

string

Example generated

{
  "question": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The generated 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”

Not authenticated

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”

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