Skip to main content
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:
EnvironmentBase URL
Productionhttps://yourdomain.com/api
Developmenthttp://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"
}
FieldTypeDescription
codeintegerHTTP status code mirrored in the response body
dataobject | arrayThe requested or mutated resource(s)
messagestringHuman-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:
CodeMeaning
400Bad Request — malformed or missing parameters
401Unauthorized — missing or invalid JWT token
403Forbidden — valid token but insufficient permissions
404Not Found — the requested resource does not exist
500Internal 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.
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

​
query
string
required
The natural-language search query. The AI engine interprets meaning and intent rather than matching keywords literally.
​
lang
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"
}
FieldTypeDescription
resultsarrayRanked array of matching article summaries
results[].idnumberArticle ID
results[].titlestringArticle title
results[].summarystringShort excerpt from the article
results[].scorenumberRelevance score between 0 and 1 — higher is more relevant
totalnumberTotal 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

​
content
string
required
The content to translate. Accepts plain text or HTML. HTML tags and structure are preserved in the translated output.
​
sourceLang
string
required
Language code of the input content (e.g. en, zh, de). Must match the actual language of the supplied content.
​
targetLang
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"
}
FieldTypeDescription
translatedContentstringThe 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.