GudForm Developer Documentation

API keys, webhooks, and Docker self-hosting for the open-source edition.

API Authentication

Generate API keys and authenticate requests

REST API Reference

Full reference for forms, collections, and responses

MCP for agents

List forms, read schema, create questions, submit answers

Collections

Organize forms into collections with team-based access

Webhooks

Receive real-time events when forms are submitted

Self-hosting

Run GudForm with Docker Compose (OSS edition)

Getting Started

1. Create an API Key

Navigate to Dashboard → Settings → API Keys and generate a new key. API keys start with ff_ and are used as Bearer tokens in all API requests.

2. Make Your First Request

List your formsGET

curl -X GET https://gudform.com/api/v1/forms \
  -H "Authorization: Bearer ff_your_api_key_here" \
  -H "Content-Type: application/json"

3. Explore the API

The GudForm REST API is organized around standard REST conventions. All responses return JSON. We support CRUD operations on forms and collections, plus list and submit for form responses.

View Full API Reference

Base URL

All API endpoints use the following base URL:

https://gudform.com/api/v1

Client Libraries

Official client libraries are available on npm and PyPI. Install via your package manager:

Install SDK

# TypeScript/JavaScript
npm install @gudlab/gudform

# Python
pip install gudform

TypeScript SDK example

import { GudForm } from "@gudlab/gudform";

const client = new GudForm({ apiKey: "ff_your_key" });

// List forms
const { forms } = await client.forms.list();

// List forms in a specific collection
const { forms: filtered } = await client.forms.list({
  collectionId: "collection_id",
});

// List collections
const { collections } = await client.collections.list();

// Get responses
const { responses } = await client.forms.responses("form_id", {
  page: 1,
  limit: 50,
});

Python SDK example

from gudform import GudForm

client = GudForm(api_key="ff_your_key")

// List forms
forms = client.forms.list()

// List forms in a specific collection
filtered_forms = client.forms.list(collection_id="collection_id")

// List collections
collections = client.collections.list()

// Get responses
responses = client.forms.responses("form_id", page=1, limit=50)

Source code available at sdk/ (TypeScript) and sdk/python/ (Python).

API Changelog

v1.1Current — Stable

• New Collections API — full CRUD for organizing forms into collections
• Forms now include collectionId and collection in responses
• Filter forms by collection via ?collectionId= query parameter
• Move forms between collections via PATCH
• Updated Free plan — unlimited forms and submissions. Hosted API keys are included with rate limits; teams and webhooks stay on paid tiers.

v1.0Stable

Initial API release with forms CRUD, responses read access, webhook events, payment fields, and integration marketplace support.