> ## 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), 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/bloom), or Spark, returning the decision in `engine_decision`. See [Query routing](/platform/query-routing). 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.