Searching and retrieving documents by using advanced search options

On this page

You can search and retrieve documents by specifying the scope of the search and field(s) to be search by sending a GET HTTP request to the Jira instance running this version of Documents app. A set of attributes of the matching documents is returned in JSON format.

Request URL

The request URL takes the following form:
https:/ /MY_JIRA_BASE_URL/plugins/servlet/stonikbyte/projectdocs/search-docs?query=QUERY&projectKey=PROJECT_KEY&fields=FIELDS&folderID=FOLDER&scope=SCOPE
Replace "https:/ /MY_JIRA_BASE_URL" with the base URL of your Jira server.

Parameters

You have to specify the following parameters:

Parameter	Description
query	Represents the search criteria. All documents containing this value will be retrieved. Search is not key sensitive. Leave it blank to retrieve all documents. The parameter has to be URL encoded.
projectKey	The key of the project that you want to search into.
fields	The field(s) to be used for search. It can be either "all" which will include most of the data fields associated with a document or one or more of the following values: "key","title", "description", "revision". The items in the list can be separated with a comma.
folderID	The key of the folder to be searched. See "scope" parameter for more info. This parameter will be used only if the scope parameter has one of the following values: "folderAndSubFolders" or "folder"
scope	The scope of the search. By default the scope is the entire project. This parameter can have one of the following values: "folderAndSubFolders" - the search will be restricted to the folder with the key specified through the "folderID" parameter and all its sub-folders "folder" - the search result will include only documents from the folder with the key specified through the "folderID" parameter If the "folderID" parameter is not provided, then the scope parameter is ignored and the entire project is searched.

An example of the request URL with parameters is as follows:

https:/ /myjiraserver:2990/jira/plugins/servlet/stonikbyte/projectdocs/search-docs?query=chart&projectKey=DEMO&fields=title,description&folderID=1&scope=folderAndSubFolders

In this example, all the documents from the folder with the key 1 (that belongs to project DEMO) and its sub-folders that contain “chart” in their Title or Description are returned.

A successful response

An HTTP 200 status response indicates a successful request. The following data about the matching documents is returned:

Data	Description	Example
key	The Key (unique identifier) of the document	11
title	The Title of the document	Project Plan
type	The type of the document. Possible values are: 1 - Folder; 2 - File; 3 - URL; 4 - Wiki	1
icon	The filename representing the document's icon. You can retrieve the icon by appending the file name to the following URL https:/ /MY_JIRA_BASE_URL/download/resources/com.stonikbyte.jira.plugins.project-docs-plugin/images/mime-types/ Example: https:/ /myjiraserver:2990/jira/download/resources/com.stonikbyte.jira.plugins.project-docs-plugin/images/mime-types/pdf24.png	pdf24.png

Error Response

If the REST call fails, the service returns one of the following HTTP statuses:

HTTP Status Code	Description
401 Unauthorized	Returned for unauthenticated requests or missing View permissions.
412 Precondition failed	Returned if one or more of the mandatory parameters are missing or if the license of the Documents app is expired.