Projects - Prometheux

A project is the top-level container in Prometheux — it groups concepts, data sources, an ontology, and compute configuration into a single workspace. The Projects API lets you create and load projects, 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. Where scope is accepted, valid values are user (default) and organization.

Save a project

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

POST /projects/save

Parameter	In	Required	Default	Description
`project`	body	yes	—	Project object (see fields below).
`project.id`	body	yes	—	Project identifier.
`project.name`	body	yes	—	Human-readable project name.
`project.scope`	body	no	`"user"`	Scope for the project.
`project.description`	body	no	—	Optional project description.

Example

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

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

List projects

Return all projects visible to the authenticated user across one or more scopes. Results from multiple scopes are merged and deduplicated by project ID.

GET /projects/list

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

The organization scope is temporarily disabled — passing it is silently ignored and only user-scoped projects are returned.

curl "$BASE_URL/projects/list?scopes=user" \
  -H "Authorization: Bearer $TOKEN"

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

Load a project

Fetch full details for a single project by ID.

GET /projects/load

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

curl "$BASE_URL/projects/load?project_id=$PROJECT_ID&scope=user" \
  -H "Authorization: Bearer $TOKEN"

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

Copy a project

Duplicate an existing project into the same or a different scope. All concepts, data source binds, and ontology are copied; a new project ID is assigned.

POST /projects/copy

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

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

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

Templates

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

List templates

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

GET /projects/list-templates

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

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

Import a template

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

POST /projects/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 project. Defaults to the template name.
`project_scope`	body	no	`"user"`	Scope for the new project.
`compute`	body	no	`{}`	Compute configuration overrides (Databricks / Snowflake).

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

{
  "status": "success",
  "message": "Template imported successfully as project 'My Supply Chain Project'",
  "data": {
    "id": "proj_abc123",
    "name": "My Supply Chain Project",
    "scope": "user"
  }
}

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 a project

Serialize a single project — its concepts (structure only, not cached output rows), data source binds, ontology, and metadata — into a portable JSON payload. Use import-project to restore it.

POST /projects/export-project

Parameter	In	Required	Default	Description
`project_id`	body	yes	—	ID of the project to export.
`scope`	body	no	`"user"`	Scope of the project.

curl -X POST "$BASE_URL/projects/export-project" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "'$PROJECT_ID'", "scope": "user" }'

{
  "status": "success",
  "message": "Project 'my-project-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-project-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 a project

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

POST /projects/import-project

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

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

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

Export workspace

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

POST /projects/export-workspace

Parameter	In	Required	Default	Description
`scope`	body	no	`"user"`	Scope to export.

curl -X POST "$BASE_URL/projects/export-workspace" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "user" }'

{
  "status": "success",
  "message": "Workspace tables exported successfully. Found 45 tables with 1200 total rows across 5 projects (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

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

POST /projects/import-workspace

Parameter	In	Required	Default	Description
`export_data`	body	yes	—	The `data` object from an `export-workspace` response.
`scope`	body	no	`"user"`	Scope for the imported workspace.

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

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

Snapshots

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

Restoring a snapshot overwrites the current project 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 /projects/snapshots/create

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

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

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

List snapshots

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

GET /projects/snapshots/list

Parameter	In	Required	Default	Description
`project_id`	query	yes	—	The project whose snapshots to list.
`scope`	query	no	`"user"`	Scope of the project.

curl "$BASE_URL/projects/snapshots/list?project_id=$PROJECT_ID&scope=user" \
  -H "Authorization: Bearer $TOKEN"

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

Restore a snapshot

POST /projects/snapshots/restore

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

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

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

Delete a snapshot

POST /projects/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 project.
`scope`	body	no	`"user"`	Scope of the project.

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

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

Other operations

Operation	Endpoint	Notes
Delete a project or all projects	`POST /projects/cleanup`	Body: `project` object with `id` (omit to delete all user projects) and `scope`. Shared/scoped users cannot delete projects.

​Save a project

​Example

​List projects

​Load a project

​Copy a project

​Templates

​List templates

​Import a template

​Export a project

​Import a project

​Export workspace

​Import workspace

​Snapshots

​Create a snapshot

​List snapshots

​Restore a snapshot

​Delete a snapshot

​Other operations

Save a project

Example

List projects

Load a project

Copy a project

Templates

List templates

Import a template

Export a project

Import a project

Export workspace

Import workspace

Snapshots

Create a snapshot

List snapshots

Restore a snapshot

Delete a snapshot

Other operations