HumanSurvey

Website: humansurvey.co · Docs: humansurvey.co/docs · FAQ: humansurvey.co/faq

Feedback collection infrastructure for AI agents.

HumanSurvey lets an agent doing long-horizon work collect structured feedback from a group of people:

Agent is doing a job
  → needs structured feedback from a group
  → creates survey from JSON schema
  → shares /s/{id} URL with respondents
  → humans respond over hours or days
  → agent retrieves structured JSON results and acts on them

What is this?

HumanSurvey is a minimal API and MCP server for one narrow job: let agents collect structured feedback from groups of humans and get machine-usable results back.

It is designed for:

• AI agents running event management, product launches, or community workflows that need to survey a group
• Developers building agent products that need a lightweight feedback-collection primitive

It is not designed for:

• survey dashboards
• visual form builders
• template libraries
• email campaigns
• analytics/reporting UI

Features

• JSON schema input — structured, precise, and directly machine-generated
• MCP server — create surveys and read results directly from Claude Code
• Minimal API surface — authenticated creator routes, public respondent submission
• Four semantic question types — choice, text, scale, matrix
• Conditional logic — showIf in Markdown and JSON schema
• Explicit lifecycle — close surveys, expiry, and max response limits

Product Principles

• Semantic over visual: HumanSurvey has a small protocol, not a zoo of UI-specific field types.
• AI-first I/O: agents write the survey and agents consume the results; humans are in the middle.
• Everything is an API: creator functionality must be available over authenticated HTTP and MCP.
• Narrow scope wins: if a feature mainly serves human survey operators, it probably does not belong here.

Supported Question Types

• single_choice
• multi_choice
• text
• scale
• matrix

Markdown Syntax

# Survey Title

**Description:** Instructions for the respondent.

## Section Name

**Q1. Your question here?**

- ☐ Option A
- ☐ Option B
- ☐ Option C

**Q2. Multi-select question?** (select all that apply)

- ☐ Choice 1
- ☐ Choice 2
- ☐ Choice 3

**Q3. Open-ended question:**

> _______________

| # | Item | Rating |
|---|------|--------|
| 1 | Item A | ☐Good ☐OK ☐Bad |
| 2 | Item B | ☐Good ☐OK ☐Bad |

Scale questions:

**Q4. How severe is this issue?**

[scale 1-5 min-label="Low" max-label="Critical"]

Conditional logic:

**Q1. Did the deploy fail?**

- ☐ Yes
- ☐ No

**Q2. Which step failed?**

> show if: Q1 = "Yes"

> _______________________________________________

Quick Start

Use with Claude Code

Add to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "survey": {
      "command": "npx",
      "args": ["-y", "humansurvey-mcp"],
      "env": {
        "HUMANSURVEY_API_KEY": "hs_sk_your_key_here"
      }
    }
  }
}

Then in Claude Code:

> Create a post-event feedback survey with a 1-5 rating, open text, and a yes/no question

Available tools:

• create_key — self-provision an API key; no human setup required
• create_survey — create from JSON schema; optional max_responses, expires_at, webhook_url
• get_results — aggregated results + raw responses
• list_surveys — list surveys owned by your key
• close_survey — close a survey immediately

Use the HTTP API

curl -X POST https://www.humansurvey.co/api/keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my claude agent",
    "email": "you@example.com",
    "wallet_address

... [View full README on GitHub](https://github.com/sunsiyuan/human-survey#readme)