Lakehouse Platform API

Getting started

Every request is scoped to a tenant and gated by ReBAC read permissions: you can only query, browse, and search tables you can read. Interactive access authenticates via SSO at the edge (oauth2-proxy); service and integration callers present an Authorization: Bearer token and select their tenant with X-Tenant-Id. Errors follow RFC-7807 (problem+json): every failure carries title and detail.

How tenant scoping resolves: a browser SSO session is pinned to its own tenant and cannot spoof another via a header. A token call has no browser identity, so it is scoped by X-Tenant-Id (or by a <tenant>.lakehouse.vforce360.ai host). The test harness below exposes both paths — pick bearer token + tenant to exercise a real tenant.

Try it now — the public demo tenant

demo.lakehouse.vforce360.ai serves a real tenant, publicly readable and read-only — no credentials needed. Every read example on this page works against it as-is, and the test harness below targets it by default. Query it right now:

curl -X POST https://demo.lakehouse.vforce360.ai/api/v1/compute/sql \
  -H 'Content-Type: application/json' \
  -d '{ "sql": "SELECT continent, year, avg_life_exp FROM demo.gold.gapminder_by_continent ORDER BY year LIMIT 10" }'

curl -X POST https://demo.lakehouse.vforce360.ai/api/v1/search \
  -H 'Content-Type: application/json' \
  -d '{ "query": "configuration management", "mode": "keyword" }'

Tip: the demo tenant’s SQL catalog is demo (browse it with GET /catalog/tree); the search corpus is a separate document set. Your own tenant exposes its own catalogs.

Writes (PUT/PATCH/DELETE, event ingestion, admin) return 403 on the demo tenant — authenticate against a provisioned tenant to integration-test writes.

Authenticate a request (production & other tenants)

Present a platform token and name the tenant. This is the service/integration path — it works from the harness below (choose bearer token + tenant), from curl, or from any HTTP client:

curl -X POST https://lakehouse.vforce360.ai/api/v1/compute/sql \
  -H 'Authorization: Bearer <your-token>' \
  -H 'X-Tenant-Id: acme' \
  -H 'Content-Type: application/json' \
  -d '{ "sql": "SELECT * FROM main.gold.orders LIMIT 10" }'

Equivalently, drop X-Tenant-Id and target the tenant host directly: https://acme.lakehouse.vforce360.ai/api/v1/compute/sql. Reads are ReBAC-filtered to what the token’s identity may read.

Event ingestion (primary integration path)

Push CloudEvents 1.0 envelopes; the platform routes each event type to a bronze table and projects typed, queryable views from the payload. This is how VForce360, VForce Flow, and customer apps feed the lakehouse.

curl -X POST https://lakehouse.vforce360.ai/api/v1/events/ingest \
  -H 'Authorization: Bearer <your-token>' \
  -H 'X-Tenant-Id: acme' \
  -H 'Content-Type: application/json' \
  -d '{
    "specversion": "1.0",
    "id": "evt-0001",
    "source": "my-app",
    "type": "com.example.order.created",
    "time": "2026-07-15T12:00:00Z",
    "data": { "order_id": "o-42", "total": 129.5 }
  }'

Events of type com.example.order.created land in a table for that type; the projection glue shreds data into typed columns you can query with SQL immediately.

Query & compute

Run read-only SQL over your readable estate (fully-qualified catalog.schema.table names):

curl -X POST https://lakehouse.vforce360.ai/api/v1/compute/sql \
  -H 'Content-Type: application/json' \
  -d '{ "sql": "SELECT continent, year, avg_life_exp FROM demo.gold.gapminder_by_continent ORDER BY year LIMIT 10" }'

Large scans can use /compute/sql/distributed (Spark). Browse what you can read with GET /catalog/tree.

Search

Document search supports modes: default semantic (ranked by meaning) or "mode": "keyword" (pure lexical — every term must appear; works without the embedding model).

curl -X POST https://lakehouse.vforce360.ai/api/v1/search \
  -H 'Content-Type: application/json' \
  -d '{ "query": "phosphate rock exports", "mode": "keyword", "k": 10 }'

Mnemo

Natural language → governed SQL, grounded strictly in tables the caller can read. The generated SQL is returned (never executed server-side); run it through /compute/sql.

curl -X POST https://lakehouse.vforce360.ai/api/v1/ai/query \
  -H 'Content-Type: application/json' \
  -d '{ "question": "how many pages per document type?" }'

API reference & test harness

Generated from the live routing table — every endpoint the deployment serves is listed (… endpoints), and CI fails if the curated annotations drift from the code. Set the target, auth, and tenant once below; then click any row to fill path parameters, edit the body, and send the request against the live API.

Loading reference…