# SQL REST API

The SQL REST API exposes three endpoints: one to run a bounded query, one to export an unbounded result, and one to introspect the queryable surface.

| Method | Path | Purpose |
| --- | --- | --- |
| POST | [`/sql/v1/query`](https://dev.nominal.io/sql-reference/rest-api/query.md) | Run a query and get the result back |
| POST | [`/sql/v1/query/export`](https://dev.nominal.io/sql-reference/rest-api/export.md) | Run an unbounded query and get a download URL for the result |
| GET | [`/sql/v1/catalog`](https://dev.nominal.io/sql-reference/rest-api/catalog.md) | List queryable tables, columns, and allowed functions |

Each path hangs off your deployment’s REST API URL, the same base the rest of the platform REST API uses. Copy it from the **API keys** page in Settings.

## Authentication

All three endpoints take a bearer token in the `Authorization` header. Use an organization API key:

```text
Authorization: Bearer <your-api-key>
```

See [API keys setup](https://dev.nominal.io/quickstart/api-keys-setup.md) for how to obtain a key. The config file/command line set-up is not required, just obtaining an API key.

## What you can query

Queries are validated before execution with key rules listed below:

- **Read-only, single statement.** One `SELECT` per request. Multi-statement requests are rejected, as is anything that would change schema (`CREATE`, `ALTER`, `DROP`) or data (`INSERT`, `UPDATE`, `DELETE`).
- **Only table, columns, and functions in the catalog are permitted.** The catalog can be viewed from the console or call [`GET /sql/v1/catalog`](https://dev.nominal.io/sql-reference/rest-api/catalog.md) for the current list.
- **Telemetry tables must be scoped by `dataset_rid`.** The `points_double`, `points_int`, `points_string`, `points_struct`, `logs`, and `channels` tables each require a `dataset_rid` predicate, or a join on `dataset_rid` to a metadata table. The metadata tables (`assets`, `runs`, `run_assets`, `datasets`, `events`, and `event_assets`) have no such requirement.

Joins work across any number of metadata tables, and between metadata and telemetry tables. Telemetry tables combine with each other through `IN` subqueries and `PIVOT`. See [Writing queries](https://dev.nominal.io/sql-guides/writing-queries.md#joins).

Every request needs view access to the workspace named in `workspace_rid`, and reads only that workspace’s data. Telemetry queries also need read access to each dataset they name.

## Permitted operations

- [Query](https://dev.nominal.io/sql-reference/rest-api/query.md)
- [Export](https://dev.nominal.io/sql-reference/rest-api/export.md)
- [Catalog](https://dev.nominal.io/sql-reference/rest-api/catalog.md)
- [Error handling](https://dev.nominal.io/sql-reference/rest-api/errors.md)

## Next steps

- [Query](https://dev.nominal.io/sql-reference/rest-api/query.md): run a bounded query.
- [Error handling](https://dev.nominal.io/sql-reference/rest-api/errors.md): error codes and response shape.
- [SQL REST API quickstart](https://dev.nominal.io/sql-guides/quickstart.md): run your first query.
- [Writing queries](https://dev.nominal.io/sql-guides/writing-queries.md): query patterns and examples.
- [Function reference](https://dev.nominal.io/sql-reference/schema/function-reference.md): available functions.