HTTP + JSON · v1
API Documentation
Connect your website to the content you manage in Pen.
Overview
Pen is a headless CMS. Manage Pages in Pen and consume them through REST APIs. Pen returns structured JSON; your website controls the rendering and design. No SDK or Pen frontend package is required.
Getting started
- Create or manage a Page from your Pen workspace.
- Save your changes, then publish the Page.
- Open Project → Website in Pen and copy its public Page endpoint.
- Fetch JSON from your website’s server or browser.
- Render the returned sections with your own components.
You do not need a Pen account to read these docs or consume a public Page endpoint.
API base URL
https://pen.tusharsharma.me/api/v1This address uses Pen’s configured public origin (PEN_PUBLIC_SITE_ORIGIN). Use the complete URL when fetching from another website. Replace YOUR_PROJECT_ID in the examples with the project ID from your copied endpoint.
Public Page API
/api/v1/public/pages/:slug?projectId=:projectIdRead-only delivery of the last published version. No API key required.
| Input | Contract |
|---|---|
| slug · path · required | Exact Page slug: lowercase letters, numbers and single separating hyphens (for example, home or about-us). |
| projectId · query · required | The project ID from your Page endpoint. Slugs are scoped to this project, never resolved globally. |
curl "https://pen.tusharsharma.me/api/v1/public/pages/home?projectId=YOUR_PROJECT_ID"Missing projects, missing Pages, unpublished Pages and invalid or missing public identifiers return 404. Saved changes do not replace the published snapshot until you publish again.
{
"page": {
"id": "page-home",
"slug": "home",
"title": "Home",
"status": "published",
"metadata": {
"title": "Acme Studio",
"description": "Thoughtful design for everyday life."
},
"sections": [
{
"id": "section-hero",
"name": "Hero",
"type": "hero",
"variant": "split",
"order": 0,
"content": {
"headline": "Make room for good design",
"subheadline": "Meet Acme Studio.",
"ctaLabel": "Our work",
"ctaHref": "/work"
},
"fields": [
{
"type": "headline",
"content": "Make room for good design"
},
{
"type": "subheadline",
"content": "Meet Acme Studio."
},
{
"type": "cta",
"content": "Our work",
"href": "/work"
}
]
}
]
}
}The response wraps the resource in page. The IDs and content above are illustrative values using the real schema.
Protected content API
/api/v1/pages/:slugRead the currently saved Page, including drafts, using a project API key.
Generate a key from Project → Website → Private content access inside Pen. Copy it when shown; Pen stores only its hash. Regenerating invalidates the previous key. Revoke removes access.
curl "https://pen.tusharsharma.me/api/v1/pages/home" \
-H "Authorization: Bearer $PEN_API_KEY"Set PEN_API_KEY in your server environment to the generated key. The key determines the project; a projectId query parameter cannot change its scope. The response has the same Page shape as the public API, but status can be draft or published. Keys grant reads only, not management mutations.
Authentication
| API | Authentication | Content |
|---|---|---|
| Public delivery | None | Last published snapshot only. |
| Protected content | Authorization: Bearer <project-api-key> | Saved content in the key’s project, including drafts. |
Use protected content access on your server. Never put a secret key in browser code or a client bundle. Pen’s workspace management operations use owner authentication separately; a project key does not authorize those operations.
Protected management APIs
Pen’s workspace routes—such as /api/projects, nested /api/projects/:projectId/… routes, /api/account/…, and /api/chat—are used by the authenticated Pen application. They require the signed-in account’s Firebase ID token and enforce project ownership or account-level authorization. A project API key cannot call them.
Third-party websites should use the public delivery endpoint for published content or the project-key endpoint for server-side draft reads. This documentation does not present management routes as a supported external API.
Pages
| Field | Meaning |
|---|---|
| id | Page identifier. |
| slug | Page address within its project. |
| title | Page title, plain text. |
| status | published for public delivery; draft or published for protected reads. |
| metadata | Object with optional title and description. |
| sections | Array sorted by section order; may be empty. |
Delivery excludes project ownership, credentials, storage paths and internal timestamps.
Sections
| Field | Meaning |
|---|---|
| id / name | Section identifier and human-readable name. |
| type | Semantic section type: hero, content, image, features or cta. |
| variant | Predefined layout choice for that type; your frontend decides how to render it. |
| order | Non-negative integer controlling section order. |
| content | Structured content for the section type. Properties can be omitted; this object may be empty. |
| fields · optional | Canonical field array when present. Each field has type and content. Text/video values are strings; uploaded image values are objects with url, alt and optional width/height. Null means unpopulated. CTA fields may also include href. |
| Type | Variants | Content properties (optional) |
|---|---|---|
| hero | centered, split, left | headline, subheadline, ctaLabel, ctaHref, imageUrl, imageAlt |
| content | basic, image, rich | heading, paragraphs (string array), imageUrl, imageAlt |
| image | full, split, gallery | heading, description, images (objects with url, alt and optional caption) |
| features | three-column, four-column, stacked | heading, intro, items (objects with title and description) |
| cta | centered, split, minimal | heading, description, label, href |
{
"type": "image",
"content": {
"url": "https://res.cloudinary.com/YOUR_CLOUD/image/upload/v1/media/IMAGE_ID.png",
"alt": "Describe the image",
"width": 1200,
"height": 800
}
}This illustrative URL is replaced by the actual uploaded image’s secure delivery URL. Upload and explicitly save an image in Pen, then publish to expose it here.
Field types are headline, subheadline, description, image, video and cta. A null value means the field exists but has not been populated. When fields is present, use it for those editable values; content can retain additional section structure such as feature items. Older image fields may still contain URL strings. New uploads return structured references; storage IDs are omitted from delivery. Older sections may only have content. Pen sends data, never HTML, CSS or JSX. Treat text as text and resolve relative links against your own website.
Example integration
Read the response envelope, handle errors and pass the Page to your own renderer.
const response = await fetch(
"https://pen.tusharsharma.me/api/v1/public/pages/home?projectId=YOUR_PROJECT_ID",
{ cache: "no-store" }
);
const body = await response.json();
if (!response.ok) {
throw new Error(body.error ?? "Could not load Page");
}
const { page } = body;
// Render page.sections with your website's own components.Framework examples
Optional fetch patterns. All use the same public HTTP endpoint and need no key.
Next.js · server component
export default async function Page() {
const response = await fetch("https://pen.tusharsharma.me/api/v1/public/pages/home?projectId=YOUR_PROJECT_ID", {
cache: "no-store",
});
const body = await response.json();
if (!response.ok) throw new Error(body.error);
return <h1>{body.page.title}</h1>;
}React · browser component
import { useEffect, useState } from "react";
export default function PageTitle() {
const [title, setTitle] = useState("Loading…");
useEffect(() => {
const controller = new AbortController();
async function load() {
try {
const response = await fetch("https://pen.tusharsharma.me/api/v1/public/pages/home?projectId=YOUR_PROJECT_ID", {
signal: controller.signal, cache: "no-store",
});
const body = await response.json();
if (!response.ok) throw new Error(body.error);
setTitle(body.page.title);
} catch (error) {
if (!controller.signal.aborted) setTitle(error.message);
}
}
load();
return () => controller.abort();
}, []);
return <h1>{title}</h1>;
}Plain JavaScript · browser module
// Run in a <script type="module"> with an <h1 id="title"> element.
const response = await fetch(
"https://pen.tusharsharma.me/api/v1/public/pages/home?projectId=YOUR_PROJECT_ID",
{ cache: "no-store" }
);
const body = await response.json();
if (!response.ok) {
throw new Error(body.error ?? "Could not load Page");
}
const { page } = body;
// Render page.sections with your website's own components.
document.querySelector("#title").textContent = page.title;Errors
Errors use a JSON object with an error string. Check the HTTP status before reading body.page.
{"error":"Page not found."}| Status | When / error message |
|---|---|
| 400 Bad Request | Protected read with an invalid slug after authentication, or schema validation failure: Invalid request. Check the supplied fields and values. |
| 401 Unauthorized | Protected read with a missing, invalid, rotated or revoked key: Invalid API key. |
| 404 Not Found | Page not found. Public delivery also uses this for invalid or missing identifiers and unpublished content. |
| 500 Internal Server Error | Unexpected server failure: Pen couldn't complete the request. Please try again. |
The documented content GET routes do not use 403 for an invalid key; they return 401. Public delivery needs no authentication.
Publishing
Draft → Publish → available through the public API. Save and preview work with saved content; they do not publish it.
Editing a published Page leaves its previous published snapshot available. Publish again to deliver the new saved version. Unpublish → removed from public delivery. Protected reads can still access the saved Page. Deleting the Page removes both versions.
Security
- Use the public endpoint whenever you only need published content.
- Keep project API keys on your server, out of client code and source control.
- Rotate or revoke a key in Website settings if it is compromised.
- Only publish content intended for anyone to read.
Caching & delivery
| Response | Headers |
|---|---|
| Public GET (including errors) | Cache-Control: no-store; Access-Control-Allow-Origin: * |
| Protected GET (including errors) | Cache-Control: private, no-store; no public CORS header |
Public JSON can be fetched across origins from a browser without credentials. Protected access belongs on your server. No CDN cache duration, ISR or revalidation interval is provided. If your website caches a copy, you are responsible for removing it when content is unpublished.
API versioning
Use /api/v1/public/pages/:slug?projectId=:projectId and /api/v1/pages/:slug for integrations. Both live under the v1 namespace; future versions can use separate routes. The older unversioned public route remains a compatibility alias, but new integrations should use v1.
