REST API CMS Pages

• Listing pages
• Showing a page
• Creating a page
• Updating a page
• Deleting a page
• Search
• Authentication
• curl examples
  • List pages
  • Show page with parts
  • Create page
  • Update page
  • Delete page

Listing pages

GET /cms/pages.xml
GET /cms/pages.json

Returns a paginated list of CMS pages.

Parameters:

Parameter	Type	Description
offset	integer	number of pages to skip (optional)
limit	integer	number of pages to return, max 100 (optional)
status_id	integer	filter by status: 1 = active, 2 = locked (optional)

Examples:

GET /cms/pages.xml
GET /cms/pages.json
GET /cms/pages.xml?offset=0&limit=50
GET /cms/pages.xml?status_id=1

Response:

<?xml version="1.0" encoding="UTF-8"?>
<cms_pages type="array" total_count="2" offset="0" limit="25">
  <cms_page>
    <id>1</id>
    <name>home</name>
    <title>Home Page</title>
    <content>Welcome to our site...</content>
    <filter_id>textile</filter_id>
    <status_id>1</status_id>
    <visibility>public</visibility>
    <is_cached>true</is_cached>
    <layout id="1" name="default"/>
    <version>3</version>
    <created_at>2024-01-01T10:00:00Z</created_at>
    <updated_at>2024-06-01T12:00:00Z</updated_at>
  </cms_page>
</cms_pages>

Showing a page

GET /cms/pages/:id.xml
GET /cms/pages/:id.json

Returns a single CMS page. The :id parameter is the page name (not numeric ID).

Parameters:

• include: fetch associated data (optional, comma-separated). Possible values:
  • attachments
  • parts
  • fields

Examples:

GET /cms/pages/home.xml
GET /cms/pages/home.json
GET /cms/pages/home.xml?include=parts,fields
GET /cms/pages/home.xml?include=attachments,parts,fields

Response:

<?xml version="1.0" encoding="UTF-8"?>
<cms_page>
  <id>1</id>
  <name>home</name>
  <slug>home</slug>
  <title>Home Page</title>
  <status id="1" name="active"/>
  <filter>textile</filter>
  <visibility>public</visibility>
  <is_cached>true</is_cached>
  <layout id="1" name="default"/>
  <author id="1" name="Admin"/>
  <version>3</version>
  <content>Welcome to our site...</content>
  <tag_list>featured, landing</tag_list>
  <created_at>2024-01-01T10:00:00Z</created_at>
  <updated_at>2024-06-01T12:00:00Z</updated_at>
</cms_page>

With include=parts,fields:

<cms_page>
  ...
  <parts type="array">
    <cms_part>
      <id>1</id>
      <name>content</name>
      <description>Main content area</description>
      <content>h1. Welcome</content>
      <filter>textile</filter>
      <status id="1" name="active"/>
      <is_cached>false</is_cached>
      <created_at>2024-01-01T10:00:00Z</created_at>
      <updated_at>2024-06-01T12:00:00Z</updated_at>
    </cms_part>
  </parts>
  <fields type="array">
    <field>
      <id>1</id>
      <name>meta_description</name>
      <content>Welcome to our homepage</content>
      <created_at>2024-01-01T10:00:00Z</created_at>
      <updated_at>2024-01-01T10:00:00Z</updated_at>
    </field>
  </fields>
</cms_page>

Creating a page

POST /cms/pages.xml
POST /cms/pages.json

Creates a new CMS page. Requires CMS edit permission.

Parameters:

• cms_page — page attributes:

Attribute	Type	Required	Description
name	string	yes	unique identifier (lowercase letters, digits, hyphens, underscores)
slug	string	yes	URL segment (same format as name)
title	string	no	display title
content	string	no	page body
filter_id	string	no	markup filter: textile, markdown, html, none
status_id	integer	no	1 = active (default), 2 = locked
visibility	string	no	public, logged, or user/group ID string
layout_id	integer	no	CMS layout ID
parent_id	integer	no	parent page ID
is_cached	boolean	no	enable page caching
tag_list	string	no	comma-separated tags
fields_attributes	array	no	custom fields: [{name, content}]

Examples:

POST /cms/pages.xml

<?xml version="1.0"?>
<cms_page>
  <name>about</name>
  <slug>about</slug>
  <title>About Us</title>
  <content>h1. About Us

Our company was founded in 2010.</content>
  <filter_id>textile</filter_id>
  <status_id>1</status_id>
  <visibility>public</visibility>
  <tag_list>company, about</tag_list>
</cms_page>

POST /cms/pages.json

{
  "cms_page": {
    "name": "about",
    "slug": "about",
    "title": "About Us",
    "content": "h1. About Us\n\nOur company was founded in 2010.",
    "filter_id": "textile",
    "status_id": 1,
    "visibility": "public",
    "tag_list": "company, about" 
  }
}

Response: HTTP 201 Created, with Location header pointing to the new page.

Updating a page

PUT /cms/pages/:id.xml
PUT /cms/pages/:id.json

Updates a CMS page. The :id parameter is the page name. Accepts the same attributes as creating a page. Requires CMS edit permission.

Examples:

PUT /cms/pages/about.xml

<?xml version="1.0"?>
<cms_page>
  <title>About Our Company</title>
  <content>Updated content here.</content>
  <tag_list>company, about, updated</tag_list>
</cms_page>

PUT /cms/pages/about.json

{
  "cms_page": {
    "title": "About Our Company",
    "content": "Updated content here." 
  }
}

Response: HTTP 200 OK (no body).

Deleting a page

DELETE /cms/pages/:id.xml
DELETE /cms/pages/:id.json

Deletes a CMS page. Requires admin privileges.

Examples:

DELETE /cms/pages/about.xml
DELETE /cms/pages/about.json

Response: HTTP 200 OK (no body).

Search

GET /cms/pages/search

Returns a JSON list of pages matching the query. Returns public pages only; does not require API key.

Parameters:

Parameter	Type	Description
q	string	search string (matches name, slug, title)
limit	integer	max results to return (default 10)
cms_page	string	restrict search to children of this page (by name)
children	string	scope when cms_page is set: children (default), descendants, leaves
tag	string	comma-separated tag names to filter by
match	string	tag matching mode: all (default), any, exclude

Examples:

GET /cms/pages/search?q=about
GET /cms/pages/search?q=news&limit=5
GET /cms/pages/search?tag=featured
GET /cms/pages/search?q=post&cms_page=blog&children=descendants
GET /cms/pages/search?tag=featured,homepage&match=any

Response:

[
  {
    "name": "about",
    "slug": "about",
    "path": "about",
    "title": "About Us",
    "tags": ["company", "about"]
  },
  {
    "name": "contact",
    "slug": "contact",
    "path": "contact",
    "title": "Contact Us",
    "tags": []
  }
]

Authentication

All API endpoints (except Search) require authentication. Supported methods:

• key query parameter: GET /cms/pages.xml?key=YOUR_API_KEY
• X-Redmine-API-Key HTTP header (preferred)
• HTTP Basic auth with login/password

API keys are found in My account → API access key.

curl examples

List pages

curl -H "X-Redmine-API-Key: YOUR_API_KEY" \
  http://localhost:3000/cms/pages.xml

Show page with parts

curl -H "X-Redmine-API-Key: YOUR_API_KEY" \
  "http://localhost:3000/cms/pages/home.xml?include=parts,fields" 

Create page

curl -v -H "Content-Type: application/xml" \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  -X POST \
  -d "<cms_page><name>test</name><slug>test</slug><title>Test Page</title><content>Hello</content><filter_id>textile</filter_id><status_id>1</status_id><visibility>public</visibility></cms_page>" \
  http://localhost:3000/cms/pages.xml

Update page

curl -v -H "Content-Type: application/json" \
  -H "X-Redmine-API-Key: YOUR_API_KEY" \
  -X PUT http://localhost:3000/cms/pages/test.json \
  -d "{\"cms_page\": {\"title\": \"Updated Title\"}}" 

Delete page

curl -v -H "X-Redmine-API-Key: YOUR_API_KEY" \
  -X DELETE http://localhost:3000/cms/pages/test.xml