List Library Documents

Use this REST API to retrieve a list of documents based on the filter criteria specified in the query parameter. After listing documents, you can use them as input for other actions, such as deleting documents in bulk.

This API allows you to:

• Retrieve all documents
• Retrieve documents with a specific path
• Retrieve documents by ID
• Retrieve multiple documents by ID array
• Retrieve specific fields only
• Retrieve documents by parent folder ID, filtered by MIME type, and with a combination of filters
• Paginate results
• Sort documents by name (ascending)
• Sort documents by name (descending)

You can use the Inbox/Outbox Explorer to view details on the listed files. Use the Download REST API to download files.

Using this REST API requires prerequisites, such as understanding how to use jobs. See Prerequisites. Be sure that you understand how to use jobs as described in Managing Jobs. For additional details, see Job Types.

Before using the REST resources, you must understand how to access the REST resources and other important concepts. See Implementation Best Practices for Cloud EPM REST APIs.

Required Roles

Service Administrator

REST Resource

GET HyperionPlanning/rest/v3/applications/{application}/documents

Request

Supported Media Types: application/json

Parameters

The following table summarizes the client request parameters specific to this job. For additional parameters that are common to all jobs, see Execute a Job.

Table 8-46 Parameters

Name	Description	Type	Default	Required
offset	Index (0-based) from which records are returned	Integer	0	No
limit	Number of items to return	Integer	25	No
fields	Comma-separated list of field names to be returned	String	None	No
path	The path for the documents if retrieving them with a specific path	String	None	No
orderBy	The order in which results are returned, optionally followed by :asc or :desc (such as name:asc). Sorting fields should match document properties	String	None	No

Example URL

https://<BASE-URL>/HyperionPlanning/rest/v3/applications/{application}/documents?q={"path":"/Library/sample.doc"}

Example queries:

Example 1: Retrieve all documents

GET /HyperionPlanning/rest/v3/applications/{application}/documents

Example 2: Retrieve documents with a specific path

GET /HyperionPlanning/rest/v3/applications/{application}/documents?q={"path":"/Library/sample.doc"}

Example 3: Retrieve documents by ID

GET /HyperionPlanning/rest/v3/applications/{application}/documents?q={"id":"3bbd16df-4da0-4e04-0000-c3c3f3c5ca96"}

Example 4: Retrieve multiple documents by ID array

GET /HyperionPlanning/rest/v3/applications/{application}/documents?q={"id": {"$in": ["3bbd16df-4da0-4e04-0000-c3c3f3c5ca96", "a4a788e5-97cd-44fc-0000-0009642a266b"]}}

Example 5: Retrieve specific fields only

GET /HyperionPlanning/rest/v3/applications/{application}/documents?q={"id":"a4a788e5-97cd-44fc-0000-0009642a266b"}&fields=id,name

Example 6: Paginate results

GET /HyperionPlanning/rest/v3/applications/{application}/documents?offset=10&limit=5

Example 7: Sort documents by name (ascending)

GET /HyperionPlanning/rest/v3/applications/{application}/documents?orderBy=name:asc

Example 8: Sort documents by name (descending)

GET /HyperionPlanning/rest/v3/applications/{application}/documents?orderBy=name:desc

Response

Supported Media Types: application/json

Example of Response Body

The following shows an example of the response body in JSON format.

{
    "totalResults": 2,
    "items": [
        {
            "name": "page1.doc",
            "displayName": "page1.doc",
            "description": "Pagination test 1",
            "objectType": "Document",
            "path": "/Library/page1.doc",
            "displayPath": "/Library/page1.doc",
            "parentId": "0c000b50-25f1-48f9-0000-c385c846b761",
            "created": "26/02/25 12:33 PM",
            "modified": "26/02/25 12:33 PM",
            "modifiedBy": "epm_default_cloud_admin",
            "access": [
                "Read",
                "Manage"
            ],
            "operations": [
                "Rename",
                "Update",
                "Move",
                "Delete",
                "AssignAccess"
            ],
            "id": "0c000b50-25f1-48f9-0000-0016c4e2a558",
            "mimeType": "application/msword"
        },
        {
            "name": "page10.doc",
            "displayName": "page10.doc",
            "description": "Pagination test 10",
            "objectType": "Document",
            "path": "/Library/page10.doc",
            "displayPath": "/Library/page10.doc",
            "parentId": "da2f51ec-d322-48a7-0000-c386676eba9d",
            "created": "26/02/25 12:33 PM",
            "modified": "26/02/25 12:33 PM",
            "modifiedBy": "epm_default_cloud_admin",
            "access": [
                "Read",
                "Manage"
            ],
            "operations": [
                "Rename",
                "Update",
                "Move",
                "Delete",
                "AssignAccess"
            ],
            "id": "0c000b50-25f1-48f9-0000-c3c4cfc98fb2",
            "mimeType": "application/msword"
        }
    ],
    "hasMore": false,
    "links": [
        {
            "href": "{{protocol}}://{{hostname}}:{{port}}/HyperionPlanning/rest/v3/applications/{{application}}/documents",
            "rel": "self",
            "method": "GET"
        }
    ]
}