API Reference - oleander

The oleander API covers two surfaces: lineage ingestion via the OpenLineage spec, and lake queries through the query router, which picks between DuckDB, Bloom, Polars, and Spark. All endpoints authenticate with a Bearer token.

Base URL

https://oleander.dev

Authentication

curl -H "Authorization: Bearer YOUR_API_KEY" https://oleander.dev/api/v1/events

Generate an API key from your oleander settings.

Endpoints

Lineage

Method	Endpoint	Description
`POST`	`/api/v1/lineage`	Submit an OpenLineage event
`GET`	`/api/v1/events`	Retrieve lineage events with filtering and pagination

Queries

Method	Endpoint	Description
`POST`	`/api/v1/query`	Run or submit a query. oleander picks the engine and machine size. Start here.
`POST`	`/api/v1/warehouse/query`	Legacy. Executes SQL on DuckDB, sized by the org default rather than by the query.
`POST`	`/api/v2/spark/query`	Run a SQL query on managed Spark, writing results to an Iceberg table
`POST`	`/api/v1/warehouse/polars`	Run Polars SQL or a Python script against your Iceberg lake

/api/v1/query is the endpoint the SDKs and MCP tools use. It parses the SQL, estimates the input, and routes to DuckDB, Polars, Bloom, or Spark, returning the decision in engine_decision. See Query routing. The engine-specific endpoints below it remain available when you need to pin one.

OpenLineage compatibility

oleander implements the OpenLineage specification. Any OpenLineage-compatible producer - Airflow, dbt, Spark, Flink - can send events directly to /api/v1/lineage without modification.

​Base URL

​Authentication

​Endpoints

​OpenLineage compatibility

Base URL

Authentication

Endpoints

OpenLineage compatibility