Browse for documents and assets

This describes the endpoint for browsing for items in the CMS. This is used for browsing documents, for example for cross-references, for document templates for new documents, and for browsing assets like images.

POST /browse

Browse for documents, templates or assets. May return folder and/or items of the specified types. This is a POST request instead of a GET request so the query object parameter can be extended with implementation specific attributes without hitting any query parameter limit constraints.

Parameters

body (Required)

The body object containing the browse request.

Parameter type	body
Content type	application/json

body
parameter	required	type	description
context	required	Context	The context from which the browse request was invoked.
assetTypes	required	array[string]	The types of content to browse. The only reserved types are 'document', 'document-template' and 'image'. For example this could be video, audio or any other implementation specific type.
resultTypes	required	array[string]	The types of items to return, can be one of: [ 'file' ] [ 'folder' ] [ 'file', 'folder' ]
folderId	optional	string	The id of the folder to browse in, if none is specified, the root folder is meant.
query	optional	Query	Implementation dependent query object.
limit	optional	number	Paging option; The maximum number of results to return in this request. If not specified, return all results.
offset	optional	number	Paging option; The zero-based offset from on which to get results. If not specified, assume 0.

Context
parameter	required	type	description
editSessionToken	required	string	Uniquely identifies the instance of Fonto Editor. See Invocation of Fonto Editor for details.
documentId	optional	string	The id of the current document.

Query
parameter	required	type	description
fulltext	optional	string	Full text search query within the scope of the given folder and type.
sort	optional	string	The sort order to use, which can be implementation specific.

Accept (Required)

The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand. See the MDN Web Docs for more information.

Parameter type	header
Type	string
Value	application/json

Responses

Status code 200

A list of available items is returned.

body
parameter	required	type	description
totalItemCount	required	number	The total number of results for the query. Can be higher than the number of returned items if pagination is used.
items	required	array[BrowseItem]	The result items. This list may be empty if the request does not match any items.
metadata	optional	RootMetadata	The implementation specific metadata describing the properties of the body. Some properties are reserved. For example see the hierarchy property that is already supported out-of-the-box below in RootMetadata.

BrowseItem
parameter	required	type	description
id	required	string	The target to use as link, href, source or id of the resource to load.
label	required	string	The label to use for displaying the resource.
type	required	string	The type of item, for example: folder, document, document-template, link, image, file or unknown.
metadata	optional	ItemMetadata	The implementation specific metadata describing the properties of this entry. See some cases that are already supported out-of-the-box below in ItemMetadata.

RootMetadata
parameter	required	type	description
hierarchy	optional	array[BrowseItem]

ItemMetadata
parameter	required	type	description
icon	optional	string	Add a fontawesome icon if it needs to be a different than the default icon. The icon name must not include a prefix (fa-). For example 'folder-o' (default for type folder), 'file-text-o' (default for type document), 'file-image-o'(default for type image), 'file-o' (default for type document-template).
isDisabled	optional	boolean	If the item is disabled, the user can't select it.
description	optional	string	Is used to add an extra description to an item. Should only be used by a item with type 'document-template'.
properties	optional	object	Is used to describe properties by name for an item. Should only be used by a item with type 'image'.

Status code 403

The user is not authorized to browse here.

Status code 404

The requested folder does not exist in the CMS. Should not be used if the query is valid but has no results.

Status code 500

Any error in the 500 range indicates a problem with the CMS.

Examples

Request

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
		"documentId": "076A86C7-BA00-4AC2-B363-37C454481183"
	},
	"assetTypes": [ "document" ],
	"resultTypes": [ "file" ]
}

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
		"documentId": "076A86C7-BA00-4AC2-B363-37C454481183"
	},
	"assetTypes": [ "document" ],
	"resultTypes": [ "folder" ],
	"folderId": "74257961-EDE3-4180-AF17-0A435EE8FB7B"
}

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
		"documentId": "076A86C7-BA00-4AC2-B363-37C454481183"
	},
	"assetTypes": [ "document" ],
	"resultTypes": [ "file" ],
	"query": {
		"fulltext": "CMS Connectors API"
	}
}

JavaScript

{
	"context": {
		"editSessionToken": "EF091CD9-DC7A-4F91-9964-21CAF0DC3DCE",
		"documentId": "076A86C7-BA00-4AC2-B363-37C454481183"
	},
	"assetTypes": [ "image" ],
	"resultTypes": [ "file" ],
	"limit": 42,
	"offset": 42
}

Response

JavaScript

{
	"totalItemCount": 1,
	"items": [
		{
			"id": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
			"label": "Dutchclogs.jpg",
			"type": "image",
			"metadata": {
				"icon": "picture-o",
				"isDisabled": true,
				"properties": {
					"width": "1",
                    "height": "1",
                    "fileSize": "1234 kb",
                    "created": "01-02-2003 12:34:56",
                    "tags": "first, second, third, everything-is-formatted-by-cms"
				}
			}
		}
	]
}

JavaScript

{
	"totalItemCount": 1,
	"items": [
		{
			"id": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
			"label": "Concept.template",
			"type": "document-template",
			"metadata": {
				"icon": "file-code-o",
				"isDisabled": true,
				"description": "Concepts provide background that helps readers understand essential information about a product, a task, a process, or any other conceptual or descriptive information."
			}
		}
	]
}

This case assumes the context.documentId is not set, the context.documentId is set to 'B457003F-37E3-4B46-9352-C5CCFB60C808'. The CMS finds the folder in which the document with documentId 'B457003F-37E3-4B46-9352-C5CCFB60C808' is found, and uses this folder as the folderId. It then returns the contents of this folder, along with the hierarchy of the folder ancestry.

JavaScript

{
	"totalItemCount": 2,
	"items": [
		{
			"id": "74257961-EDE3-4180-AF17-0A435EE8FB7B",
			"label": "glossary.xml",
			"type": "document"
		},
		{
			"id": "B457003F-37E3-4B46-9352-C5CCFB60C808",
			"label": "clogs.xml",
			"type": "document"
		}
	],
	"metadata": {
		"hierarchy": [
			{
				"id": "rootfolder-id",
				"label": "Home",
				"type": "folder"
			},
			{
				"id": "33A8360B-520F-48D2-B8B0-BA7761A73565",
				"label": "Documents",
				"type": "folder"

			}
		]
	}
}