Skip to main content

​
Authentication

All API requests require authentication via an API key.

​
API Keys

API keys are passed in the X-API-Key header: 
curl https://geniusforms.ai/api/v1/forms \
  -H "X-API-Key: gf_sk_live_YOUR_API_KEY"

​
Key Format

GeniusForms API keys follow this format:
PrefixEnvironment
gf_sk_live_Production
gf_sk_test_Sandbox (coming soon)

​
Creating API Keys

  1. Go to your dashboard
  2. Navigate to Settings → API Keys
  3. Click Create API Key
  4. Optionally name your key and set a rate limit
  5. Copy the key immediately - it’s only shown once!
Security Best Practices
  • Never expose API keys in client-side code
  • Store keys in environment variables
  • Rotate keys if you suspect they’ve been compromised
  • Use form-scoped keys when possible for least-privilege access

​
Rate Limits

Each API key has a daily request limit that resets at midnight UTC.
PlanDefault Limit
Free100 requests/day
Pro1,000 requests/day
EnterpriseCustom
You can customize limits when creating a key (100, 500, 1,000, 5,000, or 10,000).

​
Rate Limit Headers

Every response includes rate limit information: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1707264000
HeaderDescription
X-RateLimit-LimitYour daily request limit
X-RateLimit-RemainingRequests remaining today
X-RateLimit-ResetUnix timestamp when limit resets

​
Handling Rate Limits

When you exceed your limit, you’ll receive a 429 response: 
{
  "error": "rate_limit_exceeded",
  "message": "Daily rate limit exceeded. Resets at midnight UTC."
}

​
Form-Scoped Keys

For enhanced security, you can create keys scoped to a specific form:
  • Can only access that form’s data
  • Cannot create new forms
  • Cannot access other forms’ responses
This is ideal for integrations that only need access to a single form.

​
Error Responses

StatusErrorDescription
401unauthorizedMissing, invalid, or revoked API key
403forbiddenKey doesn’t have access to this resource
429rate_limit_exceededDaily limit exceeded
Example error response: 
{
  "error": "unauthorized",
  "message": "Invalid or expired API key"
}