PageHub Forms API
A site's form submissions and the webhooks that deliver them.
Operations 5
GET
/api/v1/sites/{id}/form-webhooks
List the form webhook destinations and whether each has a signing secret
#
A site's form submissions and the webhooks that deliver them.
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/pagehub-dev:pagehub-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: PageHub Forms API
version: 1.0.0
description: 'The public REST API of PageHub, called with a `ph_` API key (`Authorization: Bearer ph_...`), plus the one webhook the platform calls on a white-label tenant''s server (`fetchPage`).
A site is HTML + Liquid files: its pages are files (`pages/*.liquid`), written through the files API; the page routes manage each page''s record (name, slug, SEO, access). Writes land in the site''s draft; `PUT /api/v1/sites/{id}` with `published: true` makes the draft live.
The headless content API (`/api/v1/content/...`) is described by its own document (`GET /api/v1/content/openapi.json`); `GET /api/openapi.json` serves this document with it merged in.
The routes also accept the dashboard''s session cookie from the dashboard itself; only the API key is the public contract.
Every operation carries two extension fields. `x-auth` says who may call it: `api-key` (a `ph_` key), `session-or-key` (the dashboard''s own session, or a key), `optional-key` (public, a key widens what you see), `admin-key` (a platform admin''s key), `session` (the dashboard session only; an API key is refused) or `public`. `x-rate-limit` names the rate-limit rule (see the rate-limiting guide) when the route has one; most routes limit per user, public routes per IP.'
contact:
name: PageHub
url: https://pagehub.dev/developers
servers:
- url: https://pagehub.dev
description: PageHub
security:
- bearerAuth: []
tags:
- name: Forms
description: A site's form submissions and the webhooks that deliver them.
paths:
/api/v1/sites/{id}/submissions:
get:
tags:
- Forms
summary: List a site's form submissions
description: 'The form inbox, newest first, filtered to one state (default `open`). Each row carries its webhook delivery status when the form has a webhook. `formNames` and `summary` ride on the first page. Reading never marks a row read. Visitor details: owner, editor and agency members.'
operationId: listSiteSubmissions
parameters:
- $ref: '#/components/parameters/SiteId'
- name: state
in: query
required: false
schema:
type: string
enum:
- open
- done
- archived
- spam
default: open
description: Inbox state.
- name: formName
in: query
required: false
schema:
type: string
description: Only this form.
- name: q
in: query
required: false
schema:
type: string
description: Matches anywhere in the answers.
- name: cursor
in: query
required: false
schema:
type: string
description: '`nextCursor` of the previous page.'
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
description: Rows per page.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
submissions:
type: array
items:
type: object
additionalProperties: true
properties:
webhook:
type: object
additionalProperties: true
description: '`{ url (origin + path), status: pending|delivered|failed, attempts, lastHttpStatus, lastError, lastAttemptAt, nextAttemptAt, deliveredAt }`.'
hasMore:
type: boolean
nextCursor:
type:
- string
- 'null'
formNames:
type: array
items:
type: string
summary:
type: object
additionalProperties: true
required:
- submissions
- hasMore
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-auth: session-or-key
/api/v1/sites/{id}/submissions/{submissionId}:
parameters:
- $ref: '#/components/parameters/SiteId'
- name: submissionId
in: path
required: true
schema:
type: string
description: A submission's `_id` from the list.
get:
tags:
- Forms
summary: Read one form submission
description: The answers, how the visitor arrived (`attribution`), the notes and state changes (`activity`) and the webhook delivery. Does not mark the row read.
operationId: getSiteSubmission
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
submission:
type: object
additionalProperties: true
properties:
webhook:
type: object
additionalProperties: true
description: '`{ url (origin + path), status: pending|delivered|failed, attempts, lastHttpStatus, lastError, lastAttemptAt, nextAttemptAt, deliveredAt }`.'
required:
- submission
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-auth: session-or-key
/api/v1/sites/{id}/submissions/{submissionId}/webhook:
parameters:
- $ref: '#/components/parameters/SiteId'
- name: submissionId
in: path
required: true
schema:
type: string
description: A submission's `_id` from the list.
post:
tags:
- Forms
summary: Resend a submission's webhook
description: 'Resets the attempts and queues the delivery again from the start, to the form''s current webhook URL. The `submissionId` in the payload never changes. Owners only: a delivery carries the lead''s details to a third party. 409 when the submission has no webhook; 502 when it could not be queued.'
operationId: resendSiteSubmissionWebhook
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
webhook:
type: object
additionalProperties: true
description: '`{ url (origin + path), status: pending|delivered|failed, attempts, lastHttpStatus, lastError, lastAttemptAt, nextAttemptAt, deliveredAt }`.'
required:
- webhook
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: This submission has no webhook delivery.
'429':
$ref: '#/components/responses/RateLimited'
'502':
description: The resend could not be queued.
content:
application/json:
schema:
type: object
properties:
error:
type: string
'503':
$ref: '#/components/responses/Maintenance'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
/api/v1/sites/{id}/form-webhooks:
parameters:
- $ref: '#/components/parameters/SiteId'
get:
tags:
- Forms
summary: List the form webhook destinations and whether each has a signing secret
description: The destinations the forms on the LIVE release post to (URL without its query string), with the forms that use each. A secret is never returned. Owners only.
operationId: listSiteFormWebhooks
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
destinations:
type: array
items:
type: object
properties:
endpoint:
type: string
url:
type: string
forms:
type: array
items:
type: string
hasSecret:
type: boolean
rotatedAt:
type:
- string
- 'null'
required:
- destinations
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-auth: session-or-key
post:
tags:
- Forms
summary: Rotate or set a form webhook's signing secret
description: '`rotate` mints a new secret and returns it ONCE; `set` stores the secret the receiver issued (16 to 256 characters, no spaces) and returns nothing. `endpoint` is the key the list returned: the URL never comes from the caller. Receivers verify `X-PageHub-Signature: sha256=.">`. Owners only.'
operationId: changeSiteFormWebhookSecret
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
endpoint:
type: string
action:
type: string
enum:
- rotate
- set
secret:
type: string
required:
- endpoint
- action
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
secret:
type: string
description: Only for `rotate`.
ok:
type: boolean
description: Only for `set`.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'503':
$ref: '#/components/responses/Maintenance'
x-auth: session-or-key
x-rate-limit: dashboard_settings_save
components:
parameters:
SiteId:
name: id
in: path
required: true
schema:
type: string
description: The site's id.
responses:
Unauthorized:
description: Missing, malformed or invalid `ph_` API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
BadRequest:
description: The request is malformed or refused (`error`, often `message`).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Forbidden:
description: The key's user lacks the role this needs, or a plan limit applies.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
NotFound:
description: No such site, or the key has no access to it, or no such resource under it.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
RateLimited:
description: Too many requests.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
Maintenance:
description: 'Writes are paused for maintenance (`error: maintenance`, `Retry-After` header).'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
schemas:
ApiError:
type: object
description: The error body of the management routes. The content API uses `Error` instead.
properties:
error:
type: string
description: A message, or a code such as `version_conflict`, `lint`, `maintenance`, `site_format_changed`.
message:
type: string
code:
type: string
upgrade:
type: boolean
description: True when the plan is the reason.
required:
- error
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: A `ph_` API key (a user's key, or a tenant's).
tenantAuthToken:
type: apiKey
in: header
name: x-pagehub-auth
description: The tenant's token, sent by PageHub on every webhook call so the tenant can check the request came from PageHub.