API reference

Use the REST API directly with any HTTP client. The MCP endpoint uses the same API-key authentication.

Base URL

https://app.form.gold/api

Authentication

Pass your API key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Get an API key from your account settings.

OpenAPI spec

The full OpenAPI 3.1 spec is available at:

GET https://app.form.gold/api/openapi.json

Forms

`POST /api/forms`

Create a new form.

Request body:

{
  "title": "Contact Us",
  "slug": "contact",
  "branding": {
    "primary_color": "#0f172a"
  },
  "notifications": {
    "email": ["you@example.com"],
    "subject": "New contact from {field:name}"
  },
  "humanness": true,
  "fields": [
    { "id": "name", "type": "text", "label": "Your name", "required": true },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    { "id": "message", "type": "textarea", "label": "Message", "required": true }
  ]
}

Response:

{
  "slug": "contact",
  "form_slug": "contact",
  "status": "live",
  "public_url": "https://form.gold/acme/contact",
  "short_url": "https://form.gold/a1b2c3"
}

`GET /api/forms`

List all forms for the authenticated account.

Response:

[
  {
    "slug": "contact",
    "title": "Contact Us",
    "created_at": "2026-04-01T10:00:00Z",
    "stats": { "views": 310, "responses": 42 }
  }
]

`GET /api/forms/{slug}`

Fetch a single form's config and stats.

Response:

{
  "slug": "contact",
  "title": "Contact Us",
  "config": { ... },
  "stats": {
    "views": 310,
    "responses": 42,
    "completion_rate": 0.135,
    "sparkline_7d": [
      { "date": "2026-04-22", "count": 3 },
      { "date": "2026-04-23", "count": 5 }
    ]
  }
}

`PATCH /api/forms/{slug}`

Update a form's config. Only the fields you include are changed.

`DELETE /api/forms/{slug}`

Delete a form and all its responses. Irreversible.

Responses

`POST /api/forms/{slug}/submit`

Submit a form response. This endpoint is called by the public form page — it is not authenticated but requires a valid Turnstile token.

Request body:

{
  "fields": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "message": "Hello!"
  },
  "turnstile_token": "..."
}

Response:

{
  "response_id": "01JE...",
  "status": "received"
}

`GET /api/forms/{slug}/responses`

Fetch paginated responses. Requires authentication.

Query params:

Param	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Max results (default: 50, max: 200)
`since`	ISO 8601	Only return responses after this date
`until`	ISO 8601	Only return responses before this date

`GET /api/forms/{slug}/responses/{id}`

Fetch a single response by ID.

`GET /api/forms/{slug}/responses/export`

Export responses. Returns CSV by default.

Query params:

Param	Default	Description
`format`	`csv`	`csv`, `json`, or `markdown`
`since`	—	Filter start date
`until`	—	Filter end date

`GET /api/forms/{slug}/report`

Generate an agent-readable Markdown report.

Query params:

Param	Default	Description
`period`	`7d`	`7d`, `30d`, `90d`, or `all`

`GET /api/forms/{slug}/stats`

Fetch aggregate stats: views, responses, completion rate, 7-day sparkline, and change vs prior period.

Error responses

All errors follow this shape:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}

HTTP status	Meaning
`400`	Invalid request body or params
`401`	Missing or invalid API key
`403`	API key does not own this form
`404`	Form or response not found
`422`	Turnstile verification failed
`429`	Rate limit exceeded
`500`	Server error

On this page