Searching and retrieving documents by using advanced search options

Owned by David Claudia
Last updated: Feb 02, 2024
2 min read

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

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

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

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.