{
    "openapi": "3.1.2",
    "info": {
        "title": "Postvia Public API",
        "version": "1.0.0",
        "description": "Postvia public form submission API. Both the versioned endpoint and the short alias share one implementation and response contract. Documentation: https://postvia.dev/docs.",
        "license": {
            "name": "Proprietary",
            "url": "http://localhost:8010/docs"
        }
    },
    "servers": [
        {
            "url": "https://api.postvia.dev",
            "description": "Production"
        }
    ],
    "tags": [
        {
            "name": "Submissions",
            "description": "Accept customer-defined form submissions over JSON, URL-encoded or text-only multipart requests."
        }
    ],
    "paths": {
        "/v1/forms/{public_id}/submissions": {
            "options": {
                "operationId": "preflightForm",
                "description": "Handles the CORS preflight for the submission endpoint. The response is 204 and includes CORS headers only for an allowed customer origin.",
                "summary": "Preflight a form submission (CORS)",
                "tags": [
                    "Submissions"
                ],
                "parameters": [
                    {
                        "name": "public_id",
                        "in": "path",
                        "required": true,
                        "description": "Opaque public form identifier. Treat it as an identifier, not an authentication secret.",
                        "schema": {
                            "type": "string",
                            "description": "Opaque public form identifier.",
                            "examples": [
                                "abc123"
                            ]
                        }
                    },
                    {
                        "name": "Origin",
                        "in": "header",
                        "required": true,
                        "description": "Required. The customer website origin.",
                        "schema": {
                            "type": "string",
                            "description": "Required. The customer website origin.",
                            "examples": [
                                "https://customer-site.example"
                            ]
                        }
                    },
                    {
                        "name": "Access-Control-Request-Method",
                        "in": "header",
                        "description": "The method the browser intends to use.",
                        "schema": {
                            "type": "string",
                            "description": "The method the browser intends to use.",
                            "examples": [
                                "POST"
                            ]
                        }
                    },
                    {
                        "name": "Access-Control-Request-Headers",
                        "in": "header",
                        "description": "Headers the browser intends to send.",
                        "schema": {
                            "type": "string",
                            "description": "Headers the browser intends to send.",
                            "examples": [
                                "content-type, accept, idempotency-key"
                            ]
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "CORS preflight accepted.",
                        "headers": {
                            "Access-Control-Allow-Origin": {
                                "description": "The exact allowed origin.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "https://customer-site.example"
                                    ]
                                }
                            },
                            "Access-Control-Allow-Methods": {
                                "description": "Allowed methods.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "POST, OPTIONS"
                                    ]
                                }
                            },
                            "Access-Control-Allow-Headers": {
                                "description": "Allowed request headers.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "Content-Type, Accept, Idempotency-Key"
                                    ]
                                }
                            },
                            "Access-Control-Max-Age": {
                                "description": "Preflight cache lifetime in seconds.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "600"
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The origin is missing or not on the form website allowlist.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "origin_not_allowed",
                                        "message": "This origin is not allowed."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    }
                },
                "security": []
            },
            "post": {
                "operationId": "submitForm",
                "description": "Submits a customer-defined set of fields to a public form. This is the primary versioned endpoint; POST /f/{public_id} is a short alias with identical behaviour.\n\nThe request must include an allowed Origin. Turnstile is required only when the form has Turnstile enabled. JSON clients should send Accept: application/json. Native HTML forms receive a 303 redirect on success. A successful JSON response means the submission is durably stored and scheduled, not that email has reached an inbox.",
                "summary": "Submit a form",
                "tags": [
                    "Submissions"
                ],
                "parameters": [
                    {
                        "name": "public_id",
                        "in": "path",
                        "required": true,
                        "description": "Opaque public form identifier. Treat it as an identifier, not an authentication secret.",
                        "schema": {
                            "type": "string",
                            "description": "Opaque public form identifier.",
                            "examples": [
                                "abc123"
                            ]
                        }
                    },
                    {
                        "name": "Accept",
                        "in": "header",
                        "description": "Optional. Use application/json to receive a JSON response. Native HTML submissions receive a 303 redirect.",
                        "schema": {
                            "type": "string",
                            "description": "Optional. Use application/json to receive a JSON response. Native HTML submissions receive a 303 redirect.",
                            "examples": [
                                "application/json"
                            ]
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "description": "Optional key for safe retries. Reuse the same key while the payload is unchanged. Maximum 128 characters.",
                        "schema": {
                            "type": "string",
                            "description": "Optional key for safe retries. Reuse the same key while the payload is unchanged. Maximum 128 characters.",
                            "examples": [
                                "550e8400-e29b-41d4-a716-446655440000"
                            ],
                            "maxLength": 128
                        }
                    },
                    {
                        "name": "Origin",
                        "in": "header",
                        "required": true,
                        "description": "Required. The canonical origin of the customer website. It must be on the form website\u2019s allowlist. Server-side clients must send the same origin explicitly.",
                        "schema": {
                            "type": "string",
                            "description": "Required. The canonical origin of the customer website. It must be on the form website\u2019s allowlist. Server-side clients must send the same origin explicitly.",
                            "examples": [
                                "https://customer-site.example"
                            ]
                        }
                    }
                ],
                "requestBody": {
                    "description": "Customer-defined fields plus optional control fields. Turnstile is conditionally required. Nested objects and file uploads are not supported.",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicSubmissionRequest"
                            },
                            "example": {
                                "name": "John Smith",
                                "email": "john@example.com",
                                "phone": "0400000000",
                                "message": "I would like more information",
                                "cf-turnstile-response": "TURNSTILE_TOKEN"
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicSubmissionRequest"
                            },
                            "example": {
                                "name": "John Smith",
                                "email": "john@example.com",
                                "message": "I would like more information",
                                "_idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicSubmissionRequest"
                            },
                            "example": {
                                "name": "John Smith",
                                "email": "john@example.com",
                                "message": "I would like more information",
                                "_idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Submission accepted and durably stored. It is scheduled for delivery; email has not necessarily reached an inbox.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicSubmissionSuccess"
                                },
                                "example": {
                                    "success": true,
                                    "submission_id": "8f2c1e7a4b6d8c0e5f3a2b1c9d8e7f60",
                                    "message": "Your enquiry has been received."
                                }
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Idempotent replay. The original submission is returned and no duplicate delivery or notification is created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicSubmissionSuccess"
                                },
                                "example": {
                                    "success": true,
                                    "submission_id": "8f2c1e7a4b6d8c0e5f3a2b1c9d8e7f60",
                                    "message": "Your enquiry has been received."
                                }
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "303": {
                        "description": "Native HTML submission accepted. The browser is redirected to the form\u2019s configured HTTPS success URL or the hosted thank-you page.",
                        "headers": {
                            "Location": {
                                "description": "Validated HTTPS success URL or the hosted thank-you page.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "https://example.com/thanks"
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request body was empty, malformed, or structurally unsupported.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "malformed_request",
                                        "message": "The request could not be read."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Origin rejected, Turnstile verification failed, or the honeypot was filled. The response is generic and never echoes payload content.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "verification_failed",
                                        "message": "Verification failed."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The form does not exist, is disabled, or a parent customer or website is disabled.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "form_unavailable",
                                        "message": "This form is not available."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The same idempotency key was previously accepted with a different payload.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "idempotency_conflict",
                                        "message": "This idempotency key was already used with different content."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "413": {
                        "description": "The request exceeded the 64 KiB body limit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "payload_too_large",
                                        "message": "The submitted payload is too large."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "415": {
                        "description": "The content type or payload type is unsupported, including files and nested objects.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "unsupported_media_type",
                                        "message": "The submitted content type is not supported."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "One or more submitted fields failed validation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "validation_failed",
                                        "message": "Check the submitted fields.",
                                        "fields": {
                                            "email": [
                                                "Invalid email address."
                                            ]
                                        }
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "A per-IP, per-form, or global rate limit was exceeded. Retry after the Retry-After interval.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "rate_limited",
                                        "message": "Too many requests. Please try again later."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            },
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "60"
                                    ]
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "An unexpected server error occurred. No internal details are exposed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "internal_error",
                                        "message": "An unexpected error occurred."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "The form is not ready, CAPTCHA verification is temporarily unavailable, or the service cannot safely accept submissions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "temporarily_unavailable",
                                        "message": "The service is temporarily unavailable."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    }
                },
                "security": [],
                "x-postvia": {
                    "canonical": true,
                    "alias": false
                },
                "x-codeSamples": [
                    {
                        "lang": "curl",
                        "label": "cURL",
                        "source": "curl -X POST 'https://api.postvia.dev/v1/forms/abc123/submissions' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json' \\\n  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \\\n  -H 'Origin: https://customer-site.example' \\\n  --data-raw '{\"name\":\"John Smith\",\"email\":\"john@example.com\",\"phone\":\"0400000000\",\"message\":\"I would like more information\",\"cf-turnstile-response\":\"TURNSTILE_TOKEN\"}'"
                    },
                    {
                        "lang": "javascript",
                        "label": "JavaScript",
                        "source": "const response = await fetch('https://api.postvia.dev/v1/forms/abc123/submissions', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    Accept: 'application/json',\n    'Idempotency-Key': crypto.randomUUID(),\n  },\n  body: JSON.stringify({\"name\":\"John Smith\",\"email\":\"john@example.com\",\"phone\":\"0400000000\",\"message\":\"I would like more information\",\"cf-turnstile-response\":\"TURNSTILE_TOKEN\"}),\n})\n\nconst result = await response.json()"
                    },
                    {
                        "lang": "typescript",
                        "label": "TypeScript",
                        "source": "type PostviaSuccess = {\n  success: true\n  submission_id: string\n  message: string\n}\n\ntype PostviaError = {\n  success: false\n  error: { code: string, message: string, fields?: Record<string, string[]> }\n  request_id: string\n}\n\nconst response = await fetch('https://api.postvia.dev/v1/forms/abc123/submissions', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    Accept: 'application/json',\n    'Idempotency-Key': crypto.randomUUID(),\n  },\n  body: JSON.stringify({\"name\":\"John Smith\",\"email\":\"john@example.com\",\"phone\":\"0400000000\",\"message\":\"I would like more information\",\"cf-turnstile-response\":\"TURNSTILE_TOKEN\"}),\n})\n\nconst result = (await response.json()) as PostviaSuccess | PostviaError"
                    },
                    {
                        "lang": "typescript",
                        "label": "Nuxt $fetch",
                        "source": "const response = await $fetch<PostviaSuccess>('https://api.postvia.dev/v1/forms/abc123/submissions', {\n  method: 'POST',\n  headers: {\n    Accept: 'application/json',\n    'Idempotency-Key': crypto.randomUUID(),\n  },\n  body: {\"name\":\"John Smith\",\"email\":\"john@example.com\",\"phone\":\"0400000000\",\"message\":\"I would like more information\",\"cf-turnstile-response\":\"TURNSTILE_TOKEN\"},\n})"
                    }
                ]
            }
        },
        "/f/{public_id}": {
            "options": {
                "operationId": "preflightFormAlias",
                "description": "Handles the CORS preflight for the submission endpoint. The response is 204 and includes CORS headers only for an allowed customer origin.",
                "summary": "Preflight the short alias (CORS)",
                "tags": [
                    "Submissions"
                ],
                "parameters": [
                    {
                        "name": "public_id",
                        "in": "path",
                        "required": true,
                        "description": "Opaque public form identifier. Treat it as an identifier, not an authentication secret.",
                        "schema": {
                            "type": "string",
                            "description": "Opaque public form identifier.",
                            "examples": [
                                "abc123"
                            ]
                        }
                    },
                    {
                        "name": "Origin",
                        "in": "header",
                        "required": true,
                        "description": "Required. The customer website origin.",
                        "schema": {
                            "type": "string",
                            "description": "Required. The customer website origin.",
                            "examples": [
                                "https://customer-site.example"
                            ]
                        }
                    },
                    {
                        "name": "Access-Control-Request-Method",
                        "in": "header",
                        "description": "The method the browser intends to use.",
                        "schema": {
                            "type": "string",
                            "description": "The method the browser intends to use.",
                            "examples": [
                                "POST"
                            ]
                        }
                    },
                    {
                        "name": "Access-Control-Request-Headers",
                        "in": "header",
                        "description": "Headers the browser intends to send.",
                        "schema": {
                            "type": "string",
                            "description": "Headers the browser intends to send.",
                            "examples": [
                                "content-type, accept, idempotency-key"
                            ]
                        }
                    }
                ],
                "responses": {
                    "204": {
                        "description": "CORS preflight accepted.",
                        "headers": {
                            "Access-Control-Allow-Origin": {
                                "description": "The exact allowed origin.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "https://customer-site.example"
                                    ]
                                }
                            },
                            "Access-Control-Allow-Methods": {
                                "description": "Allowed methods.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "POST, OPTIONS"
                                    ]
                                }
                            },
                            "Access-Control-Allow-Headers": {
                                "description": "Allowed request headers.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "Content-Type, Accept, Idempotency-Key"
                                    ]
                                }
                            },
                            "Access-Control-Max-Age": {
                                "description": "Preflight cache lifetime in seconds.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "600"
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "The origin is missing or not on the form website allowlist.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "origin_not_allowed",
                                        "message": "This origin is not allowed."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    }
                },
                "security": []
            },
            "post": {
                "operationId": "submitFormAlias",
                "description": "Short convenience alias for POST /v1/forms/{public_id}/submissions. It shares the same implementation and response contract.\n\nThe request must include an allowed Origin. Turnstile is required only when the form has Turnstile enabled. JSON clients should send Accept: application/json. Native HTML forms receive a 303 redirect on success.",
                "summary": "Submit a form (short alias)",
                "tags": [
                    "Submissions"
                ],
                "parameters": [
                    {
                        "name": "public_id",
                        "in": "path",
                        "required": true,
                        "description": "Opaque public form identifier. Treat it as an identifier, not an authentication secret.",
                        "schema": {
                            "type": "string",
                            "description": "Opaque public form identifier.",
                            "examples": [
                                "abc123"
                            ]
                        }
                    },
                    {
                        "name": "Accept",
                        "in": "header",
                        "description": "Optional. Use application/json to receive a JSON response. Native HTML submissions receive a 303 redirect.",
                        "schema": {
                            "type": "string",
                            "description": "Optional. Use application/json to receive a JSON response. Native HTML submissions receive a 303 redirect.",
                            "examples": [
                                "application/json"
                            ]
                        }
                    },
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "description": "Optional key for safe retries. Reuse the same key while the payload is unchanged. Maximum 128 characters.",
                        "schema": {
                            "type": "string",
                            "description": "Optional key for safe retries. Reuse the same key while the payload is unchanged. Maximum 128 characters.",
                            "examples": [
                                "550e8400-e29b-41d4-a716-446655440000"
                            ],
                            "maxLength": 128
                        }
                    },
                    {
                        "name": "Origin",
                        "in": "header",
                        "required": true,
                        "description": "Required. The canonical origin of the customer website. It must be on the form website\u2019s allowlist. Server-side clients must send the same origin explicitly.",
                        "schema": {
                            "type": "string",
                            "description": "Required. The canonical origin of the customer website. It must be on the form website\u2019s allowlist. Server-side clients must send the same origin explicitly.",
                            "examples": [
                                "https://customer-site.example"
                            ]
                        }
                    }
                ],
                "requestBody": {
                    "description": "Customer-defined fields plus optional control fields. Turnstile is conditionally required. Nested objects and file uploads are not supported.",
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicSubmissionRequest"
                            },
                            "example": {
                                "name": "John Smith",
                                "email": "john@example.com",
                                "phone": "0400000000",
                                "message": "I would like more information",
                                "cf-turnstile-response": "TURNSTILE_TOKEN"
                            }
                        },
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicSubmissionRequest"
                            },
                            "example": {
                                "name": "John Smith",
                                "email": "john@example.com",
                                "message": "I would like more information",
                                "_idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/PublicSubmissionRequest"
                            },
                            "example": {
                                "name": "John Smith",
                                "email": "john@example.com",
                                "message": "I would like more information",
                                "_idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Submission accepted and durably stored. It is scheduled for delivery; email has not necessarily reached an inbox.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicSubmissionSuccess"
                                },
                                "example": {
                                    "success": true,
                                    "submission_id": "8f2c1e7a4b6d8c0e5f3a2b1c9d8e7f60",
                                    "message": "Your enquiry has been received."
                                }
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "200": {
                        "description": "Idempotent replay. The original submission is returned and no duplicate delivery or notification is created.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicSubmissionSuccess"
                                },
                                "example": {
                                    "success": true,
                                    "submission_id": "8f2c1e7a4b6d8c0e5f3a2b1c9d8e7f60",
                                    "message": "Your enquiry has been received."
                                }
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "303": {
                        "description": "Native HTML submission accepted. The browser is redirected to the form\u2019s configured HTTPS success URL or the hosted thank-you page.",
                        "headers": {
                            "Location": {
                                "description": "Validated HTTPS success URL or the hosted thank-you page.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "https://example.com/thanks"
                                    ]
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "The request body was empty, malformed, or structurally unsupported.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "malformed_request",
                                        "message": "The request could not be read."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Origin rejected, Turnstile verification failed, or the honeypot was filled. The response is generic and never echoes payload content.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "verification_failed",
                                        "message": "Verification failed."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "The form does not exist, is disabled, or a parent customer or website is disabled.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "form_unavailable",
                                        "message": "This form is not available."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "The same idempotency key was previously accepted with a different payload.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "idempotency_conflict",
                                        "message": "This idempotency key was already used with different content."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "413": {
                        "description": "The request exceeded the 64 KiB body limit.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "payload_too_large",
                                        "message": "The submitted payload is too large."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "415": {
                        "description": "The content type or payload type is unsupported, including files and nested objects.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "unsupported_media_type",
                                        "message": "The submitted content type is not supported."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "One or more submitted fields failed validation.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "validation_failed",
                                        "message": "Check the submitted fields.",
                                        "fields": {
                                            "email": [
                                                "Invalid email address."
                                            ]
                                        }
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "A per-IP, per-form, or global rate limit was exceeded. Retry after the Retry-After interval.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "rate_limited",
                                        "message": "Too many requests. Please try again later."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            },
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "60"
                                    ]
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "An unexpected server error occurred. No internal details are exposed.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "internal_error",
                                        "message": "An unexpected error occurred."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "The form is not ready, CAPTCHA verification is temporarily unavailable, or the service cannot safely accept submissions.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PublicError"
                                },
                                "example": {
                                    "success": false,
                                    "error": {
                                        "code": "temporarily_unavailable",
                                        "message": "The service is temporarily unavailable."
                                    },
                                    "request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                }
                            },
                            "text/html": {
                                "schema": {
                                    "type": "string",
                                    "description": "Generic, accessible HTML error page. It never echoes private payload content."
                                },
                                "example": "<!doctype html><html lang=\"en\"><body><main><h1>Submission not accepted</h1><p>Check the form and try again.</p></main></body></html>"
                            }
                        },
                        "headers": {
                            "X-Request-Id": {
                                "description": "Request ULID for support and safe operational logs.",
                                "schema": {
                                    "type": "string",
                                    "examples": [
                                        "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                                    ]
                                }
                            }
                        }
                    }
                },
                "security": [],
                "x-postvia": {
                    "canonical": false,
                    "alias": true
                },
                "x-codeSamples": [
                    {
                        "lang": "curl",
                        "label": "cURL",
                        "source": "curl -X POST 'https://api.postvia.dev/f/abc123' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json' \\\n  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \\\n  -H 'Origin: https://customer-site.example' \\\n  --data-raw '{\"name\":\"John Smith\",\"email\":\"john@example.com\",\"phone\":\"0400000000\",\"message\":\"I would like more information\",\"cf-turnstile-response\":\"TURNSTILE_TOKEN\"}'"
                    },
                    {
                        "lang": "javascript",
                        "label": "JavaScript",
                        "source": "const response = await fetch('https://api.postvia.dev/f/abc123', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    Accept: 'application/json',\n    'Idempotency-Key': crypto.randomUUID(),\n  },\n  body: JSON.stringify({\"name\":\"John Smith\",\"email\":\"john@example.com\",\"phone\":\"0400000000\",\"message\":\"I would like more information\",\"cf-turnstile-response\":\"TURNSTILE_TOKEN\"}),\n})\n\nconst result = await response.json()"
                    },
                    {
                        "lang": "typescript",
                        "label": "TypeScript",
                        "source": "type PostviaSuccess = {\n  success: true\n  submission_id: string\n  message: string\n}\n\ntype PostviaError = {\n  success: false\n  error: { code: string, message: string, fields?: Record<string, string[]> }\n  request_id: string\n}\n\nconst response = await fetch('https://api.postvia.dev/f/abc123', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    Accept: 'application/json',\n    'Idempotency-Key': crypto.randomUUID(),\n  },\n  body: JSON.stringify({\"name\":\"John Smith\",\"email\":\"john@example.com\",\"phone\":\"0400000000\",\"message\":\"I would like more information\",\"cf-turnstile-response\":\"TURNSTILE_TOKEN\"}),\n})\n\nconst result = (await response.json()) as PostviaSuccess | PostviaError"
                    },
                    {
                        "lang": "typescript",
                        "label": "Nuxt $fetch",
                        "source": "const response = await $fetch<PostviaSuccess>('https://api.postvia.dev/f/abc123', {\n  method: 'POST',\n  headers: {\n    Accept: 'application/json',\n    'Idempotency-Key': crypto.randomUUID(),\n  },\n  body: {\"name\":\"John Smith\",\"email\":\"john@example.com\",\"phone\":\"0400000000\",\"message\":\"I would like more information\",\"cf-turnstile-response\":\"TURNSTILE_TOKEN\"},\n})"
                    }
                ]
            }
        }
    },
    "components": {
        "schemas": {
            "PublicError": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "const": false
                    },
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string",
                                "description": "Stable machine-readable error code.",
                                "enum": [
                                    "malformed_request",
                                    "origin_not_allowed",
                                    "verification_failed",
                                    "form_unavailable",
                                    "idempotency_conflict",
                                    "payload_too_large",
                                    "unsupported_media_type",
                                    "validation_failed",
                                    "rate_limited",
                                    "internal_error",
                                    "temporarily_unavailable"
                                ],
                                "x-enumDescriptions": {
                                    "malformed_request": "The request body was empty, malformed, or contained unsupported structure.",
                                    "origin_not_allowed": "The request origin is missing or not on the form website\u2019s allowlist.",
                                    "verification_failed": "Turnstile verification failed, the token was invalid or expired, or the honeypot was filled.",
                                    "form_unavailable": "The form does not exist, is disabled, or a parent customer/website is disabled.",
                                    "idempotency_conflict": "The same idempotency key was previously accepted with a different payload.",
                                    "payload_too_large": "The request exceeded the 64 KiB body limit.",
                                    "unsupported_media_type": "The content type or payload type is not supported, including file uploads and nested objects.",
                                    "validation_failed": "One or more submitted fields failed validation. Field-level messages are included.",
                                    "rate_limited": "A per-IP, per-form, or global rate limit was exceeded. Retry after the Retry-After interval.",
                                    "internal_error": "An unexpected server error occurred. No internal details are exposed.",
                                    "temporarily_unavailable": "The form is not ready, CAPTCHA verification is temporarily unavailable, or the service cannot safely accept submissions."
                                }
                            },
                            "message": {
                                "type": "string",
                                "description": "Safe, human-readable error message."
                            },
                            "fields": {
                                "type": "object",
                                "description": "Field-level validation messages. Present only when a validation error can be attributed to fields.",
                                "additionalProperties": {
                                    "type": "array",
                                    "items": {
                                        "type": "string",
                                        "description": "One or more messages for this field."
                                    }
                                }
                            }
                        },
                        "required": [
                            "code",
                            "message"
                        ]
                    },
                    "request_id": {
                        "type": "string",
                        "description": "Request ULID for support and safe operational logs. Also returned in X-Request-Id.",
                        "examples": [
                            "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
                        ]
                    }
                },
                "required": [
                    "success",
                    "error",
                    "request_id"
                ],
                "title": "PublicError"
            },
            "PublicSubmissionRequest": {
                "type": "object",
                "description": "The submission body. Fields are defined by the customer\u2019s form and are validated against that form\u2019s settings. Control fields are stripped before storage and are never delivered by email.",
                "properties": {
                    "name": {
                        "description": "The submitter\u2019s name. Customer-defined; not required unless the form configures it.",
                        "examples": [
                            "John Smith"
                        ]
                    },
                    "email": {
                        "description": "The submitter\u2019s email address. Used as Reply-To when configured on the form.",
                        "examples": [
                            "john@example.com"
                        ]
                    },
                    "phone": {
                        "description": "The submitter\u2019s phone number. Customer-defined.",
                        "examples": [
                            "0400000000"
                        ]
                    },
                    "message": {
                        "description": "The enquiry message. Customer-defined.",
                        "examples": [
                            "I would like more information"
                        ]
                    },
                    "cf-turnstile-response": {
                        "description": "Cloudflare Turnstile token. Required only when Turnstile is enabled for the form.",
                        "examples": [
                            "TURNSTILE_TOKEN"
                        ]
                    },
                    "_honeypot": {
                        "description": "Optional hidden honeypot field. It must be empty. A populated value returns a generic 403 response.",
                        "examples": [
                            ""
                        ]
                    },
                    "_idempotency_key": {
                        "description": "HTML-form alternative to the Idempotency-Key header. Maximum 128 characters and must match the header if both are supplied.",
                        "examples": [
                            "550e8400-e29b-41d4-a716-446655440000"
                        ]
                    }
                },
                "additionalProperties": {
                    "description": "Any customer-defined scalar field or list of scalars. Field names are not fixed by the API. Nested objects and files are not supported."
                },
                "title": "PublicSubmissionRequest"
            },
            "PublicSubmissionSuccess": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "description": "Always true for an accepted submission.",
                        "const": true
                    },
                    "submission_id": {
                        "type": "string",
                        "description": "Opaque receipt identifying the stored submission. Treat it as an identifier, not a secret.",
                        "examples": [
                            "8f2c1e7a4b6d8c0e5f3a2b1c9d8e7f60"
                        ]
                    },
                    "message": {
                        "type": "string",
                        "description": "Human-readable confirmation. The submission is stored and scheduled, not necessarily delivered to an inbox.",
                        "examples": [
                            "Your enquiry has been received."
                        ]
                    }
                },
                "required": [
                    "success",
                    "submission_id",
                    "message"
                ],
                "title": "PublicSubmissionSuccess"
            }
        }
    },
    "x-postvia": {
        "api_version": "v1",
        "primary_endpoint": "/v1/forms/{public_id}/submissions",
        "alias_endpoint": "/f/{public_id}",
        "openapi": "/openapi.json",
        "docs": "http://localhost:8010/docs",
        "admin": "http://localhost:3100",
        "request_id_header": "X-Request-Id",
        "limits": {
            "body_bytes": 65536,
            "body_kib": 64,
            "max_fields": 50,
            "max_key_length": 100,
            "max_value_length": 10000,
            "max_list_items": 20,
            "idempotency_key_max": 128
        },
        "rate_limits": {
            "ip_form_per_minute": 10,
            "ip_global_per_minute": 60,
            "form_per_minute": 120,
            "global_per_minute": 600,
            "preflight_per_minute": 120,
            "retry_after_header": "Retry-After"
        },
        "idempotency": {
            "header": "Idempotency-Key",
            "field": "_idempotency_key",
            "scope": "form",
            "replay_status": 200,
            "conflict_status": 409,
            "retention_days": 90,
            "retention_basis": "Retained on the submission for the form retention period, then removed by the retention purge."
        },
        "turnstile": {
            "enabled_by_default": false,
            "field": "cf-turnstile-response",
            "required_when": "Required only when Turnstile is enabled for the form.",
            "outage_status": 503
        },
        "retention": {
            "default_days": 90,
            "ceiling_days": 365
        },
        "error_codes": [
            {
                "code": "malformed_request",
                "status": 400,
                "description": "The request body was empty, malformed, or contained unsupported structure."
            },
            {
                "code": "origin_not_allowed",
                "status": 403,
                "description": "The request origin is missing or not on the form website\u2019s allowlist."
            },
            {
                "code": "verification_failed",
                "status": 403,
                "description": "Turnstile verification failed, the token was invalid or expired, or the honeypot was filled."
            },
            {
                "code": "form_unavailable",
                "status": 404,
                "description": "The form does not exist, is disabled, or a parent customer/website is disabled."
            },
            {
                "code": "idempotency_conflict",
                "status": 409,
                "description": "The same idempotency key was previously accepted with a different payload."
            },
            {
                "code": "payload_too_large",
                "status": 413,
                "description": "The request exceeded the 64 KiB body limit."
            },
            {
                "code": "unsupported_media_type",
                "status": 415,
                "description": "The content type or payload type is not supported, including file uploads and nested objects."
            },
            {
                "code": "validation_failed",
                "status": 422,
                "description": "One or more submitted fields failed validation. Field-level messages are included."
            },
            {
                "code": "rate_limited",
                "status": 429,
                "description": "A per-IP, per-form, or global rate limit was exceeded. Retry after the Retry-After interval."
            },
            {
                "code": "internal_error",
                "status": 500,
                "description": "An unexpected server error occurred. No internal details are exposed."
            },
            {
                "code": "temporarily_unavailable",
                "status": 503,
                "description": "The form is not ready, CAPTCHA verification is temporarily unavailable, or the service cannot safely accept submissions."
            }
        ]
    }
}