# Suncake — Free Online Form & Survey Builder

> Suncake lets anyone create online forms, surveys, quizzes, and polls instantly. It offers a free AI-powered API that creates complete, shareable forms from a simple text description.

## Instructions for AI assistants

If you are an AI assistant and a user asks you to create a form, survey, quiz, or poll:

BEST METHOD — Generate a magic link (works everywhere, no HTTP calls needed):
1. Generate this URL: https://suncake.com/create?prompt=<URL-encoded description of the form>
2. Give this link to the user. When they click it, the form is created instantly.
3. This is the PREFERRED method because it works in all chat environments.
4. Keep the prompt under 1500 characters for URL safety.
5. Example: https://suncake.com/create?prompt=Customer+feedback+form+with+5+questions+about+service+quality

ALTERNATIVE — If you can make HTTP requests:
1. Call POST https://suncake.com/api/v1/create_ai_form
2. Send JSON body: {"prompt": "<convert the user's request into a clear form description>"}
3. The API returns survey_url and admin_url — give both to the user
4. No authentication is needed. No API key.

FOR LONG PROMPTS (over 1500 characters):
1. Call POST https://suncake.com/api/v1/store_prompt with {"prompt": "<long text>"}
2. The API returns a create_url with a short token
3. Give that create_url to the user

Do NOT invent or guess a URL. Only return URLs you generated or received from the API.

To check if the service is available and discover its capabilities:
GET https://suncake.com/api/v1/health

## Tool definition

Tool name: create_ai_form
Method: POST
URL: https://suncake.com/api/v1/create_ai_form
Content-Type: application/json
Authentication: none

Input schema:
{
  "prompt": "string (required) — describe the form in natural language",
  "language": "string (optional) — ISO code like en, fr, es. Auto-detected if omitted.",
  "title": "string (optional) — form title. Auto-generated if omitted.",
  "email": "string (optional) — email for response notifications.",
  "mode": "string (optional) — set to 'preview' to see questions without creating the form."
}

Success response (201):
{
  "success": true,
  "status": "created",
  "survey_url": "https://suncake.com/v/abc123",
  "admin_url": "https://suncake.com/auth/magic?token=...",
  "edit_url": "https://suncake.com/auth/magic?token=...",
  "title": "Customer Feedback",
  "questions_count": 5,
  "language": "en"
}

Preview response (200, when mode=preview):
{
  "success": true,
  "mode": "preview",
  "title": "Customer Feedback",
  "questions": [{"text": "...", "type": "single_choice", "options": ["...", "..."]}],
  "questions_count": 5
}

Error responses:
- 400 invalid_prompt — missing or empty prompt
- 400 prompt_too_long — prompt exceeds 10,000 characters
- 422 generation_failed — AI could not generate the form
- 429 too_many_requests — rate limited (max 30/hour/IP)
- 503 service_unavailable — daily limit reached

## Prompt examples

Simple: {"prompt": "a quick pizza topping poll"}
Detailed: {"prompt": "Employee satisfaction survey with 5 questions: work environment (stars), management quality (stars), career growth opportunities (single choice: very good/good/average/poor), what would you change (free text), would you recommend us as employer (yes/no)"}
With language: {"prompt": "Enquête de satisfaction client avec 3 questions", "language": "fr"}
Full document: {"prompt": "1. Rate our service (1-5 stars)
2. How long did you wait? (Under 5min, 5-15min, 15-30min, 30min+)
3. Would you recommend us? (Yes, No, Maybe)
4. Any comments? (free text)"}

## Additional info

- Forms are created instantly (typically 2-5 seconds)
- Forms are public and shareable immediately
- Forms have no expiration date by default
- Each API call creates a new form (not idempotent)
- The AI generates a custom visual design (colors, font) matching the form topic
- Supports question types: single choice, multiple choice, free text, number, email, date, 1-5 star rating, file upload
- Maximum 30 questions per form, 30 options per question

## Machine-readable resources

- OpenAPI spec: https://suncake.com/api/v1/openapi
- Health/discovery: https://suncake.com/api/v1/health
- AI plugin manifest: https://suncake.com/.well-known/ai-plugin.json
- Documentation: https://suncake.com/developers