REST API CMS Search, Files and History

• Search content
• Site files
• History

Search, site files and history of the CMS have a REST API in addition to Pages and Parts. Enable the REST API in the Redmine settings. Authenticate with an API key or HTTP basic authentication. All endpoints below need an administrator or a user in the CMS edit group; others get 403 and anonymous requests get 401. Every list answers with total_count, offset and limit.

Search content

GET /cms/search.json?q=pricing&type=page
GET /cms/search.xml?q=pricing&type=snippet

Parameter	Description
q	text to find; required, at least 3 characters; words are combined with AND (up to 5 words, 100 characters)
type%(no-wrap)	required: %page%(no-wrap), %part%(no-wrap), %layout%(no-wrap), %snippet%(no-wrap), %page_field%(no-wrap) or %variable%(no-wrap) (%variable is for administrators only)
limit%(no-wrap), %offset	paging, at most 100 per request

The search is case-insensitive over names and content (Pages also over the title). Each item of results has id (none for a variable), name, page (for Parts and Page fields) and an excerpt of about 160 characters around the first match. History versions, Redmine layouts, Routes, Menus and assets are not searched. A missing q, a short word or an unknown type gives 422.

Site files

GET /cms/assets.json?q=logo&type=image
POST /cms/assets.json
PATCH /cms/assets.json
POST /cms/assets/version.json

• GET lists files of the Site; add container_type%(no-wrap) (%CmsPage%(no-wrap), %CmsLayout%(no-wrap) or %CmsSnippet%(no-wrap)) and %container_id%(no-wrap) for the files of one object. Filters: %q%(no-wrap) (part of the name), %type%(no-wrap) (%image%(no-wrap), %code%(no-wrap), %document%(no-wrap), %other%(no-wrap)), %sort%(no-wrap) (%filename%(no-wrap), %created_on%(no-wrap), %size%(no-wrap)). Each item of %files%(no-wrap) has %id%(no-wrap), %filename%(no-wrap), %filesize%(no-wrap), %content_type%(no-wrap), %description%(no-wrap), %author%(no-wrap), %created_on%(no-wrap) and %content_url.
• POST /cms/assets adds Site files from upload tokens (POST /uploads) as attachments[1][token], with optional filename and description. Answers 201, or 422 if no token is valid.
• PATCH /cms/assets renames or describes Site files with attachments[ID][filename] and attachments[ID][description]. Answers 204.
• POST /cms/assets/version uploads a new version of a file (filename, file, container_type, container_id); the new file becomes the current one. Answers 201.

Files cannot be deleted through the API.

History

GET /cms/cms_page/ID/history.json
GET /cms/cms_page/ID/diff.json?entry=v3&entry_from=v1

The object type in the path is cms_page, cms_part, cms_layout or cms_snippet, and ID is the numeric id.

• history returns entries, newest first. An entry has key (vNUMBER for a version, jJOURNAL_ID for an attribute or field change), version, journal_id, kind (version, attributes, fields, attributes_and_fields), author, comments and created_at. Add include=content to get the text. Attribute and field changes exist for Pages only.
• diff compares entry with entry_from (or version and version_from; the previous entry is used when the second is missing). The answer has from, to, details (changes of attributes and fields), content_changed and unified, a unified text diff. Unknown entries give 404.