> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> REST API for ingesting lineage events and querying the oleander lake.

The oleander API covers two surfaces: lineage ingestion via the OpenLineage spec, and lake queries through the [query router](/platform/query-routing/overview), which picks between DuckDB, Bloom, Polars, and Spark. All endpoints authenticate with a Bearer token.

## Base URL

```
https://oleander.dev
```

## Authentication

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" https://oleander.dev/api/v1/events
```

Generate an API key from your [oleander settings](https://oleander.dev/app/settings/api-keys).

## 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](/platform/compute/bloom), or Spark, returning the decision in `engine_decision`. See [Query routing](/platform/query-routing/overview). The engine-specific endpoints below it remain available when you need to pin one.

## OpenLineage compatibility

oleander implements the [OpenLineage](https://openlineage.io/) specification. Any OpenLineage-compatible producer - Airflow, dbt, Spark, Flink - can send events directly to `/api/v1/lineage` without modification.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.