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

# Introduction

> The v1 API in one page: base URL, keys, the verbs, headers and errors.

```
https://test.polltheroom.com/api/v1
```

Every request carries `Authorization: Bearer ptr_…`, a key made under **Settings › API**. JSON in, JSON out. The pages in this tab are generated from the API's own OpenAPI document, so a field here is a field the server accepts, and the playground on each page runs against your key.

## The verbs

Every verb is a page in this tab's sidebar, generated from the API's OpenAPI document, with its route, its scope in the description, the fields it takes and what it answers. The playground on each page runs against your own key.

## Headers that help

| Header                                                            | Direction             | Meaning                                                                                               |
| ----------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` | reply                 | The hourly window: the limit, what is left, seconds until it opens again.                             |
| `Retry-After`                                                     | reply, on 429         | Seconds to wait.                                                                                      |
| `Idempotency-Key`                                                 | request, POST and PUT | A retry with the same key within a day gets the same answer back, marked `Idempotent-Replayed: true`. |
| `Accept: image/png`                                               | request, screenshot   | The bytes instead of JSON with a data URL.                                                            |

## Every write answers with

```json theme={null}
{ "ok": true, "revision": "2026-09-07T13:26:56.407Z", "ready": true, "problems": [] }
```

`revision` is the deck's last save. Send it with the next write and the write lands only if nobody changed the deck since; otherwise `409`. `ready` and `problems` are the [readiness check](/concepts/readiness), run for you.

## Errors

```json theme={null}
{ "error": "Bad body.", "fix": "step.overlays.0.poll.mcStyle: Arc (pairs) needs multiSelect" }
```

`error` says what went wrong. `fix`, when we can tell, says what to do, and names the field when the body did not fit. The status codes are listed under [Authentication and limits](/authentication#errors).

## Also machine-readable

* [`/openapi.json`](https://test.polltheroom.com/openapi.json), the document these pages are built from.
* [`/llms.txt`](https://test.polltheroom.com/llms.txt) and [`/llms-full.txt`](https://test.polltheroom.com/llms-full.txt), the reference an agent reads first.
* [`/api/mcp`](/mcp), the same verbs as tools.