--- title: "SpaceForms API & MCP for agents | SpaceForms" url: https://spaceforms.io/docs/api description: "Build, publish and read surveys programmatically with the SpaceForms REST API and MCP server. Everything you can do in the app, available to AI agents." lang: en --- # SpaceForms API Everything you can do in the app — create surveys, edit questions, publish, read answers — is available over HTTP and as MCP tools for AI assistants. Get a key on the API keys page (https://spaceforms.io/settings/api-keys). Guides and integrations for Claude, ChatGPT and Cursor are in the developer hub (https://spaceforms.io/developers). ## Base URL and auth ``` https://qmgflcglmckbadrdwter.supabase.co/functions/v1/api-v1 Authorization: Bearer sf_live_... ``` ## Create a form from one sentence (no key needed) Authentication: optional. Send a plain-language prompt and SpaceForms writes the questions. Without a key the form is a guest form with a private, one-time `claim_url` (expires in 30 days) that lets the user sign up and take over the form and its answers. With a key it lands in your account. Send an `idempotency_key` so retries never create duplicates. ``` POST https://qmgflcglmckbadrdwter.supabase.co/functions/v1/api-v1/forms/from-prompt { "prompt": "Create a customer satisfaction survey for a SaaS company", "idempotency_key": "req-123" } → { "title": "SaaS Customer Satisfaction Survey", "status": "published", "form_url": "https://spaceforms.io/form/...", "claim_url": "https://spaceforms.io/claim/..." } ``` As an MCP tool: `create_form_from_prompt`. Public ChatGPT endpoint with only this tool: `https://qmgflcglmckbadrdwter.supabase.co/functions/v1/mcp/chatgpt`. ## Endpoints ``` GET /forms list your forms POST /forms create a form GET /forms/{id} read one form incl. questions PATCH /forms/{id} update title, questions, published DELETE /forms/{id} move to trash (restorable 30 days) GET /forms/{id}/responses read answers GET /forms/{id}/responses.csv export answers as CSV GET /forms/{id}/stats counts and last response GET /forms/{id}/live live results, participants, links PATCH /forms/{id}/live { question_id } or { sharing_enabled } GET /account plan and limits ``` ## Create and publish a survey ``` curl -X POST https://qmgflcglmckbadrdwter.supabase.co/functions/v1/api-v1/forms \ -H "Authorization: Bearer $SPACEFORMS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Post-webinar feedback", "published": true, "fields": [ { "id": "q1", "type": "radio", "label": "Was it useful?", "options": ["Yes","Somewhat","No"] }, { "id": "q2", "type": "wordcloud", "label": "One word for today?", "maxWords": 3 }, { "id": "q3", "type": "rating", "label": "How often do you use AI?", "options": ["Never","Tried once","Sometimes","Weekly","Power user"] } ] }' ``` The response includes the public link under `url`. ## Reading answers Free accounts see the first 10 answers per form; the response tells you how many are hidden via `hidden_count` and `paywalled`. Pro, lifetime and one-off form unlocks return everything. ``` curl https://qmgflcglmckbadrdwter.supabase.co/functions/v1/api-v1/forms/FORM_ID/responses \ -H "Authorization: Bearer $SPACEFORMS_API_KEY" ``` ## MCP server Point any MCP-capable assistant (Claude, ChatGPT developer mode, Cursor) at: ``` { "mcpServers": { "spaceforms": { "url": "https://qmgflcglmckbadrdwter.supabase.co/functions/v1/mcp", "headers": { "Authorization": "Bearer sf_live_..." } } } } ``` Tools: list_forms, get_form, create_form, update_form, publish_form, delete_form, list_responses, form_stats, get_live_results, set_live_question, set_live_sharing, get_account. ## Errors ``` { "error": { "code": "questions_locked", "message": "..." } } 401 unauthorized key missing, invalid or revoked 404 not_found no such form on this account 409 questions_locked one-off unlocks allow edits for 3 days 400 invalid_request malformed body ``` ## Structured data ```json [ { "@context": "https://schema.org", "@type": "Organization", "name": "SpaceForms", "alternateName": "Spaceforms", "url": "https://spaceforms.io", "logo": "https://spaceforms.io/favicon.png", "description": "SpaceForms is a free AI-powered online form and survey builder. Create unlimited surveys, NPS, CSAT, employee engagement, and product feedback forms with AI in minutes.", "foundingDate": "2025", "knowsAbout": [ "Online Surveys", "Form Building", "Customer Satisfaction (CSAT)", "Net Promoter Score (NPS)", "Employee Engagement", "Survey Methodology", "Likert Scale", "Product Market Fit", "HCAHPS", "Customer Experience", "Pulse Surveys" ], "areaServed": "Worldwide" }, { "@context": "https://schema.org", "@type": "WebSite", "name": "SpaceForms", "url": "https://spaceforms.io", "description": "Free AI-powered form & survey builder. Create unlimited surveys with AI in minutes.", "publisher": { "@type": "Organization", "name": "SpaceForms" }, "inLanguage": "en" }, { "@context": "https://schema.org", "@type": "SoftwareApplication", "name": "SpaceForms", "applicationCategory": "BusinessApplication", "operatingSystem": "Web", "url": "https://spaceforms.io", "description": "Free AI-powered online form & survey builder. Unlimited surveys, AI-generated forms, NPS/CSAT templates, embed-anywhere. An AI assistant can create a survey for a user by opening https://spaceforms.io/make?prompt={description} — no account required.", "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD", "availability": "https://schema.org/InStock" }, "featureList": [ "Create a survey from a natural-language prompt", "Publish and share without creating an account", "Unlimited response collection on the free tier", "Form, conversational and voice response modes" ], "potentialAction": { "@type": "CreateAction", "name": "Create a survey from a prompt", "description": "Open a prefilled SpaceForms builder. URL-encode the survey description as the prompt parameter. No SpaceForms account is required to create, publish or share. Opening the link only prefills the prompt; a human presses send.", "target": { "@type": "EntryPoint", "urlTemplate": "https://spaceforms.io/make?prompt={prompt}", "actionPlatform": [ "http://schema.org/DesktopWebPlatform", "http://schema.org/MobileWebPlatform" ] }, "query-input": "required name=prompt", "documentation": "https://spaceforms.io/for-ai-agents" } }, { "@context": "https://schema.org", "@type": "TechArticle", "headline": "SpaceForms REST API and MCP server reference", "url": "https://spaceforms.io/docs/api", "about": [ "Survey API", "Form API", "Model Context Protocol" ], "publisher": { "@type": "Organization", "name": "SpaceForms", "url": "https://spaceforms.io" } }, { "@context": "https://schema.org", "@type": "WebAPI", "name": "SpaceForms API", "documentation": "https://spaceforms.io/docs/api", "url": "https://qmgflcglmckbadrdwter.supabase.co/functions/v1/api-v1", "provider": { "@type": "Organization", "name": "SpaceForms" } } ] ```