# Let's Clarify — Human-in-the-Loop API for AI Agents

> When your AI agent needs human input mid-workflow, Let's Clarify bridges the gap.

## What is Let's Clarify?

Let's Clarify is an API service that enables AI agents to collect structured human input during automated workflows. The agent creates a form via API, shares a unique URL with a human, and receives structured JSON back — either by polling or via webhook.

## How It Works

1. **Agent creates a form** — POST /api/v1/forms with a JSON schema defining fields (text, select, checkbox, file upload, etc.)
2. **Service generates unique URLs** — One URL per recipient, shareable via email, Slack, or embed widget
3. **Human fills out the form** — In any browser, no login required
4. **Agent gets structured JSON back** — Via webhook POST or by polling GET /api/v1/forms/{token}/results

## API Overview

Base URL: https://letsclarify.ai/api/v1

### Authentication
- Register: POST /api/v1/register (name + email, no auth required)
- Returns an API key starting with `lc_`
- Include as: `Authorization: Bearer lc_...`

### Endpoints
- POST /api/v1/forms — Create a form with JSON schema
- GET /api/v1/forms/{token}/summary — Check submission status
- GET /api/v1/forms/{token}/results — Get all responses as JSON
- POST /api/v1/forms/{token}/recipients — Add more recipients
- DELETE /api/v1/forms/{token} — Delete form and all data

### Supported Field Types
text, textarea, select, checkbox, checkbox_group, radio, file

### Features
- Webhook notifications on each submission (POST to your URL)
- File uploads (returned as base64 via API)
- Form validation (required, min/max length, regex pattern)
- Prefilled values per recipient
- Custom theme color
- Embeddable widget (embed.js)
- Auto-deletion after configurable retention period (1-365 days)
- Up to 10,000 recipients per form

## MCP (Model Context Protocol)

Let's Clarify also supports MCP for direct agent integration:
- Endpoint: https://letsclarify.ai/mcp
- Transport: Streamable HTTP
- Server card: https://letsclarify.ai/.well-known/mcp/server-card.json

## Use Cases

- Approval workflows (budget sign-off, deploy approvals)
- Data collection (onboarding forms, surveys, feedback)
- Human review (content moderation, quality checks)
- Decision points (choosing between options mid-workflow)

## Quick Start

```bash
# 1. Register for an API key
curl -X POST https://letsclarify.ai/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "email": "agent@example.com"}'

# 2. Create a form
curl -X POST https://letsclarify.ai/api/v1/forms \
  -H "Authorization: Bearer lc_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Quick Approval",
    "schema": [
      {"id": "decision", "type": "select", "label": "Approve?", "options": ["Yes", "No"]},
      {"id": "notes", "type": "textarea", "label": "Notes"}
    ],
    "recipient_count": 1,
    "retention_days": 7
  }'

# 3. Share the URL from the response with a human

# 4. Get results
curl https://letsclarify.ai/api/v1/forms/FORM_TOKEN/results \
  -H "Authorization: Bearer lc_YOUR_KEY"
```

## Links

- Website: https://letsclarify.ai
- MCP Server Card: https://letsclarify.ai/.well-known/mcp/server-card.json
- Privacy Policy: https://letsclarify.ai/privacy
- Terms of Service: https://letsclarify.ai/terms

## Contact

LessCode GmbH
Dr. Alfred-Neff-Str. 15
75015 Bretten, Germany
Email: letsclarify@lesscode.de