REST API

The Prometheux platform exposes a REST API that lets you drive every part of the platform from your own application — create projects, connect data, define and run concepts, read results, build knowledge graphs, schedule runs, and more. This page covers the conventions shared by all endpoints. Read it once, then jump into the per-resource references in the API Reference section.

Looking for the low-level Vadalog engine API (/evaluate, /config-info/set)? That is a separate, lower-level interface — see Vadalog Engine API. The platform API documented here is what external tools should integrate against.

Base URL

All endpoints are versioned under /api/v1. On Prometheux Cloud, each workspace is addressed by organization and username:

https://api.prometheux.ai/jarvispy/{organization}/{username}/api/v1

Segment	Description
`{organization}`	Your organization identifier.
`{username}`	Your username.

For a self-hosted instance, the base URL is your host plus the API prefix:

https://<your-host>/api/v1

Throughout the API Reference, paths are written relative to the base URL — e.g. POST /ontologies/save means POST https://api.prometheux.ai/jarvispy/{org}/{user}/api/v1/ontologies/save.

Authentication

Every request must carry a bearer token:

Authorization: Bearer <token>

Tokens are JarvisPy API keys (JWTs). See Authentication for how to obtain, list, and revoke them.

Cross-origin requests (CORS)

The API sends Access-Control-Allow-Origin: * and allows all standard methods (GET, POST, PUT, PATCH, DELETE, OPTIONS) and the Authorization, Content-Type, and X-Supabase-Token headers. This means a browser-based single-page app served from any origin can call the API directly — no proxy is required to get past CORS.

CORS does not protect your token. A token placed in browser code ships to every visitor and grants full account access. For a public app, keep the token server-side behind a small proxy (or serverless function) that adds the Authorization header, and have the browser call your proxy. See Bring your own frontend.

Response envelope

Every JSON response uses the same envelope:

{
  "status": "success",   // "success", "error", or "conflict"
  "message": "Success",  // human-readable label
  "data": { }            // the payload — shape depends on the endpoint
}

Read your result from data. On errors, status is "error" (or "conflict"), message describes the problem, and data is null.

A few endpoints do not use this envelope: file downloads return the raw file, and streaming endpoints return NDJSON. These are called out explicitly on their pages.

Status codes

Code	`status`	Meaning
`200`	`success`	The request succeeded.
`400`	`error`	Bad request — malformed body or invalid parameters.
`401`	`error`	Missing, invalid, expired, or revoked token.
`403`	`error`	Authenticated but not allowed to perform this action.
`404`	`error`	The referenced resource does not exist.
`409`	`conflict`	The request conflicts with current state (e.g. a name already exists).
`422`	`error`	Well-formed request, but the entity could not be processed.
`500`	`error`	Server-side error during processing.

A typical error response:

{
  "status": "error",
  "message": "Project not found",
  "data": null
}

Pagination

Endpoints that return tabular data (concept results, table previews) are paginated with a consistent set of parameters:

Parameter	Type	Default	Description
`page`	integer	`1`	1-based page number.
`page_size`	integer	`30`	Rows per page (max `1000`).
`order_by`	string	—	Comma-separated `column_index:direction`, e.g. `0:asc,2:desc`.

Paginated responses include the page metadata alongside the rows:

{
  "status": "success",
  "message": "Success",
  "data": {
    "rows": [ /* ... */ ],
    "count": 1240,
    "page": 1,
    "page_size": 30
  }
}

Streaming responses

Some endpoints stream their output as NDJSON (newline-delimited JSON): the response body is a sequence of JSON objects, one per line, emitted as work progresses. Read the stream line by line and parse each line independently rather than waiting for the whole body. Endpoints that stream say so on their page.

Compute

Execution endpoints accept an optional compute object to target a specific backend (local engine, Databricks, or Snowflake). When omitted, your workspace default is used. Unless you manage multiple compute backends, you can leave it out.

API Reference

Resource	What it covers
Authentication	Obtain, list, and revoke API tokens
Ontologies	Create, load, list, export/import, snapshot ontologies
Ontology Sharing	Share ontologies as viewer/editor; manage inbox and outbox
Concepts	Define, run, reorder, and read results from concepts
Data Sources	Connect data sources, infer schema, upload and preview data
Schema	Save/load schema, set node/edge roles, import OWL
Knowledge Graph	Build graphs and run graph analytics over concept output
Vadalog	Analyze and evaluate Vadalog programs directly
Vadalingo	Translate NL, SQL, RDF, and OWL into Vadalog
Apps	Manage apps programmatically
Schedules	Automate concept runs on a cron or data-change trigger
Context Layer	Manage and semantically search the agent knowledge base
AI Agent	Streaming conversational agent that plans and runs workflows
Chat History	Browse, load, rename, and delete agent chat sessions
Alerts	Ingest monitoring webhooks and reprocess alerts
Compute	Check machine / Databricks compute availability

Introduction

Get Started

Platform

Integrations

Examples

Vadalog Reference

Resources

Base URL

Authentication

Cross-origin requests (CORS)

Response envelope

Status codes

Streaming responses

Compute

API Reference

​Base URL

​Authentication

​Cross-origin requests (CORS)

​Response envelope

​Status codes

​Pagination

​Streaming responses

​Compute

​API Reference

Base URL

Authentication

Cross-origin requests (CORS)

Response envelope

Status codes

Pagination

Streaming responses

Compute

API Reference