Reference
Endpoints for forms and AI assistants
The public endpoints your site's forms, form-submission feeds and MCP clients call: what to send, the limits, and what comes back.
Most people never call these endpoints directly: forms on a site Vorx built already post to the first one, and AI assistants find the rest by themselves. This page is the reference for when you write your own form, or build an MCP client.
For your app's data, use the Vorx API. To connect an assistant, see Connect Claude and other AI assistants.
All endpoints are on https://www.vorx.com.
Form submissions
POST https://www.vorx.com/services/forms/submit
Your site's visitors call this, so it needs no key. Rate limits, size limits and a spam trap protect it instead.
Send the form as application/x-www-form-urlencoded, multipart/form-data (fields only, no files) or JSON. Every field whose name does not start with _ is saved as the submission. Repeated fields, such as a multi-select, are joined into one value.
Special fields
_vorx_project(required): your project's id. You can send it as theX-Vorx-Project-Idheader instead._vorx_form: which form this is, up to 64 characters. Submissions are grouped by it. The default isdefault. You can also pass it as?f=on the URL._redirect: where to send the visitor afterwards. It must be a path on your site, like/thanks, or an address on the same site. Anything else is ignored._vorx_hp: a hidden field for catching bots. Leave it empty. A submission that fills it in is saved as spam and does not send an email.
Limits
- 32 fields and 16 KB of field data per submission. Fields past either limit are dropped.
- 8,192 characters per value. A longer value is cut to that length.
- 10 submissions a minute per site, and 5 a minute per visitor.
Responses
When the request's Accept header includes text/html, which is what a plain HTML form sends, the visitor gets a page: a redirect to _redirect if you set one, otherwise a thank-you page. Otherwise the reply is JSON:
- Saved:
200with{"ok": true, "spam": false, "redirect": "/thanks"}.redirectisnullwhen you did not set one. - No project id, or one Vorx does not recognise:
400with{"ok": false, "error": "This form isn’t linked to a project yet."} - Too many submissions:
429, with aRetry-Afterheader in seconds. - Could not be saved:
200with{"ok": false, "error": "…"}.
Check ok, not only the status code. A save that fails still answers 200, so a visitor never sees a server error page.
Each saved submission (spam excepted) is emailed to the form's notification addresses, or to the project owner when none are set, and appears under the project's Forms.
Reading form submissions with an API key
These four read-only endpoints let a polling tool, such as a Zapier integration or your own script, collect new form submissions. They use a personal API key, sent as a Bearer token:
Authorization: Bearer vorx_api_your_key_here
The key sees the projects its owner can open in Vorx, no more.
GET /services/zapier/me.json
GET /services/zapier/projects.json
GET /services/zapier/projects/{projectId}/forms.json
GET /services/zapier/projects/{projectId}/forms/{formId}/submissions.json
me.jsonchecks the key. It returns the key owner'semail,name,companyIdandcompanyName.projects.jsonlists the projects the key can see:{"projects": [{"id", "name"}]}.forms.jsonlists one project's forms:{"forms": [{"id", "name"}]}.submissions.jsonlists one form's submissions:{"submissions": […]}.
Submissions
- Order: newest first.
- How many: at most 100.
- Spam: left out.
- Fields: each submission's own fields sit at the top level next to
id, so a field calledemailisemail. Vorx's own details start with_:_form,_project,_submittedAtand_status. - Polling: use
idto tell new submissions from ones you have already seen. - Who can read them: only someone who can edit the project. Anyone else is refused with 403 and
Form entries are visible to project editors only.
Errors
Every error is JSON with an error message you can show to a person:
- 401: the key is missing, unknown or revoked, or its person or workspace is no longer active.
- 404: the project or form is not one this key can see.
- 429: more than 25 requests a minute from one key. Wait for the
Retry-Aftertime, in seconds. - 500: the request could not be answered. Try again.
AI assistants (MCP): OAuth
The Vorx MCP server at https://www.vorx.com/mcp is protected by OAuth 2.1. An assistant that follows the MCP authorization spec discovers everything below by itself. You only need this section if you are writing a client.
Discovery
GET /.well-known/oauth-authorization-server: the authorization server's metadata (RFC 8414).GET /.well-known/oauth-protected-resource: the MCP server's metadata (RFC 9728). It is also served at…/oauth-protected-resource/mcpand…/oauth-protected-resource/builder/mcp, and each of those names its own address as theresource.
Both are public and can be cached for 5 minutes.
Register a client
POST /oauth/register
Content-Type: application/json
This is dynamic client registration (RFC 7591).
redirect_uris(required): 1 to 10 addresses. Each must behttps, orhttpon127.0.0.1,localhostor[::1].token_endpoint_auth_method:none(the default),client_secret_postorclient_secret_basic.grant_types: must includeauthorization_code, and may addrefresh_token.response_types:["code"].client_name: up to 100 characters.client_uriandlogo_uriare optional and must behttps.
The reply is 201 with your client_id, and a client_secret if you chose a secret method. The secret does not expire.
Registration is limited:
- 10 requests a minute from one IP address. Over that, the reply is
429with aRetry-Afterheader. - 20 clients an hour from one IP address, and 500 an hour across Vorx. Over either, the reply is
429. - If Vorx cannot count recent registrations, it registers nothing and replies
503withtemporarily_unavailable. Try again later.
Authorize
GET /oauth/authorize
?response_type=code
&client_id=…
&redirect_uri=…
&code_challenge=…
&code_challenge_method=S256
&state=…
- PKCE with
S256is required. scopehas one value,mcp.resource, if you send it, must be the Vorx MCP server.
The person signs in to Vorx if they need to, picks the workspace to connect, and chooses Allow or Deny. Their browser then goes back to your redirect_uri:
- with
code,stateandisswhen they allowed it; - with
error=access_deniedwhen they did not.
If the client_id is unknown, or the redirect_uri was not registered, Vorx shows an error page and does not redirect.
Get tokens
POST /oauth/token
Send the request form-encoded or as JSON. A client with a secret authenticates with it (client_secret_basic or client_secret_post). A public client sends its client_id.
grant_type=authorization_code, withcode,redirect_uriandcode_verifier. A code works once, for 10 minutes.grant_type=refresh_token, withrefresh_token.
The reply:
{
"access_token": "…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "…",
"scope": "mcp"
}
Tokens and reuse:
- An access token lasts 1 hour.
- A refresh token lasts 30 days and is replaced every time you use it, so store the new one each time.
- Using a code or a refresh token a second time ends the connection. The person then has to connect again.
Errors follow OAuth's JSON shape, {"error": "…", "error_description": "…"}:
invalid_client:401.invalid_grant,invalid_request,invalid_target,unsupported_grant_type:400.server_error:500. Try again.
Revoke
POST /oauth/revoke
Send token=…, with the same client authentication as /oauth/token (RFC 7009). Revoking either token ends the connection it belongs to.
The reply is 200 even for a token Vorx does not recognise. A 503 means the revoke could not be recorded, so try again.
Security reports
Our security contact and disclosure policy are at https://www.vorx.com/.well-known/security.txt.