io.github.sunsiyuan/human-survey

Set the questions and candidates a form shows. Replaces the whole configuration and stores it as a new immutable version, so responses already collected keep describing the list they were actually shown. Re-sending an identical configuration reuses the existing version rather than making another. A form is one single-select question, optionally expanding into a second. Give a candidate an `expands` naming another question to reveal it when that candidate is picked — that is how "TikTok" becomes "which account". Candidate ids must be stable keys that survive a rename. Using a handle as an id splits that creator’s history in two the day they change it. Set catalog_slug to take a candidate’s label and logo from the platform catalog. Order defaults to "rotate", which randomizes per respondent and is what makes the reported shares unbiased; "fixed" keeps your order and accepts that earlier options get picked more often for being earlier.

Create a form and return its id, its respondent URL, and the iframe and postMessage listener to embed that URL in a host page. The form has no questions yet and shows nothing to respondents until it is configured. allowed_origins restricts which sites may embed it; leaving it empty allows any site, which means any site can spend this account’s response quota.

What respondents said, aggregated. Reports, per question, how many completed responses named each candidate out of how many answered that question, the unresolved answers in the same list, how often a follow-up question failed to find an answer, and revenue where conversion events have been recorded. Computed fresh on every call, including any mappings made since — so a rollup of a past window can legitimately change between two reads.

List the platforms HumanSurvey knows: the slug to use as catalog_slug, the display label, and which class of channel it is. These are the named channels a respondent can be shown — TikTok, ChatGPT, LinkedIn, Reddit and so on — plus the descriptive options that have no brand behind them, like "a friend or colleague told me". No API key needed.

Read one form: its settings, and the question configuration currently shown to respondents — every question, every candidate, and the order mode. Returns the configuration as JSON, because that is the exact shape a configuration write takes.

List the forms on this account: id, name, respondent URL, whether it is active or paused, whether it has been configured with questions yet, and how many responses it has collected.

The answers respondents typed instead of picking from the list, grouped by the exact text and ordered by how often it was typed. Reports the spelling variants seen, when each was first and last typed, and whether a mapping already covers it. These are verbatim words. Two texts that read alike may be different people, and a text may name somebody who is not on the candidate list at all.

Sign in with an email address and store an API key on this machine. Called with only an email, it mails a six-digit code and returns nothing usable — the code has to come from the person, out of their inbox. Called with the email and that code, it stores a key at ~/.humansurvey/credentials and reports where it was written. The key itself is never printed. Signing in and signing up are the same act: an address that has never been used gets an account.

Record that a specific typed answer means a specific candidate. It applies to every response already carrying that text as well as every future one, so numbers reported for past windows change. The original text is never altered and a mapping can be revoked, but a report may already have been read. Only map a text whose meaning is established — a text that merely resembles a candidate’s name is not evidence that it is that candidate. One live mapping per text per question.

Stop a mapping from applying. The typed answers it covered return to the unresolved list — in past windows as well as future ones, because rollups join mappings when they are read rather than when they are made. Numbers already reported for those windows will therefore change. Nothing is deleted: the mapping is marked revoked and kept, so a report produced while it was live can still be explained. Revoking an already-revoked mapping is not an error and does not move the time it stopped applying. Mapping ids appear beside any text that is already mapped in the free-text listing, and in the confirmation given when a mapping is created.