Formasty machine-readable docs

Primary human API docs:
- /documentation/api-overview

Primary machine-readable API docs:
- /api-docs.txt

GPT Action OpenAPI pack:
- docs/gpt-actions/formasty-openapi.yaml

Primary machine-readable landing page copy:
- /landing-page.txt

Summary:
- Formasty exposes a Forms API for creating, editing, saving drafts, publishing, and deleting forms.
- Canonical production base URL: https://app.formasty.com/api/v1
- Authentication: Authorization: Bearer <api_key>
- MCP endpoint: https://app.formasty.com/api/mcp
- Preferred MCP auth: OAuth discovery via https://app.formasty.com/.well-known/oauth-authorization-server and https://app.formasty.com/.well-known/oauth-protected-resource/api/mcp
- Fallback MCP auth: Authorization: Bearer <api_key> for developer-controlled clients that cannot complete OAuth yet
- MCP sessions act as the authenticated Formasty user and use that user's live workspace access
- Revoking an MCP connection blocks future OAuth tokens and fallback /api/mcp calls for that connection without disabling standard Forms API requests
- The API uses the same builder-compatible draftSchema contract as the main Formasty builder UI.
- A form can be created with a full draftSchema, updated later with another full draftSchema, published, and then opened at the returned public_url.
- MCP agents can create forms without UI access by calling tools/list, formasty.list_workspaces, formasty.create_form or formasty.get_form, formasty.validate_draft, and formasty.publish_form.
- MCP also includes formasty.list_starter_templates, formasty.create_form_from_starter_template, formasty.clone_form, and formasty.delete_form for template-based starts and lifecycle cleanup.
- formasty.create_form requires a stable idempotencyKey so agent retries replay the same created form instead of creating duplicates.
- GPT Actions should import docs/gpt-actions/formasty-openapi.yaml and use a dedicated API-key bearer credential for the /api/v1 surface.
- MCP OAuth remains the preferred path for per-user ChatGPT app connections and live tool discovery.
- Payment fields use type "payment", require Pro access and a workspace Razorpay connection, and are verified server-side before the final submission is accepted.
- In-app XLSX exports use session-authenticated /api/forms/{form_id}/responses/exports/xlsx job endpoints and are not part of the GPT Action OpenAPI pack.

Core workflow:
1. POST /api/v1/forms
2. GET /api/v1/forms/{form_id}
3. PATCH /api/v1/forms/{form_id} or PUT /api/v1/forms/{form_id}/draft
4. POST /api/v1/forms/{form_id}/publish
5. Open data.public_url

MCP workflow:
1. In ChatGPT on the web, open Settings -> Apps -> Advanced settings -> Developer mode and enable Developer mode.
2. Open Settings -> Apps, click Create app, and choose a remote MCP server.
3. Set the app name to formasty and the server URL to https://app.formasty.com/api/mcp.
4. Complete the OAuth sign-in and consent flow. Formasty MCP supports discovery, dynamic client registration, authorization-code PKCE, and refresh tokens.
5. OAuth is the recommended setup for ChatGPT, Codex, and other remote MCP clients.
6. If your client cannot complete OAuth yet, generate a Formasty API key with forms:create, forms:publish, forms:read, and any edit scopes the agent needs, then use Authorization: Bearer <api_key> as the fallback transport.
7. After ChatGPT imports the server, review the discovered tools and keep only the tools you want enabled.
8. Start a normal chat, attach the Formasty app to the conversation, and initialize the MCP session with tools/list.
9. Call formasty.list_workspaces and use recommendedCreateWorkspaceId when present.
10. Call tools/call with name formasty.create_form or formasty.get_form. When creating, always pass a stable idempotencyKey.
11. Review the returned form, draft_schema, and draft_revision.
12. Call tools/call with name formasty.validate_draft before publish.
13. Call tools/call with name formasty.publish_form and arguments { "formId": "<returned form.id>", "draftRevision": <returned draft_revision> }.
14. Open or return the published publicUrl.
15. When the user wants a seeded starting point, call formasty.list_starter_templates and formasty.create_form_from_starter_template instead of generating the entire first draft manually.
16. Use formasty.clone_form before major edits on an existing form, and formasty.delete_form to clean up drafts the agent should discard.

ChatGPT install notes:
- Use regular chat with the Formasty app attached when you need write actions such as create, update, validate, or publish.
- Do not rely on deep research or Agent mode for Formasty write workflows.
- If your ChatGPT plan or workspace only supports read/fetch MCP access, install the app but use Codex or another MCP client for create/edit/publish actions.
- These ChatGPT install steps match OpenAI's Apps and Developer mode flow as of April 22, 2026. ChatGPT menu names can change over time.

Agent setup guide:
1. In Codex, Claude, or another MCP-capable agent, add a remote MCP server named formasty.
2. Server URL: https://app.formasty.com/api/mcp
3. Preferred auth: OAuth discovery and consent from the Formasty MCP origin
4. Fallback header: Authorization: Bearer <api_key>
5. Tell the agent: "Use the Formasty MCP server to create a form from my brief. Inspect tools/list, call formasty.list_workspaces, create or inspect the draft with a stable idempotencyKey, run formasty.validate_draft, and publish only after the structure is correct."
6. The agent should not call the browser UI unless the user asks for visual review.

Copy-paste setup prompt:
- You are my Formasty build agent.
- Use the configured remote MCP server named formasty.
- If the Formasty MCP server is unavailable in this chat, tell me what is missing and stop.
- If you can browse documentation, use these Formasty references as the source of truth:
  - https://formasty.com/documentation/api-overview
  - https://formasty.com/documentation/api-authentication
  - https://formasty.com/documentation/api-endpoints-forms
  - https://formasty.com/api-docs.txt
  - https://formasty.com/llms.txt
- Before you make changes:
  - Initialize MCP and inspect tools/list.
  - Call formasty.list_workspaces first and use recommendedCreateWorkspaceId when present. If it is null or ambiguous, ask me which workspace to use.
  - If a seeded template is the best fit, call formasty.list_starter_templates and formasty.create_form_from_starter_template. Otherwise call formasty.create_form with a stable idempotencyKey.
  - After each major change, call formasty.get_form so you are working from the latest draft state.
  - Make edits only through Formasty MCP tools that actually appear in tools/list.
  - Call formasty.validate_draft before any publish step and fix blockers first.
  - Publish only when I explicitly ask you to publish.
  - When finished, return the formId, draftRevision, and publicUrl if one exists.
  - Do not open the browser UI unless I explicitly ask for visual review.
- When I give you a form brief, convert it into a production-ready Formasty draft, not just a generic outline.

Important notes:
- Public respondents only see published snapshots.
- Draft changes do not affect the hosted public form until publish succeeds.
- GET/PATCH/PUT draft responses return the resolved draft_schema.
- Publish returns the published_schema and the hosted public_url.
- Builder-compatible draftSchema can include quiz metadata. For recommendation or personality quizzes, set quiz.type to "match", optionally set quiz.mode to "match" or "personality" ("match" means recommendation/product-match), reference ending screens from settings.submissions.thankYouScreens or "__formasty_default_thank_you__" for the default thank-you screen, and map answer option values to those screen IDs.
- Ending screen cosmetics round-trip through settings.submissions.thankYou and settings.submissions.thankYouScreens. Supported fields include showSocialShareIcons, socialShareLinks, showButton, buttonLabel, buttonUrl, buttonOpenInNewTab, mediaUrl, mediaType, mediaAlt, mediaAttribution, logoUrl, logoAttribution, titleSize, textAlign, backgroundColor, backgroundImageUrl, backgroundImageAttribution, backgroundImageBrightness, headingColor, descriptionColor, buttonBackgroundColor, buttonTextColor, and buttonRadius.
- Image attribution fields use { provider: "unsplash", photographerName, photographerUrl, sourceName: "Unsplash", sourceUrl, photoUrl } and should be kept with any Unsplash image URL so public forms can render linked photographer and Unsplash credit.
- socialShareLinks is optional and accepts { "facebook": "https://...", "x": "https://...", "linkedin": "https://..." }; omit a network to use the default share URL for that icon.