---
title: Web API reference
description: The api.queria.io API for listing, reading and searching datasets
---

`https://api.queria.io/v1` returns the dataset list, a single dataset and search results as JSON. You can call it from other sites and apps, and from JavaScript in the browser (CORS is `*`).

```bash
curl https://api.queria.io/v1/datasets/queria/e_stat
```

## Authentication

Send an API token as `Authorization: Bearer <token>` to get the private datasets the token's owner can read, in addition to public datasets. Without a token, requests are anonymous and return public datasets only. To create a token, see [Authentication](/en/authentication).

- Cookies are not read. Even if you are signed in to queria.io, a request without a token is anonymous
- An invalid token returns `401` instead of falling back to anonymous access
- **Do not put an API token in the HTML or JavaScript of a public site.** Anyone who opens the page can read the token and use it to read your private datasets. Send requests with a token only from your own server or computer. To read private datasets from the browser, use a [browser token](#browser-tokens)

### Browser tokens

`POST /v1/token` takes an API token and returns a token that expires in one hour. Keep the API token on your own server and pass only this token to the browser. The browser sends it as `Authorization: Bearer <token>` to read the `GET` endpoints and data on data.queria.io.

```bash
curl https://api.queria.io/v1/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=qk_... \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token
```

```json
{
  "access_token": "eyJ...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

- Send the body as `application/x-www-form-urlencoded` (OAuth 2.0 Token Exchange, RFC 8693)
- The returned token reads the same datasets as the API token. `scope`, `audience` and `resource` to narrow the datasets are not supported (`400` with `invalid_target`)
- The token expires in one hour, or when the API token expires if that comes first. Request a new one on your server before `expires_in` seconds pass and pass it to the browser
- Only personal API tokens are accepted. Organization API tokens return `400` with `invalid_grant`
- The token shares the rate limit of the API token
- Errors use the OAuth shape (`{ "error": "invalid_grant", "error_description": "..." }`). `429` and `503` include a `Retry-After` header

## Rate limits

The limits are guidelines and may change.

| Caller | Limit |
| --- | --- |
| Anonymous | 60 requests per minute per IP address |
| With an API token | 600 requests per minute per token |

Over the limit, the API returns `429` with a `Retry-After` header.

## Endpoints

| Method and path | Returns |
| --- | --- |
| `GET /v1/datasets` | The dataset list |
| `GET /v1/datasets/{handle}/{name}` | One dataset |
| `GET /v1/datasets/{handle}/{name}/declaration` | The published declaration of the dataset (descriptions of tables and columns) |
| `GET /v1/search?q=` | Search across datasets, tables and columns |
| `GET /v1/openapi.json` | The OpenAPI specification |
| `POST /v1/token` | A token to pass to the browser ([Browser tokens](#browser-tokens)) |

Datasets are named by their fully qualified name (handle and name), such as `queria/e_stat`. Short names such as `e_stat` alone are not accepted.

### A dataset

`GET /v1/datasets/{handle}/{name}` returns the dataset object directly, without a wrapping field. Each item in `datasets` of the list and search responses has the same fields.

| Field | Content |
| --- | --- |
| `handle`, `name` | Owner and name of the dataset |
| `qualified_name` | Fully qualified name |
| `title`, `description`, `keywords` | Title, description and keywords |
| `catalog_url` | URL of the DuckLake catalog, for `ATTACH` in DuckDB |
| `versioned_catalog_url` | Catalog URL pinned to the current version |
| `page_url` | The dataset page on queria.io |
| `visibility` | Visibility (`public`, `private` or `premium`) |
| `licenses` | Licenses (`id`, `title`, `url`). Omitted when the dataset has no registered license |
| `updated_at`, `bytes` | Last update and size |
| `pro_required` | `true` only when a premium dataset is fetched anonymously or with a token that cannot read it. In that case, attaching `catalog_url` does not give access to the data |

`GET /v1/datasets/{handle}/{name}/declaration` returns the declaration JSON as is. For a dataset without a declaration, it returns `null`.

### List and search responses

`GET /v1/datasets` returns `datasets` (an array of datasets) and `next_cursor`. `GET /v1/search` returns the search terms in `query`, matching datasets in `datasets`, matching tables and columns in `entries`, and `next_cursor`.

Search accepts these parameters. `q` can be omitted when another filter is given.

| Parameter | Content |
| --- | --- |
| `q` | Search terms. Returns results that contain all space-separated terms |
| `type` | Restricts results to `dataset`, `table` or `column` |
| `column`, `entity` | Restricts to tables that have this column name or identifier. Repeatable (up to 8 each) |
| `geo` | `true` restricts to tables with a location column |
| `area` | Restricts to tables that cover this area code (6 or 5 digits) |
| `year` | Restricts to tables whose period includes this year |
| `theme` | Restricts to tables in this theme |
| `min_rows`, `max_rows` | Restricts to tables whose row count is in this range (both ends included) |
| `value` | Restricts to tables with a column holding a value that contains this text. Repeatable (up to 8) |

### Pagination

The list and search take `limit` (1 to 200, default 50). Pass `next_cursor` from the response as `cursor` in the next request. A `null` `next_cursor` means the last page. The content of a cursor may change, so pass the value you received without building it yourself. `offset` is not accepted.

```bash
curl "https://api.queria.io/v1/datasets?limit=50"
curl "https://api.queria.io/v1/datasets?limit=50&cursor=<value of next_cursor>"
```

## Errors

Except for `/v1/token`, errors come with a status code and a body of this form.

```json
{ "error": { "code": "not_found", "message": "Dataset not found" } }
```

| Status | Meaning |
| --- | --- |
| `400` | Invalid parameters (such as an unreadable `cursor`, a `limit` out of range, or `offset`) |
| `401` | Invalid API token |
| `404` | No such dataset or path |
| `405` | A method the path does not accept (`POST` is accepted only by `/v1/token`) |
| `429` | Rate limit reached |
| `500` | Server error |
| `503` | The API token could not be verified temporarily. Wait for the number of seconds in `Retry-After` and retry |

## Versioning

Fields may be added to `/v1` responses. Removing fields or changing their names or types happens in a new `/v2`. Ignore fields you do not know.
