PageWeave Forms API
Forms and their versioned field definitions.
Forms and their versioned field definitions.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/pageweave-dev:pageweave-dev-forms-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: PageWeave Forms API
version: 1.0.0
summary: Programmatic control plane for PageWeave websites.
description: 'Version 1 of the PageWeave HTTP API. Every endpoint under `/api/v1`
authenticates with a bearer API key unless its operation declares an
anonymous alternative — `security: []` or an optional requirement such as
`[{bearerAuth: []}, {}]` for upload sessions.
Errors use RFC 9457 Problem Details (`application/problem+json`). Rate
limits follow draft-ietf-httpapi-ratelimit-headers-11 and are reported on
every authenticated response through the `RateLimit-Policy` and
`RateLimit` headers.
The contract is additive within v1: operations and response fields may be
added, never removed or changed incompatibly.'
contact:
name: PageWeave
url: https://pageweave.dev/docs/api
externalDocs:
description: Guide, authentication, pagination, errors, and worked examples.
url: https://pageweave.dev/docs/api/guide
servers:
- url: https://pageweave.dev
description: Production
tags:
- name: Forms
description: Forms and their versioned field definitions.
paths:
/api/v1/websites/{website_id}/forms:
parameters:
- name: website_id
in: path
required: true
description: Website UUID or subdomain.
schema:
type: string
get:
operationId: listForms
summary: List forms
description: 'Keyset-paginated form summaries. Version fields are omitted from list
rows; use `getForm` for the latest field definitions and settings.
Recipient and notification fields are not part of this API.'
tags:
- Forms
security:
- bearerAuth: []
x-required-permission: form.read
x-required-scope: website
x-required-credential: read
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: A page of forms
content:
application/json:
schema:
$ref: '#/components/schemas/FormsCollection'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: createForm
summary: Create a form with its first version
tags:
- Forms
security:
- bearerAuth: []
x-required-permission: form.create
x-required-scope: website
x-required-credential: write
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FormCreateRequest'
example:
name: Contact
fields:
- name: email
type: email
required: true
label: Email
- name: message
type: textarea
required: true
label: Message
success_message: Thanks — we will reply within one business day.
spam_protection: code
confirmation_email:
enabled: true
to_field: email
subject: We received your message
body: Thanks for contacting {{website_name}}. We will reply within one business day.
reply_to: hello@studio-north.test
responses:
'201':
description: The form and its first version
headers:
Location:
$ref: '#/components/headers/Location'
ETag:
$ref: '#/components/headers/ETag'
Last-Modified:
$ref: '#/components/headers/LastModified'
content:
application/json:
schema:
$ref: '#/components/schemas/FormDetail'
example:
id: 019fc8a1-4b2d-7c3e-8f51-0a9b8c7d6e5f
name: Contact
version_count: 1
latest_version_number: 1
submit_url: https://studio-north.pageweave.site/forms/019fc8a1-4b2d-7c3e-8f51-0a9b8c7d6e5f/submissions
created_at: '2026-11-02T10:40:27Z'
updated_at: '2026-11-02T10:40:27Z'
fields:
- name: email
type: email
required: true
label: Email
- name: message
type: textarea
required: true
label: Message
success_message: Thanks — we will reply within one business day.
redirect_path: null
spam_protection: standard
recipient_summary:
recipient_count: 0
pending_count: 0
deliverable_count: 0
blocked_count: 0
health: no_recipients
alertable: true
confirmation_email:
enabled: false
to_field: null
subject: null
body: null
reply_to: null
email_verification_field: null
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'422':
$ref: '#/components/responses/Unprocessable'
'429':
$ref: '#/components/responses/TooManyRequests'
/api/v1/websites/{website_id}/forms/{id}:
parameters:
- name: website_id
in: path
required: true
description: Website UUID or subdomain.
schema:
type: string
- name: id
in: path
required: true
description: Form UUID.
schema:
type: string
format: uuid
get:
operationId: getForm
summary: Get a form
tags:
- Forms
security:
- bearerAuth: []
x-required-permission: form.read
x-required-scope: website
x-required-credential: read
parameters:
- $ref: '#/components/parameters/IfNoneMatch'
responses:
'200':
description: The form with its latest version
headers:
ETag:
$ref: '#/components/headers/ETag'
Last-Modified:
$ref: '#/components/headers/LastModified'
content:
application/json:
schema:
$ref: '#/components/schemas/FormDetail'
'304':
$ref: '#/components/responses/NotModified'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
patch:
operationId: updateForm
summary: Update a form
description: 'Updates the name and/or publishes a new form version. A supplied
`fields` or versioned setting creates a version; a name-only update
does not. Omitted versioned fields inherit the latest version; null or
an empty string clears `success_message`, `redirect_path`, or
`spam_protection`. `notification_email` is not accepted — recipient
management belongs to the notification subscription surface.'
tags:
- Forms
security:
- bearerAuth: []
x-required-permission: form.update
x-required-scope: website
x-required-credential: write
parameters:
- $ref: '#/components/parameters/IfMatch'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FormUpdateRequest'
responses:
'200':
description: The updated form
headers:
ETag:
$ref: '#/components/headers/ETag'
Last-Modified:
$ref: '#/components/headers/LastModified'
content:
application/json:
schema:
$ref: '#/components/schemas/FormDetail'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'412':
$ref: '#/components/responses/PreconditionFailed'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'422':
$ref: '#/components/responses/Unprocessable'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
operationId: deleteForm
summary: Delete a form
description: 'Permanently deletes the form, its versions, and every submission and
upload belonging to it. Embedded `/f/{version_id}` URLs stop working.'
tags:
- Forms
security:
- bearerAuth: []
x-required-permission: form.delete
x-required-scope: website
x-required-credential: write
parameters:
- $ref: '#/components/parameters/IfMatch'
responses:
'204':
$ref: '#/components/responses/NoContent'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'412':
$ref: '#/components/responses/PreconditionFailed'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
headers:
RetryAfter:
description: Seconds to wait before retrying.
schema:
type: integer
ETag:
description: Strong validator for the current representation.
schema:
type: string
Location:
description: Canonical URL of the created or affected resource.
schema:
type: string
format: uri
LastModified:
description: Last modification time (HTTP-date).
schema:
type: string
WWWAuthenticate:
description: 'Bearer challenge (RFC 9110 §11.6.1, RFC 6750 §3).
Carries `error="invalid_token"` when a credential was presented but
could not be resolved. `/api/v1` uses the `api` realm; OAuth
protected-resource metadata (RFC 9728) is advertised by MCP only.
'
schema:
type: string
example: Bearer realm="api", error="invalid_token"
RateLimitPolicy:
description: 'The applicable quota policy (draft-ietf-httpapi-ratelimit-headers-11).
'
schema:
type: string
example: '"write";q=120;w=60'
RateLimit:
description: 'The remaining quota and seconds until the window resets
(draft-ietf-httpapi-ratelimit-headers-11).
'
schema:
type: string
example: '"write";r=119;t=42'
schemas:
FormConfirmationEmail:
type: object
additionalProperties: false
description: 'The form''s visitor confirmation email configuration, raw as stored.
Empty subject/body fall back to localized platform copy; the
rendered default is not frozen into the API.
'
required:
- enabled
- to_field
- subject
- body
- reply_to
properties:
enabled:
type: boolean
to_field:
type:
- string
- 'null'
description: Name of the form's email field that receives the receipt.
subject:
type:
- string
- 'null'
description: Single line; may contain the documented {{placeholders}}.
body:
type:
- string
- 'null'
description: Plain text; may contain the documented {{placeholders}} and newlines; a blank line starts a paragraph.
reply_to:
type:
- string
- 'null'
format: email
FormField:
type: object
additionalProperties: false
required:
- name
- type
description: 'One form field definition. The domain validator is authoritative for
conditional rules (file-only keys, options for select/radio/checkbox,
`max_files` requiring `multiple`).
'
properties:
name:
type: string
pattern: ^[A-Za-z0-9_-]+$
type:
type: string
enum:
- text
- email
- textarea
- select
- checkbox
- radio
- number
- url
- tel
- search
- range
- color
- date
- datetime-local
- time
- month
- week
- hidden
- file
required:
type: boolean
label:
type: string
minLength: 1
placeholder:
type: string
minLength: 1
options:
type: array
items:
type: string
minLength: 1
multiple:
type: boolean
description: File fields only.
accept:
type: array
description: File fields only. Allowed extensions.
items:
type: string
enum:
- jpg
- jpeg
- png
- gif
- webp
- avif
- pdf
- doc
- docx
- xls
- xlsx
- ppt
- pptx
- txt
- csv
- rtf
max_size_mb:
type: integer
minimum: 1
maximum: 25
description: File fields only.
max_files:
type: integer
minimum: 1
maximum: 10
description: File fields only. Requires `multiple`.
FormConfirmationEmailInput:
type: object
additionalProperties: false
description: 'Partial update: omitted fields keep their stored value; explicit null
clears that value. Sending `null` instead of the object clears the
whole configuration (enabled false, all values null). While enabled,
live submissions resolve to at least the `code` spam-protection tier
and preview surfaces never send the receipt.
'
properties:
enabled:
type: boolean
to_field:
type:
- string
- 'null'
subject:
type:
- string
- 'null'
maxLength: 200
description: Single line; may contain the documented {{placeholders}}.
body:
type:
- string
- 'null'
maxLength: 5000
description: Plain text; may contain the documented {{placeholders}} and newlines; a blank line starts a paragraph.
reply_to:
type:
- string
- 'null'
format: email
FormCreateRequest:
type: object
additionalProperties: false
required:
- name
- fields
description: 'A form''s initial name and field definitions. `notification_email` is
not a form field; recipient management is a separate notification
surface.
'
properties:
name:
type: string
fields:
type: array
minItems: 1
items:
$ref: '#/components/schemas/FormField'
success_message:
type:
- string
- 'null'
redirect_path:
type:
- string
- 'null'
spam_protection:
type:
- string
- 'null'
enum:
- standard
- code
- strict
- null
description: Stored tier. A form with the confirmation email enabled resolves to at least `code`.
confirmation_email:
oneOf:
- $ref: '#/components/schemas/FormConfirmationEmailInput'
- type: 'null'
email_verification_field:
type:
- string
- 'null'
description: 'Name of the required email field the visitor must prove. Set =
double opt-in enabled; null/omitted = off. Requires
`spam_protection` code or strict. The receipt for a verified
submission goes to this address.
'
Problem:
type: object
example:
type: https://pageweave.dev/errors/forbidden
title: Forbidden
status: 403
detail: The API key lacks the page.create permission for this website.
instance: /api/v1/websites/019f9c2a-6a1b-7a3d-8f2e-4b6c8d0e1f23/pages
request_id: 019fc8e5-8f6a-9b7c-8d85-4f6a7b8c9d0e
required_permission: page.create
required_permission_scope: website
required_credential_scope: write
required:
- type
- title
- status
- instance
properties:
type:
type: string
format: uri
title:
type: string
status:
type: integer
detail:
type: string
instance:
type: string
request_id:
type:
- string
- 'null'
errors:
type: array
items:
type: object
additionalProperties: false
required:
- field
- detail
properties:
field:
type: string
detail:
type: string
code:
type: string
upgrade_url:
type: string
required_permission:
type:
- string
- 'null'
description: Declared endpoint permission; null for account-level endpoints with no resource permission.
required_permission_scope:
type:
- string
- 'null'
description: Scope the permission resolves in (workspace, website, environment); null when there is no resource permission.
required_credential_scope:
type:
- string
- 'null'
description: The read/write scope the presented bearer credential lacks; present on credential-ceiling 403s.
retry_after_seconds:
type: integer
minimum: 1
description: Seconds until the quota resets (RFC 9457 extension member, on too-many-requests only). Authoritative over retry_at when clocks differ.
retry_at:
type: string
format: date-time
description: UTC "not before" timestamp — when the quota window ends (RFC 9457 extension member, on too-many-requests only).
suggested_path:
type: string
description: First free path for a restore whose original path is taken, when one can be suggested (RFC 9457 extension member; nothing is renamed automatically).
template_pages:
type: array
description: Live template pages that reference a table whose deletion was refused (RFC 9457 extension member).
items:
type: object
additionalProperties: false
required:
- id
- path
properties:
id:
type: string
format: uuid
path:
type: string
conflicts:
type: array
description: Release items edited by someone else after the caller's last edit (RFC 9457 extension member).
items:
type: object
additionalProperties: false
required:
- type
- identifier
- mine_version
- latest_version
- latest_author
properties:
type:
type: string
identifier:
type: string
mine_version:
type: integer
latest_version:
type: integer
latest_author:
type:
- string
- 'null'
matches:
type: array
description: Candidate short ids for an ambiguous feedback reference (RFC 9457 extension member).
items:
type: string
items:
type: array
description: Identifiers that made a release selection invalid (RFC 9457 extension member).
items:
type: string
nameservers:
type: array
description: Live parent NS answer that still delegates a zone to PageWeave, sent with a refused zone deletion (RFC 9457 extension member).
items:
type: string
existing_id:
type: string
format: uuid
description: Identifier of the existing resource that caused a conflict, such as a pending invitation (RFC 9457 extension member).
FormUpdateRequest:
type: object
additionalProperties: false
minProperties: 1
description: 'Supplying `fields` or a versioned setting creates a form version.
Omitting a versioned setting inherits the latest version; null or an
empty string clears it. `notification_email` is not accepted.
'
properties:
name:
type: string
fields:
type: array
minItems: 1
items:
$ref: '#/components/schemas/FormField'
success_message:
type:
- string
- 'null'
redirect_path:
type:
- string
- 'null'
spam_protection:
type:
- string
- 'null'
enum:
- standard
- code
- strict
- null
description: Stored tier. A form with the confirmation email enabled resolves to at least `code`.
confirmation_email:
oneOf:
- $ref: '#/components/schemas/FormConfirmationEmailInput'
- type: 'null'
email_verification_field:
type:
- string
- 'null'
description: 'Name of the required email field the visitor must prove. Full-value
replacement in a new version; null or an empty string disables it.
Omitted keeps the latest version''s value. Requires
`spam_protection` code or strict. While it is set, the receipt
recipient is this field.
'
FormsCollection:
type: object
additionalProperties: false
required:
- data
- pagination
properties:
data:
type: array
items:
$ref: '#/components/schemas/FormSummary'
pagination:
$ref: '#/components/schemas/Pagination'
Pagination:
type: object
additionalProperties: false
required:
- limit
- has_more
- next_cursor
properties:
limit:
type: integer
minimum: 0
has_more:
type: boolean
next_cursor:
type:
- string
- 'null'
FormRecipientSummary:
type: object
additionalProperties: false
description: 'Delivery health derived from the form''s recipients, the same verdict
the dashboard and MCP report.
'
required:
- recipient_count
- pending_count
- deliverable_count
- blocked_count
- health
- alertable
properties:
recipient_count:
type: integer
minimum: 0
pending_count:
type: integer
minimum: 0
deliverable_count:
type: integer
minimum: 0
blocked_count:
type: integer
minimum: 0
health:
type: string
enum:
- ok
- webhook_only
- opted_out
- pending_only
- no_recipients
- all_blocked
- delivery_failing
alertable:
type: boolean
FormSummary:
type: object
additionalProperties: false
required:
- id
- name
- version_count
- latest_version_number
- submit_url
- created_at
- updated_at
properties:
id:
type: string
format: uuid
name:
type: string
version_count:
type: integer
minimum: 0
latest_version_number:
type:
- integer
- 'null'
submit_url:
type:
- string
- 'null'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
FormDetail:
type: object
additionalProperties: false
required:
- id
- name
- version_count
- latest_version_number
- submit_url
- created_at
- updated_at
- fields
- success_message
- redirect_path
- spam_protection
- recipient_summary
- confirmation_email
- email_verification_field
properties:
id:
type: string
format: uuid
name:
type: string
version_count:
type: integer
minimum: 0
latest_version_number:
type:
- integer
- 'null'
submit_url:
type:
- string
- 'null'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
fields:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/FormField'
success_message:
type:
- string
- 'null'
redirect_path:
type:
- string
- 'null'
spam_protection:
type:
- string
- 'null'
enum:
- standard
- code
- strict
- null
recipient_summary:
$ref: '#/components/schemas/FormRecipientSummary'
confirmation_email:
$ref: '#/components/schemas/FormConfirmationEmail'
email_verification_field:
type:
- string
- 'null'
description: 'Name of the required email field the visitor must prove. Null =
verification off. When set, `spam_protection` must be `code` or
`strict`, and the named field must exist with `type: email` and
`required: true`. The visitor receipt is sent to the verified
address — after confirmation, never before — and an explicit
`confirmation_email.to_field` must name the same field.
'
parameters:
IdempotencyKey:
name: Idempotency-Key
in: header
required: false
description: 'Replay-safe key for POST, including bodyless action POSTs such as
revert (1-255 printable ASCII characters,
draft-ietf-httpapi-idempotency-key-header-08). A replay returns the
stored response with `Idempotent-Replayed: true`.
Responses up to 64 KB are stored and replayed in full. Larger responses
keep only status and headers; their replay is bodyless and carries
`Idempotent-Replay-Body-Omitted: true` (follow `Location`). Each user
may hold 10,000 unexpired records across credentials; a new key past
the cap returns 429 with `Retry-After`, while an existing key still
replays.
'
schema:
type: string
minLength: 1
maxLength: 255
IfMatch:
name: If-Match
in: header
required: false
description: 'Strong validator for optimistic concurrency. A stale value fails with
412 (RFC 9110 §13.1.1).
'
schema:
type: string
Limit:
name: limit
in: query
required: false
description: Page size (1-100, default 25).
schema:
type: integer
minimum: 1
maximum: 100
default: 25
Cursor:
name: cursor
in: query
required: false
description: Opaque keyset cursor from the previous page's `pagination.next_cursor`.
schema:
type: string
IfNoneMatch:
name: If-None-Match
in: header
required: false
description: 'Revalidate a cached representation; a matching value answers 304
without a body (RFC 9110 §13.1.2).
'
schema:
type: string
responses:
UnsupportedMediaType:
description: Request bodies must use application/json
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
TooManyRequests:
description: A rate limit was exceeded
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
RateLimit-Policy:
$ref: '#/components/headers/RateLimitPolicy'
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
Unauthorized:
description: Missing, invalid, expired, or revoked credential
headers:
WWW-Authenticate:
$ref: '#/components/headers/WWWAuthenticate'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
Unprocessable:
description: The payload could not be processed
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
BadRequest:
description: The request is malformed or carries unknown query parameters
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
NotFound:
description: The resource does not exist or is not visible to this caller
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
Forbidden:
description: The session, credential, or role does not permit the action
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
NoContent:
description: The action succeeded and has no body
PreconditionFailed:
description: If-Match did not match the current representation
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
NotModified:
description: The representation has not changed
headers:
ETag:
$ref: '#/components/headers/ETag'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'API key created in Settings → API keys. Send
`Authorization: Bearer pagew_...`. A key''s scopes (`read`, `write`) are
a ceiling: a read-only key cannot write even when its owner''s role
allows it.
'