NodeForgeCMS REST API — Complete Reference Guide

The NodeForgeCMS REST API gives developers full programmatic control over every aspect of their CMS — from publishing articles and managing media assets to administering users and defining content structure. Whether you’re building a headless front-end, automating content workflows, integrating a third-party service, or extending NodeForgeCMS with custom tooling, the API provides a consistent, predictable interface to every resource the platform manages.

The NodeForgeCMS API is designed for developers extending or integrating NodeForgeCMS into their own applications and workflows. Familiarity with REST conventions and JSON is assumed throughout this reference.

Base URL

All API endpoints are relative to the following base URL:

Environment	Base URL
Production	`https://yourdomain.com/api`
Development	`http://localhost:3000/api`

Replace yourdomain.com with the domain of your NodeForgeCMS deployment. Every path in this reference is appended to this base URL — for example, GET /api/articles resolves to https://yourdomain.com/api/articles in production.

Request & Response Format

All requests and responses use JSON. Every request that sends a body must include the Content-Type: application/json header, and every response from the API will carry Content-Type: application/json.

Content-Type: application/json

Standard Response Envelope

Every successful API response is wrapped in a consistent envelope:

{
  "code": 200,
  "data": { ... },
  "message": "success"
}

Field	Type	Description
`code`	integer	HTTP status code mirrored in the response body
`data`	object \| array	The requested or mutated resource(s)
`message`	string	Human-readable status string, typically `"success"`

Error Responses

When a request cannot be fulfilled, the API returns an error envelope. The data field is omitted:

{
  "code": 404,
  "message": "Article not found"
}

Common error codes:

Code	Meaning
`400`	Bad Request — malformed or missing parameters
`401`	Unauthorized — missing or invalid JWT token
`403`	Forbidden — valid token but insufficient permissions
`404`	Not Found — the requested resource does not exist
`500`	Internal Server Error — unexpected server-side failure

Authentication

JWT Bearer tokens are required for all write operations (POST, PUT, PATCH, DELETE). Some read endpoints (GET) are publicly accessible without a token — these are noted individually in the endpoint reference. See the Authentication guide for full details on obtaining and using tokens.

Endpoint Groups

Columns

Define and manage the content structure of your CMS — create custom column types, configure fields, and control how content is organised.

Articles

Create, read, update, and delete article content. Supports filtering, pagination, and publishing state management.

Media

Upload and manage image and file assets. Retrieve media metadata and integrate assets into your content programmatically.

Users

Administer CMS user accounts — create users, assign roles, update credentials, and manage access permissions.

AI Endpoints

NodeForgeCMS exposes two AI-powered endpoints for semantic search and content translation. Both require a valid Bearer token.

AI Semantic Search

Performs a semantic search across all published content using natural language. Returns ranked results relevant to the query. Requires a valid Bearer token.

POST /api/ai/search
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "query": "how to configure custom columns",
  "lang": "en"
}

Request Body

string

required

The natural-language search query. The AI engine interprets meaning and intent rather than matching keywords literally.

string

required

Language code for the search context (e.g. en, zh, fr). Results are ranked within the specified language corpus.

Response

{
  "code": 200,
  "data": {
    "results": [
      {
        "id": 12,
        "title": "Configuring Content Columns",
        "summary": "A guide to setting up and customising content columns in NodeForgeCMS.",
        "score": 0.94
      },
      {
        "id": 7,
        "title": "Getting Started with NodeForgeCMS",
        "summary": "An introduction to the core concepts of NodeForgeCMS.",
        "score": 0.81
      }
    ],
    "total": 2
  },
  "message": "success"
}

Field	Type	Description
`results`	array	Ranked array of matching article summaries
`results[].id`	number	Article ID
`results[].title`	string	Article title
`results[].summary`	string	Short excerpt from the article
`results[].score`	number	Relevance score between `0` and `1` — higher is more relevant
`total`	number	Total number of results returned

AI Content Translation

Translates a block of content from one language to another using the AI translation engine. Useful for automating multi-locale content workflows. Requires a valid Bearer token.

POST /api/ai/translate
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "content": "<p>Welcome to NodeForgeCMS — the modern enterprise CMS.</p>",
  "sourceLang": "en",
  "targetLang": "fr"
}

Request Body

string

required

The content to translate. Accepts plain text or HTML. HTML tags and structure are preserved in the translated output.

string

required

Language code of the input content (e.g. en, zh, de). Must match the actual language of the supplied content.

string

required

Language code of the desired output language (e.g. fr, es, ja). The translated content will be returned in this language.

Response

{
  "code": 200,
  "data": {
    "translatedContent": "<p>Bienvenue sur NodeForgeCMS — le CMS d'entreprise moderne.</p>"
  },
  "message": "success"
}

Field	Type	Description
`translatedContent`	string	The translated content in the target language. HTML structure is preserved if the input contained HTML.

Translation quality depends on the AI model configured in your NodeForgeCMS deployment. Very long content bodies may be subject to token limits — split large articles into sections if you encounter 400 errors.

​Base URL

​Request & Response Format

​Standard Response Envelope

​Error Responses

​Authentication

​Endpoint Groups

Columns

Articles

Media

Users

​AI Endpoints

​AI Semantic Search

​Request Body

​Response

​AI Content Translation

​Request Body

​Response

Base URL

Request & Response Format

Standard Response Envelope

Error Responses

Authentication

Endpoint Groups

AI Endpoints

AI Semantic Search

Request Body

Response

AI Content Translation

Request Body

Response