A
Atlas
...

Form Submission Endpoint

The form submission endpoint accepts data from your frontend forms.

Endpoint

http
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)

bash
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)

bash
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)

bash
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:

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=success

Success Redirect

Configure a redirect URL in your form settings:

  • Go to Form Settings → General (under Delivery Settings)
  • Set Success Redirect to your thank-you page URL
  • The redirect includes:

  • submission_id - The unique submission ID
  • status - Always success
  • files - Number of uploaded files (if any)
  • webhook - delivered if the first webhook attempt succeeded, otherwise pending
  • Spam Protection

    Honeypot Fields

    Add hidden honeypot fields to catch bots:

    html
    <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:

    html
    <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.

    FieldPurpose
    _gotchaHoneypot spam protection
    _honeypotHoneypot spam protection
    _csrfCSRF token
    cf-turnstile-responseTurnstile token
    _turnstileTokenTurnstile token (JS)

    CORS

    The endpoint supports CORS for JavaScript submissions:

  • Access-Control-Allow-Origin: Your configured origins
  • Access-Control-Allow-Methods: POST, OPTIONS
  • Access-Control-Allow-Headers: Content-Type, X-Atlas-Key
  • Configure 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:

    javascript
    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:00Z

    Error 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.

    json
    { "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:

    json
    { "error": "File \"photo.png\" could not be processed: ...", "field": "photo", "filename": "photo.png" }
    json
    { "error": "Validation failed", "details": [{ "field": "email", "error": "Invalid email format" }] }

    403 Forbidden

  • Form or project is inactive
  • Origin not allowed, or no allowed origins configured
  • Turnstile verification failed
  • IP blocked
  • Localhost not allowed (live mode)
  • IP not registered (sandbox mode)
  • json
    { "error": "Origin not allowed", "origin": "other-site.com", "hint": "..." }
    json
    { "error": "Localhost not allowed in live mode. Use sandbox mode for local development." }
    json
    { "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.

    json
    { "error": "Form not found" }

    429 Too Many Requests

    Rate limit exceeded.

    json
    { "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.

    json
    { "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.

    json
    { "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):

    json
    {
      "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.