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. The limit depends on your plan:
PlanDefault Limit
Free1,000 requests/day
Builder ($19/mo)5,000 requests/day
Scale ($49/mo)10,000 requests/day
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 of 1000 requests exceeded. Resets at midnight UTC.",
  "resetAt": "2026-02-10T00:00:00Z",
  "tier": "free",
  "upgradeUrl": "/settings?tab=api"
}

​
Credit Headers

Every response also includes AI credit information: 
X-Credits-Remaining: 45
X-Credits-Used: 5
X-Monthly-Allowance: 500
HeaderDescription
X-Credits-RemainingCredits left in your billing cycle
X-Credits-UsedCredits consumed by this request
X-Monthly-AllowanceTotal monthly credit allowance
See Pricing & Credits for details on the credit system.

​
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
402insufficient_creditsNot enough AI credits for this operation (details)
403forbiddenKey doesn’t have access to this resource
429rate_limit_exceededDaily request limit exceeded
Example error response: 
{
  "error": "unauthorized",
  "message": "Invalid or expired API key"
}