OSL API reference

This section defines the public contracts of the OSL engine. What it states is what any client can assume, and what any OSL-conformant engine MUST implement exactly.

For the full object semantics (which primitives exist, their fields) see the specification. Here: how it’s called and what it returns.

Surfaces

OSL v1 exposes four separate surfaces:

Surface	Who consumes it	Shape
REST	BI tools, apps, dashboards, scripts	HTTP/JSON · optional Arrow IPC for /query bulk
MCP tools	AI agents (Claude, GPT, Copilot, custom)	tool definitions over the MCP protocol
CLI	Developers, CI pipelines	the osl binary
OpenLineage events	Marquez, DataHub, observability	webhook / kafka emitter

One consumption endpoint

Everything you read goes through a single endpoint — /osl/query. Structured analytics, metrics, governed vector retrieval, entity records and graph traversal are all forms of the OSL-SQL surface.

The five endpoints are now one

The former /osl/retrieve, /osl/joint/resolve and /osl/traverse endpoints have been removed — each is a form of /osl/query (RETRIEVE(...), a Joint record select, TRAVERSE(...)). This is what makes “OSL is the sole consumption layer” literally true.

Endpoint	Purpose
POST /osl/query	The consumption surface — OSL-SQL (osql), raw sql, or MetricFlow
POST /osl/sample	Governed content preview — ACL + server-side redaction (not an algebra query)
GET /osl/domain-map	The unified domain graph (Entities, metrics, candidates)
GET /osl/schema	The compiled manifest (cacheable)
GET /osl/schema/resolve	Lexicon resolver — business term → canonical FQN
POST /osl/suggest · POST /osl/validate · POST /osl/objects	Assisted authoring (draft → validate → publish)
GET /osl/candidates	Discovery — candidate (not-yet-adopted) entities
GET /osl/conformance	Declared conformance levels
GET /health	Unauthenticated health check

The query surface (OSL-SQL)The single endpoint and its five forms.

Retrieval (RETRIEVE)Governed vector retrieval as a relation source.

AuthenticationAttested delegation chains, scopes, rate limits.

Errors & status codesThe error envelope and the E-code bands.

MCP tools

OSL ships MCP tools any agent can invoke: metric_lookup, doc_search, entity_get, schema_describe, joint_explore. They call the same governed resolvers that back the OSL-SQL forms — doc_search wraps RETRIEVE, entity_get wraps the Joint record form — so an agent gets the same enforcement as any other consumer.

API versioning

/osl/ is the v1 root. A breaking v2 would live at /osl/v2/ while /osl/ keeps serving the v1 contract for at least two consecutive minor versions. Endpoints MAY add optional response fields within v1.x; clients MUST ignore unrecognized fields.