API Overview

The GeniusForms API is a REST API that allows you to programmatically create forms, manage fields, and retrieve responses.

Base URL

https://geniusforms.ai/api/v1

For local development:

http://localhost:8000/api/v1

Authentication

All endpoints require an API key passed in the X-API-Key header. See Authentication for details.

Content Type

All requests with a body should use Content-Type: application/json.

Field Types

GeniusForms supports 15+ field types:

Type	Description	Requires Options
`text`	Short text input	No
`textarea`	Long text input	No
`email`	Email address with validation	No
`number`	Numeric input	No
`phone`	Phone number	No
`url`	URL with validation	No
`date`	Date picker	No
`time`	Time picker	No
`select`	Dropdown selection	Yes
`multi_select`	Checkbox selection	Yes
`rating`	Star rating (1-5)	No
`slider`	Range slider	Yes (`sliderConfig`)
`yes_no`	Boolean toggle	No
`file_upload`	File upload	No
`currency`	Currency input	Optional (`currencyConfig`)

Options Examples

Select/Multi-select:

{
  "type": "select",
  "question": "Favorite color",
  "options": ["Red", "Green", "Blue"]
}

Slider:

{
  "type": "slider",
  "question": "How likely to recommend?",
  "sliderConfig": {
    "min": 0,
    "max": 10,
    "step": 1
  }
}

Currency:

{
  "type": "currency",
  "question": "Budget",
  "currencyConfig": {
    "currency": "USD",
    "min": 0,
    "max": 10000
  }
}

Display Modes

Forms support two display modes:

Mode	Description
`single-page`	All questions on one page (default)
`multi-step`	One question per step

Common Patterns

# 1. Create form
FORM=$(curl -s -X POST https://geniusforms.ai/api/v1/forms \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Feedback", "questions": [...]}')

FORM_ID=$(echo $FORM | jq -r '.id')

# 2. Publish
curl -X POST "https://geniusforms.ai/api/v1/forms/$FORM_ID/publish" \
  -H "X-API-Key: $API_KEY"

# 3. Share URL is now live
echo "Form URL: https://geniusforms.ai/f/$(echo $FORM | jq -r '.shareUrl')"

Paginate Responses

# Get first page
curl "https://geniusforms.ai/api/v1/forms/$FORM_ID/responses?limit=50&offset=0" \
  -H "X-API-Key: $API_KEY"

# Get next page
curl "https://geniusforms.ai/api/v1/forms/$FORM_ID/responses?limit=50&offset=50" \
  -H "X-API-Key: $API_KEY"

SDKs

Official SDKs coming soon. For now, use any HTTP client:

Python
JavaScript
cURL

import requests

API_KEY = "your_api_key"
BASE_URL = "https://geniusforms.ai/api/v1"

headers = {"X-API-Key": API_KEY}

# List forms
response = requests.get(f"{BASE_URL}/forms", headers=headers)
forms = response.json()["forms"]

const API_KEY = "your_api_key";
const BASE_URL = "https://geniusforms.ai/api/v1";

// List forms
const response = await fetch(`${BASE_URL}/forms`, {
  headers: { "X-API-Key": API_KEY }
});
const { forms } = await response.json();

curl https://geniusforms.ai/api/v1/forms \
  -H "X-API-Key: YOUR_API_KEY"

Overview

Forms

Fields

Responses

​API Overview

​Base URL

​Authentication

​Content Type

​Field Types

​Options Examples

​Display Modes

​Common Patterns

​Create → Publish → Share

​Paginate Responses

​SDKs