Invoke a named lens
const url = 'http://localhost:11044/api/v1/lenses/example/invoke?background=false';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"args":{"additionalProperty":"example"},"idempotencyKey":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'http://localhost:11044/api/v1/lenses/example/invoke?background=false' \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "args": { "additionalProperty": "example" }, "idempotencyKey": "example" }'Run an authored lens by id and return a redacted, typed result envelope. background=true returns a RUNNING envelope immediately; waitSeconds=N waits that long then hands back the RUNNING envelope instead of blocking. For those deferred modes the envelope’s executionId is a run handle: poll GET /lenses/runs/{runId} with it. A synchronous invocation returns the final result directly; its executionId is not pollable.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The authored lens id
Query Parameters
Section titled “Query Parameters”Run on a worker and return a RUNNING envelope immediately
Wait up to this many seconds for the run to settle, then return the envelope as it stands rather than blocking
Request Body
Section titled “Request Body”The lens’s arguments under args, keyed by its declared parameter names; an argument left out takes the parameter’s default, and a required parameter left with no value is refused with 400. Omitting the body, or args, runs the lens on its defaults. Any top-level field other than args and idempotencyKey is refused with 400 rather than ignored; idempotencyKey is accepted but does not deduplicate invocations here
The body of POST /lenses/{lensId}/invoke and POST /views/{name}/invoke: arguments and an optional idempotency key. Any other top-level field is refused with 400.
object
Arguments by the lens’s or view’s declared parameter name. A name it does not declare, or a required parameter left out, is refused with 400; an optional one left out takes its declared default
object
Accepted but not yet acted on: a repeated call with the same key runs again
Example generated
{ "args": { "additionalProperty": "example" }, "idempotencyKey": "example"}Responses
Section titled “Responses”Arguments do not match the lens’s declared parameters, or the body has a field other than args/idempotencyKey; a body that will not parse answers an ApiError
A request-level refusal from the headless surface. Carries only the reason; an execution that ran and failed answers 200 with the outcome in its envelope instead
object
Why the request was refused, written to be shown: the unknown lens, view or run, the argument at fault, or the field the body should not have
A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly
object
Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own
Extra context where there is some, such as the fields a body may carry; null otherwise
A plain-language explanation, written to be shown. Never carries an exception message
The body the servlet error dispatch answers for a status raised by an exception rather than written by the endpoint. Every failure except 404, which answers the not-found HTML page
object
The status’s standard reason phrase, such as Bad Request or Forbidden
The request path that failed
The HTTP status code, repeated from the status line
Example generated
{ "error": "example"}Not authenticated. The filter chain answers an ApiError; a principal that resolves to no user answers the refusal
A request-level refusal from the headless surface. Carries only the reason; an execution that ran and failed answers 200 with the outcome in its envelope instead
object
Why the request was refused, written to be shown: the unknown lens, view or run, the argument at fault, or the field the body should not have
A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly
object
Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own
Extra context where there is some, such as the fields a body may carry; null otherwise
A plain-language explanation, written to be shown. Never carries an exception message
The body the servlet error dispatch answers for a status raised by an exception rather than written by the endpoint. Every failure except 404, which answers the not-found HTML page
object
The status’s standard reason phrase, such as Bad Request or Forbidden
The request path that failed
The HTTP status code, repeated from the status line
Example generated
{ "error": "example"}No such lens
A request-level refusal from the headless surface. Carries only the reason; an execution that ran and failed answers 200 with the outcome in its envelope instead
object
Why the request was refused, written to be shown: the unknown lens, view or run, the argument at fault, or the field the body should not have
Example generated
{ "error": "example"}