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

POST

/api/v1/admin/kg/generate

curl --request POST \
  --url http://localhost:11044/api/v1/admin/kg/generate \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "preferViews": true, "question": "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.

scope

string

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

Request Body^required

The question, in question, and preferViews (default true): a question a saved view answers comes back as that view’s invocation with view set, and no model is asked. The catalogue is skipped under scope or with preferViews: false, and Cypher is then generated and validated, never run

Media typeapplication/json

A question to write Cypher for, and whether a saved view that answers it may stand in.

object

preferViews

Consult the saved-view catalogue first (default true): a question a curated view already answers comes back as that view’s invocation, with view set. False generates regardless.

boolean

question

required

The natural-language question to write Cypher for.

string

Example ^generated

{
  "preferViews": true,
  "question": "example"
}

Responses

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

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

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

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