A concept is a unit of logic in a project that produces an output predicate. Four kinds are executable programs — Vadalog, SQL, Cypher, and Python — and two are configured rather than written: context concepts, which expose unstructured notes as a queryable window, and llm concepts, which call a language model from a prompt template. The Concepts API lets you create concepts, run them (individually or as a dependency chain), read their results, and track execution progress. All paths are relative to the base URL and require authentication. All responses use the standard envelope.

Save a concept

Create or update a concept. Saving a concept with an existing_name updates it in place; otherwise a new concept is created.

Example

List concepts

Return all concepts in a project, enriched with their parsed code and binds.
data is an array of concept objects (name, type, definition, binds, output predicate, description, group, and position).

Get one concept

Return the same enriched object as /list, for a single concept. Use it when you already know the name and do not want to pull the whole project.
A name that does not exist in the project returns 404.

Run a concept

Execute a concept and its dependency chain. The engine runs at most one job at a time per workspace; see Execution status to track progress.
run_mode values
  • single — reuse every populated dependency as-is; rebuild only what is strictly missing to answer for the target concept. Cheapest.
  • auto (default) — reuse dependencies that are provably fresh, rebuild the stale or unverifiable ones, and honour any frozen checkpoints.
  • all — rebuild everything reachable in the dependency chain and override checkpoints. Most expensive; use as an escape hatch.
run_mode replaces the older force_rerun boolean. For older clients, force_rerun: true maps to all and force_rerun: false maps to single; new integrations should send run_mode.

Example

On success, data contains the execution result. On a run error, status is "error" and data carries an errorCode and errorMessage:
For long-running jobs, prefer firing the run and then polling Execution status rather than blocking on the response. A WebSocket variant, /concepts/{ontology_id}/run-stream/{concept_name}, streams per-concept progress frames if you need live updates.

Freeze a concept

Freeze a concept so no run rebuilds it, or unfreeze it again. A frozen concept keeps whatever output it last produced: nothing re-derives it while it is reached as a dependency of something else, so the concepts below it are not rebuilt either. Running it directly still builds it — freezing says “do not rebuild this on the way to something else”, not “never build this”. Use it for a concept whose inputs are gone or unreliable, one expensive enough that its consumers should reuse the last result, or one holding a result that must not move while work continues around it.
This endpoint sets only the freeze flag — the definition, the populated flag and everything else are left alone. A freeze is honoured by run_mode: "auto" and overridden by run_mode: "all".
A freeze holds against the world moving underneath a concept, not against the concept itself changing. Editing the definition, or running with different params, breaks it: the stored table would otherwise be served in place of one it is not a substitute for.

Check freshness

Ask whether each concept’s stored output still reflects its sources — judged against the sources as they are right now, not against what was last recorded. It answers “would a run rebuild this?” without paying for the run.
data is a map keyed by concept name:
unknown is an honest answer, not a failure: the output matches what was recorded, but at least one source cannot be trusted to have noticed a change.Supplying params changes the question. Without it, each concept is judged under the arguments its own last run used — which describes the stored artifact. With it, each is judged under these arguments — which is what a run would decide. For a parametric concept only the second form is meaningful: rows built at one threshold are not an answer about another.
Unlike /list, this endpoint contacts your data sources — one batched metadata call per project, or per chain when concept_name is given. It writes nothing, so it is safe to call, but do not put it on a poll loop the way you would /list.
The two companion endpoints, POST /concepts/{ontology_id}/freshness/record and POST /concepts/{ontology_id}/freshness/invalidate, exist for one caller: a recipient of a filesystem share, whose run computes on its own compute but writes the owning project’s tables. They bracket such a write so the owner’s record does not describe rows a recipient overwrote. Ordinary integrations never call them — a normal run keeps its own record.

Fetch concept results

Read the persisted rows of an output predicate. This is the single endpoint for all reads: paging, ordering, free-text search, and per-column filtering are all optional and combine in one request. It reads already-materialized results and never recomputes — run the concept first.
output_predicate is a query parameter; everything else goes in the JSON body. Column filters Each entry is { "position": <0-based column index>, "operator": <operator>, "value": <string or array of strings> }. operator defaults to contains: Filters are AND-combined. To OR several values on one column, pass an array as value ("any of") rather than repeating the filter.

Example

/fetch used to be a GET with query-string parameters, alongside a separate POST /concepts/{ontology_id}/search for filtered reads. Both were replaced by this single POST. Move page, page_size, order_by, and params out of the query string and into the JSON body; output_predicate stays in the query string.

Query a concept with SQL

Run a single read-only SQL SELECT over one populated concept — for aggregates, GROUP BY, and joins against the concept’s own rows that /fetch cannot express. Reference the concept by name in FROM. A row cap is always enforced, and the concept must already exist and be populated.

Find similar concepts

Semantic search across every concept in every project you can access — used to find reuse candidates before authoring something new.
data is { "count": <n>, "matches": [ ... ] }.

Rename a concept

Rename a concept and propagate the new name to every dependent concept.

Reorder concepts

Set the display order of concepts in a project. Pass the concept names in the desired order; optionally restrict the reordering to a single group.

Execution status

When a concept runs, the platform persists a snapshot of the run (one per run, most recent 50 kept per project). These read-only endpoints report the state of the latest run — they do not start one.

Single project

The top-level data.status is the primary field: success, error, cancelled, and interrupted are terminal. Poll roughly every 1.5 s while running, and stop once the status is terminal or idle.

All projects (batch)

Takes no parameters — it reports on every project in your workspace.
data is a map keyed by project_id, where each value is the same snapshot as above. Only projects whose latest run is running, error, cancelled, or interrupted appear — a project absent from the map is idle (never run, or its last run succeeded).

Other operations