Concepts

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.

POST /concepts/{ontology_id}/save

Parameter	In	Required	Default	Description
`ontology_id`	path	yes	—	The ontology ID.
`definition`	body	conditional	—	The concept body: Vadalog rules, a SQL or Cypher query, Python logic, or an LLM prompt template (per `concept_type`). Omit it for `context` concepts, which have no executable body.
`concept_type`	body	no	`"logic"`	One of `logic` (Vadalog), `sql`, `cypher`, `python`, `context`, or `llm`. See Context and LLM concepts.
`concept_name`	body	conditional	—	Required for every type except `logic`, which takes its name from the output predicate.
`concept_config`	body	conditional	—	Configuration for `context` and `llm` concepts, ignored for the other types. Required for `context`. See Context and LLM concepts.
`output_predicate`	body	no	`""`	The predicate this concept outputs.
`description`	body	no	—	Human-readable description.
`binds`	body	no	—	Bind annotations linking input/output predicates to data sources.
`force_overwrite`	body	no	`false`	Overwrite a conflicting concept instead of returning `409`.

Example

curl -X POST "$BASE_URL/concepts/$PROJECT_ID/save" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": "@output(\"location\").\nlocation(L) <- company(_, L).",
    "concept_type": "logic"
  }'

{
  "status": "success",
  "message": "Concept saved",
  "data": { "id": "cpt_8f2a..." }
}

List concepts

Return all concepts in a project, enriched with their parsed code and binds.

GET /concepts/{ontology_id}/list

Parameter	In	Required	Default	Description
`ontology_id`	path	yes	—	The ontology ID.

curl "$BASE_URL/concepts/$PROJECT_ID/list" \
  -H "Authorization: Bearer $TOKEN"

data is an array of concept objects (name, type, definition, binds, output predicate, description, group, and position).

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.

POST /concepts/{ontology_id}/run/{concept_name}

Parameter	In	Required	Default	Description
`ontology_id`	path	yes	—	The ontology ID.
`concept_name`	path	yes	—	The target concept to run.
`params`	body	no	`{}`	Runtime parameter values referenced by the program.
`run_mode`	body	no	`"auto"`	How much of the dependency chain to rebuild: `single`, `auto`, or `all`. See below.
`persist_outputs`	body	no	`true`	Persist output predicates so they can be read with `/fetch`.
`compute`	body	no	—	Compute target.

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

curl -X POST "$BASE_URL/concepts/$PROJECT_ID/run/location" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "persist_outputs": true }'

On success, data contains the execution result. On a run error, status is "error" and data carries an errorCode and errorMessage:

{
  "status": "error",
  "message": "Evaluation failed",
  "data": { "errorCode": "VL0023", "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.

Fetch concept results

Read the persisted rows of an output predicate, with pagination.

GET /concepts/{ontology_id}/fetch

Parameter	In	Required	Default	Description
`ontology_id`	path	yes	—	The ontology ID.
`output_predicate`	query	yes	—	The predicate to read.
`params`	query	no	`{}`	JSON string of parameter values.
`page`	query	no	`1`	Page number.
`page_size`	query	no	`30`	Rows per page (max `1000`).
`order_by`	query	no	—	e.g. `0:asc,2:desc`.

curl "$BASE_URL/concepts/$PROJECT_ID/fetch?output_predicate=location&page=1&page_size=30" \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "Success",
  "data": {
    "rows": [ ["Mountain View, CA"], ["Redmond, WA"] ],
    "count": 2,
    "page": 1,
    "page_size": 30
  }
}

Search concept results

Filter the rows of an output predicate by a search term and/or per-column filters. Same pagination as /fetch.

POST /concepts/{ontology_id}/search

Parameter	In	Required	Default	Description
`ontology_id`	path	yes	—	The ontology ID.
`output_predicate`	query	yes	—	The predicate to search.
`search_term`	body	no	—	Free-text term matched across columns.
`column_filters`	body	no	—	Array of `{ "position": <col index>, "value": <string> }`.

curl -X POST "$BASE_URL/concepts/$PROJECT_ID/search?output_predicate=location" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "search_term": "CA", "column_filters": [{ "position": 0, "value": "Mountain" }] }'

The response shape matches /fetch.

Rename a concept

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

POST /concepts/{ontology_id}/rename

Parameter	In	Required	Default	Description
`ontology_id`	path	yes	—	The ontology ID.
`old_name`	body	yes	—	Current concept name.
`new_name`	body	yes	—	New concept name.

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.

POST /concepts/{ontology_id}/reorder

Parameter	In	Required	Default	Description
`ontology_id`	path	yes	—	The ontology ID.
`concept_names`	body	yes	—	Array of concept names in the desired order.
`group`	body	no	—	Restrict reordering to concepts in this group.

curl -X POST "$BASE_URL/concepts/$PROJECT_ID/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "concept_names": ["raw_data", "cleaned", "final_report"] }'

{
  "status": "success",
  "message": "Concepts reordered successfully",
  "data": null
}

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

GET /concepts/{ontology_id}/execution-status

Parameter	In	Required	Default	Description
`ontology_id`	path	yes	—	The ontology ID.

{
  "status": "success",
  "message": "Execution status",
  "data": {
    "execution_id": "f1c2...",
    "project_id": "proj_123",
    "target_concept": "final_report",
    "order": ["raw_data", "cleaned", "final_report"],
    "total": 3,
    "statuses": {
      "raw_data": { "status": "success" },
      "cleaned":  { "status": "running" }
    },
    "status": "running",
    "failure_reason": null,
    "started_at": "2026-06-19T10:00:00+00:00",
    "updated_at": "2026-06-19T10:00:04+00:00",
    "finished_at": null,
    "duration_ms": null
  }
}

The top-level data.status is the primary field:

Value	Meaning
`idle`	No run history (single-project endpoint only).
`running`	A run is in progress. The currently-executing concept is the key in `statuses` whose `status` is `running`.
`success`	The run completed successfully.
`error`	The run failed — see `failure_reason`.
`cancelled`	The run was cancelled.
`interrupted`	The connection dropped or the server restarted mid-run.

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.

GET /concepts/execution-statuses

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

Operation	Endpoint	Notes
Generate a description with the LLM	`POST /concepts/{ontology_id}/generate-description`	Body: `concept_name`. Returns `{ "description": "..." }`.
Read (or lazily generate) a description	`GET /concepts/{ontology_id}/description`	Query: `concept_name`.
Ask a question over predicate data	`POST /concepts/{ontology_id}/llm`	Body: `predicate_names`/`predicate_data`, `question`. Returns `{ "response": "..." }`.
Export results to CSV / download a file	`GET /concepts/{ontology_id}/download`	Query: `path`, `export_csv`, `concept_name`. Returns the raw file, not the envelope.
Delete concepts	`POST /concepts/{ontology_id}/cleanup`	Body: `concept_names` (omit to delete all).

Introduction

Get Started

Platform

Integrations

Examples

Vadalog Reference

Resources

Save a concept

Example

List concepts

Run a concept

Example

Fetch concept results

Search concept results

Rename a concept

Reorder concepts

Execution status

Single project

All projects (batch)

Other operations

​Save a concept

​Example

​List concepts

​Run a concept

​Example

​Fetch concept results

​Search concept results

​Rename a concept

​Reorder concepts

​Execution status

​Single project

​All projects (batch)

​Other operations

Save a concept

Example

List concepts

Run a concept

Example

Fetch concept results

Search concept results

Rename a concept

Reorder concepts

Execution status

Single project

All projects (batch)

Other operations