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

# Tally

> Forms built from blocks, the questions Tally derives from them, and the submissions that come in

Tally's forms API at `tally-version: 2026-08-04`. The two jobs an agent is
pointed at Tally for are reading the responses that came in and spinning up a
form, and both are easy to get subtly wrong: a form is a flat list of blocks
joined by `groupUuid` rather than a list of questions, and polling submissions
runs into a 100-requests-a-minute limit quickly. Tally publishes no client
library, so the conformance suite pins the OpenAPI document Tally serves and
validates every response the twin gives against it.

**Slug:** `tally`

## What it models

| Area | Modelled |
| - | - |
| Starting account | One organization on the Pro plan, its owner, and the workspace Tally gives a new account, `My workspace` |
| Authentication | A `tly-…` key in `Authorization: Bearer`, matched exactly; Tally's `401 text/plain Unauthorized` for a key it cannot read and for a path it has no route for, and its JSON `UNAUTHORIZED_ACTION` for a key it does not know; the `tally-version` header; `GET /users/me` |
| Workspaces and folders | List, create, retrieve, rename and delete workspaces with their members and invites; nested folders, renamed and deleted with their subtree; deleting either trashes the forms inside |
| Forms and blocks | List with `workspaceIds` and page numbers, newest edit first; create, retrieve, update and trash; every block type Tally accepts, validated the way Tally validates them; settings with Tally's defaults; draft blocks on a published form; close dates and submission limits closing a form |
| Questions | Derived from a form's published blocks — one per answerable group, titled from the `TITLE` block before it or the input's placeholder — keeping their identifiers across a republish |
| Submissions | Listed with `filter`, `startDate`, `endDate`, `afterId`, `page` and `limit`, with Tally's per-filter totals; retrieved and deleted; answers typed by their question, choices as option texts |
| Webhooks | Create, list, update and delete, and the event log a completed submission appends to |
| Organization | Its users, invites by email into workspaces, and cancelling them |
| Errors and limits | Tally's Joi validation messages, checked in Tally's order and before the key is looked up; its not-found and business-rule envelopes; 100 requests a minute with the `x-ratelimit-*` headers and the `429` |

Advancing closes forms whose close date has passed, completes partial
submissions that were marked to complete, and appends a `FORM_RESPONSE` event
to each enabled webhook for every newly completed submission.

## Not modelled

Analytics (metrics, visits, submissions over time, dimensions and drop-off),
webhook delivery, form templates, file uploads, payments, hidden and calculated
fields as questions, the preview and PDF pages a submission links to, and every
response shape older than `2026-08-04`. An endpoint Tally has and the twin has
not built answers an explicit `501` in Tally's envelope; a path Tally does not
have gets Tally's own `401 text/plain Unauthorized`.


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