Ontologies

An ontology is the top-level container in Prometheux — it groups concepts, data sources, a schema, and compute configuration into a single workspace. The Ontologies API lets you create and load ontologies, copy or template them, move them between workspaces via export/import, and capture point-in-time snapshots. All paths are relative to the base URL and require authentication. All responses use the standard envelope.

On the wire the request/response payloads still use project-prefixed keys (project, project_id) for backward compatibility. These name the ontology container.

Save an ontology

Create or update an ontology. Sending an existing id updates the ontology in place; a new id (or a client-generated one) creates a new ontology.

POST /ontologies/save

Parameter	In	Required	Default	Description
`project`	body	yes	—	Ontology object (see fields below).
`project.id`	body	yes	—	Ontology identifier.
`project.name`	body	yes	—	Human-readable ontology name.
`project.description`	body	no	—	Optional ontology description.

Example

curl -X POST "$BASE_URL/ontologies/save" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project": {
      "id": "my-ontology-001",
      "name": "Supply Chain Analysis",
      "description": "Vadalog models for supplier risk."
    }
  }'

{
  "status": "success",
  "message": "Ontology Supply Chain Analysis saved successfully",
  "data": { "project_id": "my-ontology-001" }
}

List ontologies

Return all ontologies visible to the authenticated user, deduplicated by ontology ID. No parameters required.

GET /ontologies/list

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

data is an array of ontology objects (id, name, description, and associated metadata).

Load an ontology

Fetch full details for a single ontology by ID.

GET /ontologies/load

Parameter	In	Required	Default	Description
`project_id`	query	yes	—	The ontology ID to load.

curl "$BASE_URL/ontologies/load?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "Ontology loaded successfully",
  "data": {
    "id": "my-ontology-001",
    "name": "Supply Chain Analysis",
    "description": "Vadalog models for supplier risk."
  }
}

Copy an ontology

Duplicate an existing ontology. All concepts, data source binds, and the schema are copied; a new ontology ID is assigned.

POST /ontologies/copy

Parameter	In	Required	Default	Description
`project_id`	body	yes	—	ID of the source ontology to copy.
`new_project_name`	body	no	—	Name for the copy. Defaults to the source name with a suffix.
`compute`	body	no	`{}`	Compute configuration overrides for the copy (Databricks / Snowflake).

curl -X POST "$BASE_URL/ontologies/copy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'$PROJECT_ID'",
    "new_project_name": "Supply Chain Analysis (Copy)"
  }'

{
  "status": "success",
  "message": "Ontology copied successfully! New ontology ID: new-ontology-abc.",
  "data": { "new_project_id": "new-ontology-abc" }
}

Templates

Templates are pre-built ontologies available to all users from a shared marketplace. Use list-templates to browse them, then import-template to instantiate one as a new ontology in your workspace.

List templates

Return all available templates from the marketplace. No parameters required.

GET /ontologies/list-templates

curl "$BASE_URL/ontologies/list-templates" \
  -H "Authorization: Bearer $TOKEN"

data is an array of template objects (id, name, description, and metadata).

Import a template

Create a new ontology from a marketplace template. Data source connections are validated after import; any that cannot be resolved are reported in failed_datasources.

POST /ontologies/import-template

Parameter	In	Required	Default	Description
`template_id`	body	yes	—	ID of the template to import.
`new_project_name`	body	no	—	Name for the resulting ontology. Defaults to the template name.
`compute`	body	no	`{}`	Compute configuration overrides (Databricks / Snowflake).

curl -X POST "$BASE_URL/ontologies/import-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tmpl_supply_chain_01",
    "new_project_name": "My Supply Chain Ontology"
  }'

{
  "status": "success",
  "message": "Template imported successfully as ontology 'My Supply Chain Ontology'",
  "data": {
    "id": "onto_abc123",
    "name": "My Supply Chain Ontology"
  }
}

If any data sources declared in the template cannot be resolved in your workspace, the response includes a failed_datasources array listing which connectors need to be reconfigured before running concepts.

Export an ontology

Serialize a single ontology — its concepts (structure only, not cached output rows), data source binds, schema, and metadata — into a JSON payload.

To move an ontology to another account or workspace, export it as a file tree with export-tree instead. The app no longer imports this JSON payload, and import-ontology is deprecated.

POST /ontologies/export-ontology

Parameter	In	Required	Default	Description
`project_id`	body	yes	—	ID of the ontology to export.

curl -X POST "$BASE_URL/ontologies/export-ontology" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "'$PROJECT_ID'" }'

{
  "status": "success",
  "message": "Ontology 'my-ontology-001' exported successfully. Found 12 tables with 340 total rows. (Concept data and embedding tables excluded, concepts set to not populated)",
  "data": {
    "project_id": "my-ontology-001",
    "tables": { "concepts": ["..."], "datasources": ["..."] },
    "summary": {
      "total_tables": 12,
      "total_rows": 340
    }
  }
}

Concept execution output (cached predicate rows) and embedding tables are excluded from the export. All concepts are marked as not-populated so they must be re-run after import.

Import an ontology

Deprecated, and will be removed in a future release. Import an ontology as a file tree with plan-tree and apply-tree instead.

Restore an ontology from a payload previously produced by export-ontology. A new ontology ID is assigned; data source connections are validated after import and any that fail are reported in failed_datasources.

POST /ontologies/import-ontology

Parameter	In	Required	Default	Description
`export_data`	body	yes	—	The `data` object from an `export-ontology` response.
`force_new_id`	body	no	`false`	Assign a fresh ID even if the original ontology ID is available.
`compute`	body	no	`{}`	Compute configuration overrides.

curl -X POST "$BASE_URL/ontologies/import-ontology" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export_data": { "project_id": "my-ontology-001", "tables": { "..." } },
    "force_new_id": false
  }'

{
  "status": "success",
  "message": "Ontology imported successfully! New ontology ID: onto_xyz789. Created 12 tables, inserted 340 rows.",
  "data": {
    "new_project_id": "onto_xyz789",
    "summary": {
      "tables_created": 12,
      "rows_inserted": 340
    }
  }
}

Ontology as files

export-ontology and import-ontology above move an ontology as one opaque payload. The three endpoints here move it as a file tree instead — a manifest, one file per concept, the data source specs, the schema graph and the apps — which is what you want when the ontology lives in version control. This is the API behind the CLI’s px pull, px plan and px apply; if you are working from a terminal, use the CLI rather than these endpoints directly.

Export a tree

POST /ontologies/export-tree

Parameter	In	Required	Default	Description
`ontology_id`	body	yes	—	The ontology to export.
`slug`	body	no	—	Directory name for the tree. Defaults to a slug of the ontology name.
`format`	query	no	`json`	`json` for a list of files, `zip` for the tree as an archive.

curl -X POST "$BASE_URL/ontologies/export-tree?format=zip" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ontology_id": "'$PROJECT_ID'" }' \
  --output ontology.zip

With format=zip the response is the raw archive rather than the envelope.

A tree never carries credentials. Data sources are exported as specs — type, host, database, table — so a tree is safe to commit, and applying one to an account that lacks a named data source reports it rather than inventing it.

Plan a tree

Diffs a tree against what is live and writes nothing. Run this before applying, and show a user the result: it is the only point at which the consequences of an apply are visible in advance.

POST /ontologies/plan-tree

Accepts either JSON — {"files": [{"path": "...", "content": "..."}, …]} — or a multipart/form-data upload with a file field holding the tree as a zip.

curl -X POST "$BASE_URL/ontologies/plan-tree" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@ontology.zip"

For each ontology in the tree, data classifies every concept as create, update, delete or unchanged, lists the data source, app and schema changes, and — importantly — names the downstream concepts a changed definition forces to re-run. A one-line edit near the top of a chain can mean rebuilding most of the project, and this is where you find that out.

Apply a tree

Reconciles live state to the tree. Concepts are written dependencies-first, and an ontology the tree names but your account does not have is created.

POST /ontologies/apply-tree

Takes the same two encodings as /plan-tree, plus:

Parameter	In	Required	Default	Description
`prune`	body/form	no	`false`	Also delete concepts and apps that are absent from the tree.
`snapshot`	body/form	no	`true`	Snapshot each ontology before writing.

prune: true makes the tree authoritative — anything not in it is deleted, including concepts a colleague added through the UI since you pulled. Leave snapshot on: it is what makes a bad apply recoverable, via Restore a snapshot.

Export workspace

Deprecated, and will be removed in a future release. Export each ontology as a file tree with export-tree instead.

Export every ontology in the workspace — and all workspace-level tables — in a single payload. Equivalent to calling export-ontology for each ontology plus the workspace-level tables in one request. No parameters required.

POST /ontologies/export-workspace

curl -X POST "$BASE_URL/ontologies/export-workspace" \
  -H "Authorization: Bearer $TOKEN"

{
  "status": "success",
  "message": "Workspace tables exported successfully. Found 45 tables with 1200 total rows across 5 ontologies (5 successful, 0 failed). (Concept data, embedding, and user_configs tables excluded, concepts set to not populated)",
  "data": {
    "projects": { "...": "..." },
    "workspace_tables": { "...": "..." },
    "summary": {
      "total_tables": 45,
      "total_rows": 1200,
      "projects_found": 5,
      "projects_exported_successfully": 5,
      "projects_failed": 0
    }
  }
}

Import workspace

Deprecated, and will be removed in a future release. Import each ontology as a file tree with plan-tree and apply-tree instead.

Restore a full workspace from a payload produced by export-workspace. Each ontology is imported in turn; partial failures are tracked per-ontology in the summary.

POST /ontologies/import-workspace

Parameter	In	Required	Default	Description
`export_data`	body	yes	—	The `data` object from an `export-workspace` response.

curl -X POST "$BASE_URL/ontologies/import-workspace" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export_data": { "..." }
  }'

{
  "status": "success",
  "message": "Workspace tables imported successfully. Imported 5 ontologies (0 failed), created 45 tables, inserted 1200 rows.",
  "data": {
    "summary": {
      "projects_imported": 5,
      "projects_failed": 0,
      "tables_created": 45,
      "rows_inserted": 1200
    }
  }
}

Create from context

Create a brand-new ontology from free-text context and/or file attachments. The platform analyzes the input with the LLM to extract entities and relationships, generates an ontology name and description, and uses Vadalingo to translate the domain knowledge into Vadalog concepts. This endpoint is sent as multipart/form-data (form fields, not JSON) because it accepts file uploads.

POST /ontologies/create-from-context

Parameter	In	Required	Default	Description
`context`	form	conditional	`""`	Text describing the domain or task. Required if no files are attached.
`concept_names`	form	no	`"[]"`	JSON array (as a string) of existing concept names whose schemas should inform generation.
`files`	form	no	—	One or more file attachments. Supported: PDF, CSV, TXT/MD, and images (JPG, PNG, GIF, BMP, TIFF, WEBP — OCR’d via computer vision).

Provide at least one of context or files; supplying neither returns a 400.

curl -X POST "$BASE_URL/ontologies/create-from-context" \
  -H "Authorization: Bearer $TOKEN" \
  -F "context=Model suppliers, the parts they make, and which factories consume them." \
  -F "files=@/local/path/supply_chain.pdf"

{
  "status": "success",
  "message": "Ontology 'Supply Chain Model' created successfully from context, 0 table(s), and 1 file(s)",
  "data": {
    "id": "onto_new123",
    "name": "Supply Chain Model",
    "description": "...",
    "nodes": [ /* extracted entities */ ],
    "edges": [ /* extracted relationships */ ]
  }
}

Snapshots

Snapshots are point-in-time captures of an ontology’s full state — concepts, data source binds, and schema. They enable lightweight versioning without a full export/import cycle.

Restoring a snapshot overwrites the current ontology state. By default, a safety snapshot of the current state is automatically created before the restore proceeds. Set create_safety_snapshot: false to skip this.

Create a snapshot

POST /ontologies/snapshots/create

Parameter	In	Required	Default	Description
`project_id`	body	yes	—	ID of the ontology to snapshot.
`description`	body	no	—	Optional human-readable label for the snapshot.

curl -X POST "$BASE_URL/ontologies/snapshots/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'$PROJECT_ID'",
    "description": "Before schema refactor"
  }'

{
  "status": "success",
  "message": "Snapshot created successfully for ontology 'my-ontology-001'",
  "data": {
    "snapshot_id": "snap_a1b2c3",
    "project_id": "my-ontology-001",
    "description": "Before schema refactor",
    "created_at": "2026-06-25T09:00:00+00:00"
  }
}

List snapshots

Return snapshot metadata for an ontology. The heavy snapshot payload is omitted — use restore with a snapshot_id to apply one.

GET /ontologies/snapshots/list

Parameter	In	Required	Default	Description
`project_id`	query	yes	—	The ontology whose snapshots to list.

curl "$BASE_URL/ontologies/snapshots/list?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN"

data is an array of snapshot metadata objects (snapshot_id, description, created_at).

Restore a snapshot

POST /ontologies/snapshots/restore

Parameter	In	Required	Default	Description
`snapshot_id`	body	yes	—	ID of the snapshot to restore.
`project_id`	body	yes	—	ID of the ontology to overwrite.
`create_safety_snapshot`	body	no	`true`	Capture the current state before restoring.

curl -X POST "$BASE_URL/ontologies/snapshots/restore" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "snap_a1b2c3",
    "project_id": "'$PROJECT_ID'",
    "create_safety_snapshot": true
  }'

{
  "status": "success",
  "message": "Ontology 'my-ontology-001' restored from snapshot 'snap_a1b2c3'",
  "data": {
    "project_id": "my-ontology-001",
    "restored_from": "snap_a1b2c3",
    "safety_snapshot_id": "snap_safety_d4e5f6"
  }
}

Delete a snapshot

POST /ontologies/snapshots/delete

Parameter	In	Required	Default	Description
`snapshot_id`	body	yes	—	ID of the snapshot to delete.
`project_id`	body	yes	—	ID of the owning ontology.

curl -X POST "$BASE_URL/ontologies/snapshots/delete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "snap_a1b2c3",
    "project_id": "'$PROJECT_ID'"
  }'

{
  "status": "success",
  "message": "Snapshot 'snap_a1b2c3' deleted successfully",
  "data": null
}

Read a snapshot’s concepts

Return the concept definitions held by one snapshot, or by the live ontology. This is what a diff view reads on both sides — pass a snapshot ID for one side and current for the other.

GET /ontologies/snapshots/concepts

Parameter	In	Required	Default	Description
`ontology_id`	query	yes	—	The ontology the snapshot belongs to.
`source`	query	yes	—	A snapshot ID, or the literal `current` for live state.

curl -G "$BASE_URL/ontologies/snapshots/concepts" \
  --data-urlencode "ontology_id=$PROJECT_ID" \
  --data-urlencode "source=snap_a1b2c3" \
  -H "Authorization: Bearer $TOKEN"

Read-only, and available whether or not versioning is enabled for the ontology.

Other operations

Operation	Endpoint	Notes
Delete an ontology or all ontologies	`POST /ontologies/cleanup`	Body: `project` object with `id` (omit to delete all your ontologies). Shared/scoped users cannot delete ontologies.

Introduction

Get Started

Platform

Integrations

Examples

Vadalog Reference

Resources

Save an ontology

Example

List ontologies

Load an ontology

Copy an ontology

Templates

List templates

Import a template

Export an ontology

Import an ontology

Ontology as files

Export a tree

Plan a tree

Apply a tree

Export workspace

Import workspace

Create from context

Snapshots

Create a snapshot

List snapshots

Restore a snapshot

Delete a snapshot

Read a snapshot’s concepts

Other operations

​Save an ontology

​Example

​List ontologies

​Load an ontology

​Copy an ontology

​Templates

​List templates

​Import a template

​Export an ontology

​Import an ontology

​Ontology as files

​Export a tree

​Plan a tree

​Apply a tree

​Export workspace

​Import workspace

​Create from context

​Snapshots

​Create a snapshot

​List snapshots

​Restore a snapshot

​Delete a snapshot

​Read a snapshot’s concepts

​Other operations

Save an ontology

Example

List ontologies

Load an ontology

Copy an ontology

Templates

List templates

Import a template

Export an ontology

Import an ontology

Ontology as files

Export a tree

Plan a tree

Apply a tree

Export workspace

Import workspace

Create from context

Snapshots

Create a snapshot

List snapshots

Restore a snapshot

Delete a snapshot

Read a snapshot’s concepts

Other operations