API overview
The public Postvia submission API, its base URL and response modes.
The public API accepts customer-defined form submissions over HTTPS. It is unauthenticated by design; the form public ID is an identifier, not a credential.
Authentication
There is no authentication header, token or session. The public API uses security: [] in OpenAPI. Form public IDs identify forms but are not credentials; origin allowlists, Turnstile and rate limits protect the endpoint.
Base URL
https://api.postvia.dev
Primary endpoint
POST /v1/forms/{public_id}/submissions
Short alias
POST /f/{public_id}
Both endpoints share one implementation and one response contract. Use the versioned endpoint for new integrations.
Supported request types
application/jsonapplication/x-www-form-urlencodedmultipart/form-datawith text fields only
Files and nested objects are rejected. The maximum body size is 64 KiB.
Response modes
JSON clients receive JSON. Native HTML forms receive a 303 redirect after durable acceptance.
| Client | Success | Failure |
|---|---|---|
JSON body or Accept: application/json | 201 with receipt | JSON error |
| Native HTML form | 303 redirect | Generic HTML error page |
Explore
- Submit form — complete endpoint reference.
- Request headers — Origin, Accept and idempotency.
- Request body — dynamic fields and limits.
- Error codes — stable machine-readable errors.
- Rate limits — limits and retry behaviour.
- Idempotency — safe retries.
- Security and spam protection — Turnstile, CORS and origin rules.
- OpenAPI JSON — machine-readable specification.