PageHub Components library API
The shared component library (blocks stored as Liquid).
The shared component library (blocks stored as Liquid).
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-components-library-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 Components library 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: Components library
description: The shared component library (blocks stored as Liquid).
paths:
/api/v1/components:
get:
tags:
- Components library
summary: Search the component library
description: 'Public blocks; with a key, also the caller''s own. The Liquid `source` is left out: read one block for it.'
operationId: listLibraryComponents
parameters:
- name: q
in: query
required: false
schema:
type: string
description: Full-text search.
- name: tag
in: query
required: false
schema:
type: string
- name: featured
in: query
required: false
schema:
const: 'true'
- name: sort
in: query
required: false
schema:
type: string
enum:
- popular
- newest
- name
- relevance
default: popular
description: '`relevance` needs `q`.'
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
default: 1
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: category
in: query
required: false
schema:
type: string
description: Comma-separated for several.
- name: categories
in: query
required: false
schema:
type: string
- name: subcategory
in: query
required: false
schema:
type: string
- name: preset
in: query
required: false
schema:
type: string
- name: source
in: query
required: false
schema:
type: string
- name: group
in: query
required: false
schema:
type: string
- name: style
in: query
required: false
schema:
type: string
description: Comma-separated for several.
- name: styles
in: query
required: false
schema:
type: string
- name: blockType
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
components:
type: array
items:
$ref: '#/components/schemas/LibraryComponent'
total:
type: integer
page:
type: integer
pages:
type: integer
required:
- components
- total
'401':
$ref: '#/components/responses/Unauthorized'
x-auth: optional-key
security:
- {}
- bearerAuth: []
post:
tags:
- Components library
summary: Add a block to the library
description: A block is its Liquid `source` (sanitized and linted like a site file). Only platform admins can publish one (`isPublic`) or mark it a category preview.
operationId: createLibraryComponent
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
slug:
type: string
description:
type: string
visual:
type: string
category:
type: string
subcategory:
type: string
tags:
type: array
items:
type: string
preset:
type: string
group:
type: string
style:
type: string
styles:
type: array
items:
type: string
isPublic:
type: boolean
isCategoryPreview:
type: boolean
source:
type: string
description: The block's Liquid.
required:
- name
- slug
- category
- source
responses:
'201':
description: Created
content:
application/json:
schema:
type: object
properties:
component:
$ref: '#/components/schemas/LibraryComponent'
required:
- component
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: A conflict (`error` says which).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'422':
$ref: '#/components/responses/WriteRejected'
x-auth: api-key
/api/v1/components/categories:
get:
tags:
- Components library
summary: List library categories
description: Categories with counts, subcategories and styles, for a category-first block picker.
operationId: listLibraryCategories
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
categories:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
total:
type: integer
subcategories:
type: array
items:
type: object
properties:
name:
type: string
count:
type: integer
styles:
type: array
items:
type: object
properties:
name:
type: string
count:
type: integer
required:
- id
- name
- total
required:
- categories
'401':
$ref: '#/components/responses/Unauthorized'
x-auth: optional-key
security:
- {}
- bearerAuth: []
/api/v1/components/{id}:
get:
tags:
- Components library
summary: Read a block with its Liquid
description: By `_id` or slug. Bumps the block's `uses` count.
operationId: getLibraryComponent
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The block's `_id` or slug.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
component:
$ref: '#/components/schemas/LibraryComponent'
required:
- component
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-auth: optional-key
security:
- {}
- bearerAuth: []
put:
tags:
- Components library
summary: Update a block
description: Only the block's owner (or an admin). `source` is sanitized and linted. `expectedVersion` guards against a concurrent edit. Only an admin can change `isPublic`, `isFeatured` or `isCategoryPreview`.
operationId: updateLibraryComponent
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The block's `_id` or slug.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
slug:
type: string
description:
type: string
visual:
type: string
category:
type: string
subcategory:
type: string
tags:
type: array
items:
type: string
preset:
type: string
group:
type: string
style:
type: string
isPublic:
type: boolean
isFeatured:
type: boolean
isCategoryPreview:
type: boolean
expectedVersion:
type: integer
source:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
component:
$ref: '#/components/schemas/LibraryComponent'
required:
- component
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: A conflict (`error` says which).
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'422':
$ref: '#/components/responses/WriteRejected'
x-auth: api-key
delete:
tags:
- Components library
summary: Delete a block
description: Only the block's owner (or an admin).
operationId: deleteLibraryComponent
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The block's `_id` or slug.
responses:
'200':
description: Deleted
content:
application/json:
schema:
type: object
properties:
deleted:
type: boolean
required:
- deleted
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-auth: api-key
/api/v1/components/{id}/like:
post:
tags:
- Components library
summary: Like a public block
description: 'Idempotent per caller: the first like counts, repeats answer `alreadyLiked`.'
operationId: likeLibraryComponent
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The block's `_id` or slug.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
likes:
type: integer
alreadyLiked:
type: boolean
required:
- likes
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-auth: api-key
components:
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'
WriteRejected:
description: 'A file write was refused: `lint` (422, with `issues` and `path`), too large (413), or another `rejected` reason.'
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
LibraryComponent:
type: object
description: A block in the component library. A block is its Liquid `source`.
properties:
_id:
type: string
name:
type: string
slug:
type: string
description:
type: string
visual:
type: string
category:
type: string
subcategory:
type: string
tags:
type: array
items:
type: string
styles:
type: array
items:
type: string
preset:
type: string
group:
type: string
blockType:
type: string
source:
type: string
description: The block's Liquid (omitted from lists).
isPublic:
type: boolean
isFeatured:
type: boolean
isCategoryPreview:
type: boolean
likes:
type: integer
uses:
type: integer
version:
type: integer
author:
type: string
tenant:
type:
- string
- 'null'
required:
- _id
- slug
- name
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.