Skip to content
Documentation

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

Prompt
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 the X-Vorx-Project-Id header instead.
  • _vorx_form: which form this is, up to 64 characters. Submissions are grouped by it. The default is default. 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: 200 with {"ok": true, "spam": false, "redirect": "/thanks"}. redirect is null when you did not set one.
  • No project id, or one Vorx does not recognise: 400 with {"ok": false, "error": "This form isn’t linked to a project yet."}
  • Too many submissions: 429, with a Retry-After header in seconds.
  • Could not be saved: 200 with {"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.json checks the key. It returns the key owner's email, name, companyId and companyName.
  • projects.json lists the projects the key can see: {"projects": [{"id", "name"}]}.
  • forms.json lists one project's forms: {"forms": [{"id", "name"}]}.
  • submissions.json lists 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 called email is email. Vorx's own details start with _: _form, _project, _submittedAt and _status.
  • Polling: use id to 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-After time, 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/mcp and …/oauth-protected-resource/builder/mcp, and each of those names its own address as the resource.

Both are public and can be cached for 5 minutes.

Register a client

Prompt
POST /oauth/register
Content-Type: application/json

This is dynamic client registration (RFC 7591).

  • redirect_uris (required): 1 to 10 addresses. Each must be https, or http on 127.0.0.1, localhost or [::1].
  • token_endpoint_auth_method: none (the default), client_secret_post or client_secret_basic.
  • grant_types: must include authorization_code, and may add refresh_token.
  • response_types: ["code"].
  • client_name: up to 100 characters. client_uri and logo_uri are optional and must be https.

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 429 with a Retry-After header.
  • 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 503 with temporarily_unavailable. Try again later.

Authorize

Prompt
GET /oauth/authorize
  ?response_type=code
  &client_id=…
  &redirect_uri=…
  &code_challenge=…
  &code_challenge_method=S256
  &state=…
  • PKCE with S256 is required.
  • scope has 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, state and iss when they allowed it;
  • with error=access_denied when 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

Prompt
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, with code, redirect_uri and code_verifier. A code works once, for 10 minutes.
  • grant_type=refresh_token, with refresh_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

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