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 anexisting_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.
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
data contains the execution result. On a run error, status is
"error" and data carries an errorCode and errorMessage:
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.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.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 SQLSELECT 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
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).

