Folder API

This article describes endpoints available for configuration of Folders and Folder Elements.

  • /api/folder: Retrieve, create, update, and delete Folders/Sub-Folders.
  • /api/folder_element: Retrieve, add, bulk add, and remove Elements from Folders.

Prerequisites:

Table of contents:

  1. Access Admin > System > API Toolkit
  2. Configure Folder
    1. Get All Folders
    2. Get a Specified Folder
    3. Create Folder
      1. Create Sub-Folder
    4. Update Folder
      1. Update Sub-Folder
      2. Copy Or Move Folder
    5. Delete Folder
  3. Configure Folder Elements
    1. Get Folder Elements
    2. Add Element to Folder
    3. Bulk Add Folder Elements
    4. Delete Element from Folder
  4. Code Snippets
    1. Folders Elements

1. Access Admin > System > API Toolkit

2. Configure Folders

2.1. Get All Folders

  • GET request to /api/folder retrieves all Folders.
  1. Item: folder
  2. Method: GET
  3. Enter an API Token
  4. [Run request]

Example Response 

{
  "folders": [
    {
      "user_id": 118,
      "category_id": 0,
      "favorite_id": 0,
      "folder_id": 241,
      "parent_category_id": 0,
      "parent_folder_id": null,
      "source_shared_favorite_id": null,
      "copied_from_favorite_id": null,
      "name": "Dashboard Element Test",
      "ancestors": "",
      "folder_ancestors": null,
      "type": "Folder",
      "shared_by": null,
      "source_propagate_display_order_changes_ind": "N",
      "sort_order_owner_id": null,
      "sort_order_modified_by_owner_ind": "N",
      "viewer_metadata": "Y",
      "favorite_content": null,
      "description": "",
      "is_edit_access_ind": "Y",
      "order_by": 1,
      "display_order": 1130000
    }
  ]
}

Fields Description

Field NameValue TypeDescription
folders
arrayAn array with all Folder data.
user_id
integerThe ID of the User who ran the API request.
folder_id
integerThe ID of the Folder.
parent_folder_id
integerThe ID of the parent Folder. Returns null if the folder is a top-level Folder.
name
stringThe name of the Folder.
folder_ancestors
string

Comma-separated list of ancestor Folder IDs, ordered from the top-level folder down to the immediate parent. Returns null if the Folder has no parent Folders.

description
stringThe description of the Folder.
is_edit_access_ind
stringWhether or not the User who ran the API request has edit access to the Folder. Takes value "Y" if the User has edit access, "N" - if not.
display_order
integerThe numeric value that determines the display order of the Folder on the homepage. Lower value = earlier in the list.

2.2. Get a Specified Folder

  • GET request to /api/folder/id/<ID> retrieves a specified Folder.
  1. Item: folder
  2. Methods: GET
  3. Enter the ID of the Folder or Sub-Folder which data needs to be retrieved.
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an object with Folder's data.

Example Response 

{
  "folder": {
    "id": 279,
    "name": "Robert's Folder",
    "description": "This is my new folder",
    "visible": "Y",
    "visible_on_mobile": "Y",
    "include_in_export": "N"
  }
}

NOTE: For Sub-Folders, only id, parent_folder_id, and name are returned.

Fields Description

Field NameValue TypeDescription
folder
objectObject containing Folder information.
id
stringThe ID of the Folder.
name
stringThe name of the Folder.
description
stringThe description of the Folder.
visible
stringWhether the Folder is displayed on the homepage. («Y/N»)
visible_on_mobile
stringWhether the Folder is displayed in mobile app.(«Y/N»)

2.3. Create Folder

  • POST request to /api/folder with body {"name": "<name>", "visible": "<Y/N>", "visible_on_mobile": "<Y/N>"} creates a new Folder.
  1. Item: folder
  2. Methods: POST
  3. Enter ID of an existing Folder
  4. Select JSON request and enter JSON providing the needed values for your Folder. See Fields Description for details:
{
  "name": "<Folder_Name>",
  "visible": "<Y/N>",
  "visible_on_mobile": "<Y/N>",
  "include_in_export": "<Y/N>"
}
  1. Enter an API Token
  2. [Run request]
  3. The returned object contains an object with Folder's data.

2.3.1. Create Sub-Folder

  • POST request to /api/folder with body {"parent_folder_id": "<ID>", "name": "<name>"} creates a new Sub-Folder.
  1. Item: folder
  2. Methods: POST
  3. Enter ID of an existing Folder
  4. Select JSON request and replace request with the following JSON providing the needed values:
{
    "parent_folder_id": <Parent Folder ID>,
    "name": "<Sub-Folder name>"
}
  1. Enter an API Token
  2. [Run request]
  3. The returned object contains an object with Sub-Folder's data.

2.4. Update Folder

  • PUT request to /api/folder with body {"name": "<name>", "visible": "<Y/N>", "visible_on_mobile": "<Y/N>"} updates an existing Folder.
  1. Item: folder
  2. Methods: PUT
  3. Enter ID of the Folder which data needs to be updated
  4. Select JSON request and enter JSON with the updated Folder's data:
  5. Enter an API Token
  6. [Run request]
  7. The returned object contains an array with an object with the updated Folder's data.

2.4.1. Update Sub-Folder

  • PUT request to /api/folder with body {"parent_folder_id": "<ID>", "name": "<name>"} updates an existing Sub-Folder.
  1. Item: folder
  2. Methods: PUT
  3. Enter ID of the Sub-Folder which data needs to be updated
  4. Select JSON request and replace request with the following JSON providing the needed values:
{
    "parent_folder_id": <Parent Folder ID>,
    "name": "<Sub-Folder Name>"
}
  1. Enter an API Token
  2. [Run request]
  3. The returned object contains an array with an object with the updated Folder's data.

2.4.2. Copy Or Move Folder Or Sub-Folder

  • PUT request to /api/folder with body {"call": "copy", "target_folder_id": "<ID>"} creates a copy of the specified Folder inside of the target Folder.
  • PUT request to /api/folder with body {"call": "move", "target_folder_id": "<ID>"} moves the specified Folder inside the target Folder.
  1. Item: folder
  2. Method: PUT
  3. Enter ID of the Folder or Sub-Folder which needs to be copied or moved
  4. Actions:
    • Copy: A copy of the selected Folder is created inside of the target Folder.
    • Move: Selected Folder is moved inside the target Folder.
  5. Select JSON request and assign target_folder_id the ID of the target Folder
  6. Enter an API Token
  7. [Run request]

2.5. Delete Folder Or Sub-Folder

  • POST request to /api/folder/id/<ID> deletes the specified Folder or Sub-Folder.
  1. Item: folder
  2. Methods: DELETE
  3. Enter ID of the Folder or Sub-Folder which needs to deleted
  4. Enter an API Token
  5. [Run request]

3. Configure Folder Elements

3.1. Get Folder Elements

Note: Beginning v6.4.3, this API request returns only Elements that are placed in the Folder, without Elements with Discoverability.

  1. Item: folder_element
  2. Methods: GET
  3. Use one of the following parameters to retrieve Folder's data:
    • folder_id: Enter Folder ID
    • folder_name: Enter Folder Name
  4. Enter an API Token
  5. [Run request]
  6. The returned object contains an object with Folder elements' data.
  7. See Example Response and Fields Description for details.
Expand or collapse content Example Response 
{
  "folder_elements": [
    {
      "user_dashboard_element_instance_id": 311,
      "user_id": 192,
      "element_id": 1279,
      "segment_value_id": 0,
      "section_type": "Favorite",
      "favorite_id": 532,
      "category_id": 0,
      "element_type": "external report",
      "in_dashboard_ind_flag": "Y",
      "last_stoplight_value": 0,
      "is_expired": 1,
      "element_name": "Tableau Worldwide Sales Analysis",
      "is_owned": 0,
      "topics": "101,177",
      "refresh_frequency_text": "Daily",
      "refresh_frequency_sec": 86400,
      "description_markdown_ind": "N",
      "element_info": "Daily sales data in Tableau, updated at 3am PST",
      "metric_unit_of_measure": null,
      "last_measurement_time": null,
      "external_report_download_url_info": "",
      "certified_ind": "Y",
      "certification_level_id": 1,
      "last_certified_time": "2021-10-13 23:06:07",
      "metric_display_on_tile": "value",
      "metric_moving_average_interval": null,
      "metric_display_on_tile_prefix": null,
      "metric_home_page_compare_value_type": "last value",
      "metric_home_page_compare_line_id": null,
      "metric_home_page_compare_target_id": null,
      "report_single_unit_label": null,
      "report_multiple_units_label": null,
      "report_no_units_label": null,
      "report_on_demand_generation_ind": "Y",
      "external_report_display": "iframe",
      "external_report_url": "https://tableau-prod.metricinsights.com/t/MI-Demo/views/SalesAnalysis/SalesAnalysis",
      "publicly_visible_ind": "Y",
      "certification_level_name": "Bronze",
      "certification_level_color": "#cd7f32",
      "last_certified_by_name": "Anna Kennedy",
      "last_certified_by_email": "[email protected]",
      "business_owner": "Grayson Stebbins",
      "business_owner_email": "[email protected]",
      "data_steward": null,
      "data_steward_email": null,
      "technical_owner": "Grayson Stebbins",
      "technical_owner_email": "[email protected]",
      "data_source_name": "Tableau - Prod_MI-Demo",
      "supports_last_refreshed_check": "none",
      "display_order": 1,
      "total_view_count": null,
      "in_favorites": "532",
      "is_in_favorites": 0,
      "is_in_folders": 0,
      "mi_name": "Daily",
      "mi_sequence": 30,
      "pct_variance_text": "from last day",
      "last_measurement_value_formatted": null,
      "last_measurement_time_formatted": null,
      "metric_last_moving_average_value_formatted": null,
      "last_updated_time": "2019-04-05 19:06:03",
      "total_forecast_amount_formatted": null,
      "last_activity_time": null,
      "last_annotation_text": null,
      "last_commentary_text": "Canada Manager: In Canada, we noticed that our Toronto store has maintained the same walk-in traffic as before, while at the same time noticing an increase in our website sales.",
      "element_dashboard_name": "Tableau Worldwide Sales Analysis",
      "element_dashboard_name_with_formatting": null,
      "is_empty_instance_ind": "N",
      "metric_tile_display_pct_variance": null,
      "report_rows": null,
      "last_display_generation_time": "2019-04-02 15:08:38",
      "last_file_updated_time": "",
      "last_modified": "unknown",
      "favorite_content": "wisdom of crowds",
      "alert_event_id": null,
      "last_alert_text": null,
      "last_alert_news_type": null,
      "is_alert_active": 0,
      "is_collaborative_alert_active": 0,
      "is_collaborative_annotation_active": 0,
      "is_annotation_active": 0,
      "is_commentary_active": 1,
      "last_notable_event_activity_time": null,
      "last_user_annotation_activity_time": null,
      "last_user_note_activity_time": null,
      "last_alert_event_activity_time": null,
      "reporting_tool_name": "Tableau",
      "remove_preview_link_ind": "N",
      "is_tech_editor": "N",
      "external_content_type_name": null,
      "enable_click_in_mobile_ind": "Y",
      "content_type": "Tableau",
      "global_total_view_count": 2,
      "has_access": "Y"
    },
  ],
  "folder_items": []
}

Fields Description

This description covers only the fields that contain information useful for App (Portal Page) development, the fields that are not covered are for  internal use only.

Field NameValue TypeDescription
folder_elementsarrayAn array containing folder_elements data entries.
user_dashboard_element_instance_idintegerA unique ID of the element record.
user_idintegerThe ID of the user who ran the API request.
element_idintegerThe ID of the element.
segment_value_idintegerThe dimension value of the element.
favorite_idintegerThe IDs of the element instances in favorites.
category_idintegerThe ID of the element's category.
element_typestringThe type of the element.
in_dashboard_ind_flagstringWhether or not the element is displayed on the dashboard.
is_expiredstringWhether or not the element is expired.
is_tech_editorstringWhether or not the user who ran the API request can edit the element. Takes value "Y" if the user can edit the element, "N" - if not.
is_ownedintegerWhether or not the element has an owner. Takes value "1" if the element has an owner, "0" - if not.
topicsarrayAn array of the element's tags' IDs.
refresh_frequency_secintegerThe frequency of element refresh in seconds.
enabled_indstringWhether the Element is enabled («Y»/«N»).
description_markdown_indstringWhether or not markdown is applied to the element's description. Takes value "Y" if markdown is enabled, "N" - if not.
external_report_download_url_infoobjectInformation about element download.
certified_indstringWhether or not the element is certified. Takes value "Y" if the element is certified, "N" - if not.
certification_level_idintegerThe ID of the certification level.
last_certified_timestringThe date and time of the last certification of the element.
external_report_displaystringIf the element is an External Report, describes its display options.
external_report_urlstringThe URL of the External Report or External Content in a native BI tool.
certification_level_namestringThe name of the certification level.
certification_level_colorstringThe hex value of the certification level color.
last_certified_by_namestringThe name of the user who certified the element.
last_certified_by_emailstringThe email of the user who certified the element.
business_ownerstringThe name of the Element Business Owner.
business_owner_emailstringThe email of the Element Business Owner.
data_stewardstringThe name of the element's Data Steward.
data_steward_emailstringThe email of the element's Data Steward.
technical_ownerstringThe element's Technical Owner.
technical_owner_emailstringThe email of the element's Technical Owner.
data_source_namestringThe name of the data source from which the element is populated.
total_view_countintegerThe engagement count of the element.
in_favoritesstringThe IDs of favorites where the element is present.
is_in_favoritesintegerWhether or not the element is in favorites. Takes value "1" if the element is in favorites, "0" - if not.
is_in_foldersintegerWhether or not the element is in any folder. Takes value "1" if the element is in any folder, "0" - if not.
metric_last_moving_average_value_formattedstringThe last collected value of a metric.
last_updated_timestringThe date and time of the last element update.
last_activity_timestringThe date and time of the last element activity.
last_annotation_textstringThe text of the last annotation.
last_commentary_textstringThe text of the last comment.
element_dashboard_namestringThe name of the element.
is_empty_instance_indstringWhether or not the last instance of the report is empty.
metric_tile_display_pct_variancestringThe percentage ratio between the two latest metric values.
favorite_contentstringThe type of favorite content.
content_type_aliasstringHuman-readable alias of the content type. Supported values:
  • metric
  • report
  • External Report’s source BI tool name
  • other
reporting_tool_namestringIf the element is an External Report, displays the name of the BI tool from which the element is populated.
external_content_type_namestringIf the element is an External Content, describes its type.
enable_click_in_mobile_indstringIf the element is an External Report or External Content, defines whether or not the "Enable click-through" option is activated for its content type.
content_typestringThe type of the content.
global_total_view_countintegerThe engagement count of the element.
has_accessstringWhether or not the user who ran the API request has access to the element.

3.2. Add Element to Folder

  1. Item: folder_element
  2. Methods: POST
  3. Enter any number
  4. Select JSON request and enter JSON providing the needed values for the following parameters:
    • folder_id: ID of the Folder.
    • elements: ID of the Element that needs to be added to the Folder.
  5. Enter an API Token
  6. [Run request]

3.3. Bulk Add Folder Elements

Bulk adding Folder elements is not available in API toolkit but can be performed via direct API request to the /api/folder_element endpoint:

$.ajax({
    url: '/api/folder_element',
    type: 'POST', 
    data: {
        folder_id: '<Folder ID>', 
        elements:['<Element 1 ID>', '<Element 2 ID>']  
    }    
});

Assigning values to the following parameters:

  • folder_id: A string containing ID of the Folder
  • elements: An array of strings containing IDs of the elements that need to be added to the Folder

Example request:

$.ajax({
    url: '/api/folder_element',
    type: 'POST', 
    data: {
        folder_id: "258", 
        elements:['1700', '122483']  
    }    
});

3.4. Delete Element from Folder

Deleting an element from Folder is not available in API toolkit but can be performed via direct API request to the /api/folder_element endpoint: 

$.ajax({
    url: '/api/folder_element',
    type: 'DELETE', 
    data: {
        folder_id: '<Folder ID>', 
        elements:['<Element 1 ID>', '<Element 2 ID>']  
    }    
});

Assigning values to the following parameters:

  • folder_id: A string containing ID of the Folder
  • elements:
    • A single string containing ID of the element, if only one element needs to be deleted, or
    • An array of strings containing IDs of the elements that need to be deleted from the Folder

Example request:

$.ajax({
    url: '/api/folder_element',
    type: 'DELETE', 
    data: {
        folder_id: "258", 
        elements:['1700', '122484']  
    }    
});

4. Code Snippets

4.1. Folders Elements

The following API call returns an array of all Folder elements from Folders available on the Homepage:

$.ajax({
    url: '/api/element?folder_items=Y', 
    type: 'GET', 
    dataType: 'json', 
}).then(res=>{console.log(res.folderItems)})

The following API call returns an array of all Folder elements including the Folders hidden from the Homepage:

$.ajax({
  url: '/api/element?folder_items=Y&all_folders=Y', 
  type: 'GET', 
  dataType: 'json', 
}).then(res=>{console.log(res.folderItems)})

Example Response 

[
   {
     "folder_item_id": "3644700",
     "folder_id": "171",
     "element_id": "1247",
     "segment_value_id": "1",
     "display_order": "1"
   },
   {
     "folder_item_id": "3644699",
     "folder_id": "171",
     "element_id": "1247",
     "segment_value_id": "2596",
     "display_order": "2"
   },
]

Fields Description

Field Name Value Type Description
folder_item_id string The ID of the folder item unique for each element.
folder_id string The ID of the folder.
element_id string The ID of the element.
segment_value_id string The dimension value of the element.
display_order string The order in which the element is displayed in the Folder.