Form Submission Endpoint
The form submission endpoint accepts data from your frontend forms.
Endpoint
POST /f/{form_id}Each form has a unique form_id (e.g., abc123xyz). Find it in your form settings.
Request Formats
JSON (recommended for JavaScript)
curl -X POST https://atlasforms.app/f/abc123xyz \
-H "Content-Type: application/json" \
-d '{"name": "John", "email": "john@example.com"}'Form URL-encoded (HTML forms)
curl -X POST https://atlasforms.app/f/abc123xyz \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "name=John&email=john@example.com"Multipart Form Data (with file uploads)
curl -X POST https://atlasforms.app/f/abc123xyz \
-F "name=John" \
-F "email=john@example.com" \
-F "attachment=@document.pdf"Response Formats
JSON Response (default for AJAX)
When Accept: application/json or Content-Type: application/json:
{
"success": true,
"submission_id": "550e8400-e29b-41d4-a716-446655440000",
"webhook_delivered": false,
"files": [
{
"id": "file-uuid",
"filename": "document.pdf",
"type": "application/pdf",
"size": 102400
}
]
}Redirect Response (HTML forms)
If the form has a Success Redirect URL, HTML form submissions get a 302 redirect to it. Without one, browsers get a simple built-in thank-you page with a link back to the page the form was on. Requests that send or accept JSON always get the JSON response.
Query parameters are appended:
https://yoursite.com/thank-you?submission_id=xxx&status=successSuccess Redirect
Configure a redirect URL in your form settings:
The redirect includes:
submission_id - The unique submission IDstatus - Always successfiles - Number of uploaded files (if any)webhook - delivered if the first webhook attempt succeeded, otherwise pendingSpam Protection
Honeypot Fields
Add hidden honeypot fields to catch bots:
<form action="https://atlasforms.app/f/abc123xyz" method="POST">
<!-- Honeypot - hide with CSS -->
<input type="text" name="_gotcha" style="display:none" tabindex="-1" autocomplete="off">
<!-- Real fields -->
<input type="text" name="name" required>
<input type="email" name="email" required>
<button type="submit">Send</button>
</form>If _gotcha or _honeypot contains a value, the endpoint returns a normal success response but discards the submission (bots fill all fields). It is not stored and doesn't count toward your quota.
AI Spam Filter
Forms with the optional AI spam filter turned on send each submission's text to Cloudflare Workers AI. Submissions classified as spam get the normal success response but are quarantined in the form's Spam tab instead of being delivered.
Turnstile CAPTCHA
Turn on Require Turnstile CAPTCHA in Form Settings → Security, then add the widget to your form. Turnstile is only checked for browser form posts, not JSON requests:
<form action="https://atlasforms.app/f/abc123xyz" method="POST">
<input type="text" name="name" required>
<input type="email" name="email" required>
<!-- Turnstile widget -->
<div class="cf-turnstile" data-sitekey="your-site-key"></div>
<button type="submit">Send</button>
</form>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>Reserved Fields
These field names are reserved and automatically stripped. There are no other special fields: options such as the redirect URL and notification emails are set in form settings, not with hidden fields.
| Field | Purpose |
|---|---|
_gotcha | Honeypot spam protection |
_honeypot | Honeypot spam protection |
_csrf | CSRF token |
cf-turnstile-response | Turnstile token |
_turnstileToken | Turnstile token (JS) |
CORS
The endpoint supports CORS for JavaScript submissions:
Access-Control-Allow-Origin: Your configured originsAccess-Control-Allow-Methods: POST, OPTIONSAccess-Control-Allow-Headers: Content-Type, X-Atlas-KeyConfigure allowed origins in Form Settings → Security → Allowed Origins, or set defaults for the project in Project Settings → Defaults. Live forms with no allowed origins reject every submission.
Localhost Testing
Localhost submissions are accepted only in Sandbox Mode. Once you register one or more IPs in form settings, only those IPs can submit from localhost.
See Security → Localhost Testing for details.
Optional: For JavaScript apps, you can add extra security with a Sandbox API Key:
await fetch('https://atlasforms.app/f/abc123', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Atlas-Key': process.env.ATLAS_FORM_KEY // From .env.local
},
body: JSON.stringify(data)
})Rate Limiting
Submissions are rate limited to 60 requests per minute per IP address, per project. The limit is fixed.
Rate limit headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 2024-01-15T10:31:00ZError Responses
Rejected requests don't count against your monthly submission quota. Most errors include a hint that says how to fix them.
400 Bad Request
Invalid content type, malformed JSON (or a JSON body that isn't an object), a file that fails validation or can't be processed, or (in live mode) data that doesn't match the form's schema.
{ "error": "Invalid content type", "hint": "Send application/json, application/x-www-form-urlencoded, or multipart/form-data." }When a file is rejected, nothing is saved and the error names the file:
{ "error": "File \"photo.png\" could not be processed: ...", "field": "photo", "filename": "photo.png" }{ "error": "Validation failed", "details": [{ "field": "email", "error": "Invalid email format" }] }403 Forbidden
{ "error": "Origin not allowed", "origin": "other-site.com", "hint": "..." }{ "error": "Localhost not allowed in live mode. Use sandbox mode for local development." }{ "error": "IP not registered for sandbox mode. Register it with `atlas sandbox --form <form_id> --action register` or in form settings.", "your_ip": "73.45.123.100" }404 Not Found
Form doesn't exist.
{ "error": "Form not found" }429 Too Many Requests
Rate limit exceeded.
{ "error": "Rate limit exceeded. Please try again later.", "retry_after": 45 }Monthly submission limit reached. The submission is not stored. Submissions are accepted again after the monthly reset or an upgrade.
{ "error": "Monthly submission limit reached", "limit": 50, "used": 50, "upgrade_url": "..." }502 Bad Gateway
A file could not be stored. Nothing was saved; retry the submission.
{ "error": "File \"resume.pdf\" could not be stored. The submission was not saved; try again.", "field": "resume", "filename": "resume.pdf" }When file storage is full
If your account's file storage is full, submissions are still saved, without their attachments, so you don't lose the message. The submitter gets a normal 200 that tells them the attachments weren't accepted (your plan and usage are not shown):
{
"success": true,
"submission_id": "...",
"files": [],
"files_rejected": [{ "field": "resume", "filename": "cv.pdf", "size": 48213 }],
"warning": "Your message was sent, but its attachments couldn't be accepted."
}HTML forms show the thank-you page with the same note, and a success redirect gets attachments=rejected. You see the rejected files on the submission, and you get an email (at most one a day while it continues). You're also emailed when storage reaches 80%, 90% and 100%. Upgrade or free up space in Settings → Billing.