> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mayekun.com/llms.txt
> Use this file to discover all available pages before exploring further.
# NodeForgeCMS REST API — Complete Reference Guide
> Complete reference for the NodeForgeCMS REST API — manage articles, columns, media, users, and AI features with a consistent JSON interface.
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`.
```http theme={null}
Content-Type: application/json
```
### Standard Response Envelope
Every successful API response is wrapped in a consistent envelope:
```json theme={null}
{
"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:
```json theme={null}
{
"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](/api/authentication) for full details on obtaining and using tokens.
## Endpoint Groups
Define and manage the content structure of your CMS — create custom column types, configure fields, and control how content is organised.
Create, read, update, and delete article content. Supports filtering, pagination, and publishing state management.
Upload and manage image and file assets. Retrieve media metadata and integrate assets into your content programmatically.
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.**
```http theme={null}
POST /api/ai/search
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"query": "how to configure custom columns",
"lang": "en"
}
```
#### Request Body
The natural-language search query. The AI engine interprets meaning and intent rather than matching keywords literally.
Language code for the search context (e.g. `en`, `zh`, `fr`). Results are ranked within the specified language corpus.
#### Response
```json theme={null}
{
"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.**
```http theme={null}
POST /api/ai/translate
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"content": "Welcome to NodeForgeCMS — the modern enterprise CMS.
",
"sourceLang": "en",
"targetLang": "fr"
}
```
#### Request Body
The content to translate. Accepts plain text or HTML. HTML tags and structure are preserved in the translated output.
Language code of the input content (e.g. `en`, `zh`, `de`). Must match the actual language of the supplied `content`.
Language code of the desired output language (e.g. `fr`, `es`, `ja`). The translated content will be returned in this language.
#### Response
```json theme={null}
{
"code": 200,
"data": {
"translatedContent": "Bienvenue sur NodeForgeCMS — le CMS d'entreprise moderne.
"
},
"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.