Concepts - Prometheux

A concept is a unit of logic in a project — a Vadalog, SQL, or Python program that produces an output predicate. 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/{project_id}/save

Parameter	In	Required	Default	Description
`project_id`	path	yes	—	The project ID.
`definition`	body	yes	—	The concept body: Vadalog rules, a SQL query, or Python logic (per `concept_type`).
`concept_type`	body	no	`"logic"`	One of `logic` (Vadalog), `sql`, `cypher`, or `python`.
`concept_name`	body	conditional	—	Required for `sql`, `cypher`, and `python` 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.
`scope`	body	no	`"user"`	Scope of the concept.
`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",
    "scope": "user"
  }'

{
  "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/{project_id}/list

Parameter	In	Required	Default	Description
`project_id`	path	yes	—	The project ID.
`scope`	query	no	`"user"`	Scope of the project.

curl "$BASE_URL/concepts/$PROJECT_ID/list?scope=user" \
  -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/{project_id}/run/{concept_name}

Parameter	In	Required	Default	Description
`project_id`	path	yes	—	The project ID.
`concept_name`	path	yes	—	The target concept to run.
`scope`	body	no	`"user"`	Scope of the project.
`params`	body	no	`{}`	Runtime parameter values referenced by the program.
`force_rerun`	body	no	`true`	Re-run even if cached results exist.
`persist_outputs`	body	no	`true`	Persist output predicates so they can be read with `/fetch`.
`compute`	body	no	—	Compute target.

Example

curl -X POST "$BASE_URL/concepts/$PROJECT_ID/run/location" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "user", "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/{project_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/{project_id}/fetch

Parameter	In	Required	Default	Description
`project_id`	path	yes	—	The project 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`.
`project_scope`	query	no	`"user"`	Scope of the project.

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/{project_id}/search

Parameter	In	Required	Default	Description
`project_id`	path	yes	—	The project 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> }`.
`project_scope`	query	no	`"user"`	Scope of the project.

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/{project_id}/rename

Parameter	In	Required	Default	Description
`project_id`	path	yes	—	The project ID.
`old_name`	body	yes	—	Current concept name.
`new_name`	body	yes	—	New concept name.
`scope`	body	no	`"user"`	Scope of the project.

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/{project_id}/execution-status

Parameter	In	Required	Default	Description
`project_id`	path	yes	—	The project ID.
`scope`	query	no	`"user"`	Scope of the project.

{
  "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)

GET /concepts/execution-statuses

Parameter	In	Required	Default	Description
`scopes`	query	no	`"user"`	Comma-separated scopes, e.g. `user,organization`.

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/{project_id}/generate-description`	Body: `concept_name`, `scope`. Returns `{ "description": "..." }`.
Read (or lazily generate) a description	`GET /concepts/{project_id}/description`	Query: `concept_name`, `scope`.
Ask a question over predicate data	`POST /concepts/{project_id}/llm`	Body: `predicate_names`/`predicate_data`, `question`. Returns `{ "response": "..." }`.
Export results to CSV / download a file	`GET /concepts/{project_id}/download`	Query: `path`, `export_csv`, `concept_name`. Returns the raw file, not the envelope.
Delete concepts	`POST /concepts/{project_id}/cleanup`	Body: `concept_names` (omit to delete all), `scope`.

​Save a concept

​Example

​List concepts

​Run a concept

​Example

​Fetch concept results

​Search concept results

​Rename a concept

​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

Execution status

Single project

All projects (batch)

Other operations