Skip to content
Embabel Worlds

Open a saved lens and return how many entities it focused

POST
/api/v1/lenses/{id}/run
curl --request POST \
  --url http://localhost:11044/api/v1/lenses/example/run \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "args": { "additionalProperty": "example" } }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Lens id, resolved in order: the caller’s saved lens (the slug of its name, as PUT /lenses returns it), a world or realm lens, then a saved view by name; 404 when none matches

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.

Request Body

Section titled “Request Body”

Optional. args supplies values for the lens’s declared parameters, overlaid on their declared defaults; omit the body or args to run on the defaults alone. A required parameter left unset fails the request

Media typeapplication/json

Optional body for opening a saved lens — POST /lenses/{id}/run, /present, /views and /views/{view} — carrying values for its declared parameters

object
args
required

Parameter values keyed by parameter name. They override the declared defaults; a required parameter with neither a value nor a default fails the open. Empty or absent uses the defaults.

object
key
additional properties

Example generated

{
  "args": {
    "additionalProperty": "example"
  }
}

Responses

Section titled “Responses”

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

404

Section titled “404”

Lens not found

Media typeapplication/json

A refusal from the lens authoring surface. Carries only the reason

object
error
required

Why the request was refused, written to be shown. Names the lens or view where the refusal is about one

string

Example generated

{
  "error": "example"
}