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

# API overview

> Base URLs, authentication, formats and conventions.

> [!TIP]
>
> The [client libraries](https://docs.bloklake.com/clients.md) (TypeScript, Python, Rust) wrap this API: typed queries,
> pagination, retries, and Arrow decoded into JSON rows.

## Base URLs

Each chain has a base URL. Every endpoint below is relative to it.

| Chain | Base URL | Alternative |
| - | - | - |
| Ethereum | `https://api.bloklake.com/v1/chains/eth` | `https://eth.api.bloklake.com` |
| Robinhood Chain | `https://api.bloklake.com/v1/chains/rh` | `https://rh.api.bloklake.com` |

## Endpoints

| Method and path | Purpose | Key | Billed |
| - | - | - | - |
| [`POST /query`](https://docs.bloklake.com/api-reference/query) | Run a query, get Arrow IPC streams | yes | yes |
| [`POST /query/json`](https://docs.bloklake.com/api-reference/query-json) | Run a query, get JSON | yes | yes |
| [`POST /v1/sets`](https://docs.bloklake.com/api-reference/create-set) | Create (or find) a set of addresses or topics | yes | 10 KB |
| [`GET /v1/sets/{id}`](https://docs.bloklake.com/api-reference/get-set) | A set's metadata | yes | 10 KB |
| [`DELETE /v1/sets/{id}`](https://docs.bloklake.com/api-reference/delete-set) | Delete a set | yes | 10 KB |
| [`POST /v1/queries`](https://docs.bloklake.com/api-reference/create-query) | Register a prepared query | yes | 10 KB |
| [`GET /status`](https://docs.bloklake.com/api-reference/status) | Chain head, finalized block, block range | no | free |
| [`GET /v1/schema`](https://docs.bloklake.com/api-reference/schema) | Every field and whether this chain has it | no | free |
| [`GET /v1/account`](https://docs.bloklake.com/api-reference/account) | Your key's plan, limits and balance | yes | free |
| `GET /healthz` | Liveness: `200 ok` | no | free |

## Authentication

Send your API key in the `Authorization` header:

```http theme={null}
Authorization: Bearer bl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

`x-api-key` and `X-BL-Api-Key` headers are accepted too. Keys are created in the
[dashboard](https://dashboard.bloklake.com); see [API keys](https://docs.bloklake.com/account/api-keys.md).

## Requests

* Request bodies are JSON (`content-type: application/json`), up to 8 MiB (about 5.5 MiB
  for `POST /v1/sets`).
* Unknown keys anywhere in a body are rejected with `400`, never ignored.
* Hex values are `0x`-prefixed and case-insensitive.
* HTTP/1.1 and HTTP/2 are supported. Responses are not compressed.
* The API sends no CORS headers: call it from servers, not browsers.

## Responses

* `POST /query`: `application/vnd.apache.arrow.stream`. See [Reading Arrow](https://docs.bloklake.com/responses/reading-arrow.md).
* Everything else: `application/json`.
* Errors: a non-`200` status and `{"error": {"code": "…", "message": "…"}}`. See
  [Errors](https://docs.bloklake.com/api-reference/errors.md).

## Headers on every response

| Header | Meaning |
| - | - |
| `X-Request-Id` | your `X-Request-Id` (up to 128 printable characters) or a generated one; quote it to support |
| `X-RateLimit-Limit` | your key's requests per second (admitted requests) |
| `X-RateLimit-Remaining` | requests left in the current second |
| `Retry-After` | on `429` and `503`: seconds to wait |


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