v1 REST API

Fetch content from CMS One using simple HTTP endpoints. Authenticate with an API key and start serving articles to any front‑end, app, or service.

GET /api/v1/articlesGET /api/v1/articles/:slug

Overview

The v1 API exposes published content from your workspace over HTTPS. All requests must be authenticated and all responses use the same JSON envelope.

REST + JSON

Simple HTTP endpoints returning predictable JSON responses. No SDK required.

API Key Auth

Authenticate every request with a Bearer token scoped to your workspace.

Paginated Lists

All collection endpoints support page, limit, search, and sort parameters.

Consistent Errors

Every error returns { success: false, error } with a reliable HTTP status code.

Base URL

https://your-domain.com/api/v1

Replace your-domain.com with your own domain or the CMS One cloud hostname.

Authentication

Every request must include a valid API key in the Authorization header. Generate keys from Dashboard → Settings → API Keys. Keys are scoped to your workspace — they only grant access to content belonging to that tenant.

Required header

Authorization: Bearer YOUR_API_KEY

const res = await fetch("https://your-domain.com/api/v1/articles", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});

const { success, data, meta } = await res.json();

Where to find your API key

Open your dashboard and navigate to Settings → API Keys. Create a new key, copy it once — it will not be shown again.

Articles

The Articles resource gives read‑only access to all published content in your workspace. Two endpoints are available: one for listing and one for fetching a single article by its slug.

GET/api/v1/articles— List Articles

Returns a paginated list of published articles for your workspace. Results are ordered by publish date (newest first) by default. Filter by type, category, tag, or language, and search full‑text across titles and content.

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number (1‑based).
`limit`	number	10	Results per page. Maximum 100.
`type`	string	—	Filter by article type. One of: blog, news, case-study, tutorial, documentation, page.
`category`	string	—	Filter by category slug (e.g. guides).
`tag`	string	—	Filter by tag slug or name.
`search`	string	—	Full‑text search term matched against titles and content.
`language`	string	—	ISO language code (e.g. "en", "fr").
`sort`	string	latest	"latest" orders by publishedAt desc (default); "popular" orders by view count desc.

Example

const res = await fetch(
  "https://your-domain.com/api/v1/articles?page=1&limit=5&sort=latest",
  {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  }
);

const { success, data, meta } = await res.json();
// data → Article[]
// meta → { page: 1, limit: 5, total: 48, totalPages: 10 }

Response Fields

Field	Type	Description
`id`	string	Article ObjectId as a hex string.
`title`	string	Article title.
`slug`	string	URL‑friendly identifier. Use this to fetch the full article.
`excerpt`nullable	string	Short summary suitable for list views.
`type`	string	Content type (blog, tutorial, etc.).
`featuredImage`nullable	string	Cover image URL.
`featuredImageAlt`nullable	string	Image alt text.
`categories`	{ id, name, slug }[]	Resolved category objects.
`tags`	string[]	Tag slugs / names.
`language`	string	Language code.
`publishedAt`	ISO string	Publication date.
`readCount`	number	Total view count.
`likeCount`	number	Total likes.
`commentCount`	number	Total comments.
`isFeatured`	boolean	Whether the article is featured.
`isPinned`	boolean	Whether the article is pinned.

GET/api/v1/articles/:slug— Get Article

Returns the full content of a single published article identified by its slug. Includes the raw body (HTML or Markdown), resolved category and tag objects, SEO metadata, and up to 5 related articles. Calling this endpoint also increments the article's view counter — repeat visits within the same time window are deduplicated automatically.

Example

const slug = "getting-started-with-cms-one";

const res = await fetch(
  `https://your-domain.com/api/v1/articles/${slug}`,
  {
    headers: { Authorization: "Bearer YOUR_API_KEY" },
  }
);

const { success, data } = await res.json();
// data.content     → full article body
// data.contentType → "html" | "markdown"
// data.related     → up to 5 related articles

Response Fields

Field	Type	Description
`id`	string	Article ObjectId as a hex string.
`title`	string	Article title.
`slug`	string	URL‑friendly identifier.
`content`	string	Full article body. Check contentType to determine the format.
`contentType`	"html" \| "markdown"	Format of the content field.
`excerpt`nullable	string	Short summary.
`type`	string	Content type.
`featuredImage`nullable	string	Cover image URL.
`gallery`	string[]	Additional image URLs.
`language`	string	Language code.
`publishedAt`	ISO string	Publication date.
`updatedAt`	ISO string	Last updated date.
`categories`	{ id, name, slug, description? }[]	Fully resolved category objects.
`tags`	{ name, slug, color }[]	Fully resolved tag objects including brand color.
`readCount`	number	Total view count (incremented by this request, deduplicated).
`likeCount`	number	Total likes.
`commentCount`	number	Total comments.
`allowComments`	boolean	Whether the comment section is open.
`isFeatured`	boolean	Featured flag.
`seo`	object	SEO metadata: { title, description, ogImage, noIndex }.
`related`	RelatedArticle[]	Up to 5 related articles based on shared categories and tags.

Error Handling

Every failed request returns a JSON body with success: false and a human‑readable error string. Always check the HTTP status code first, then inspect the body for details.

Status	When it occurs	Response body
401	The Authorization header is missing, malformed, or the API key does not exist.	`{ "success": false, "error": "Unauthorized" }`
403	The API key is valid but disabled, or it does not belong to the target workspace.	`{ "success": false, "error": "API key is disabled" }`
404	The requested article does not exist, is not published, or its publish date is in the future.	`{ "success": false, "error": "Article not found" }`
500	An unexpected server error occurred. Please verify your request and try again.	`{ "success": false, "error": "Failed to fetch articles" }`

v1 REST API

Overview

Authentication

Articles

Query Parameters

Example

Response Fields

Example

Response Fields

Error Handling

Further Reading