External Content API

This article describes the API endpoints used to manage External Content: dashboard elements that display embedded web pages, uploaded images, or linked files. The following endpoints are covered:

  • /api/external_content: Retrieve, create, update, and delete External Content objects.

Prerequisites:

NOTES: Access requirements differ per method:

  • GET: Requires View access to the External Content element.
  • PUT, DELETE: Require Edit access to the External Content element.
  • POST: Requires an Admin or a Power User.

Table of Contents

  1. Retrieve External Content
  2. Create External Content
  3. Update External Content
  4. Delete External Content

1. Retrieve External Content

  • A GET request to /api/external_content returns a list of all External Content objects.
  • A GET request to /api/external_content/id/<ID> returns the specified External Content object.
  1. Item: external_content
  2. Method: GET
  3. ID: Leave empty to list all items, or input the ID of an existing External Content to retrieve a single object.
  4. Query parameters: Optional; used with the list call to filter results (for example, data_source, data_source_external_report, data_source_parameter_name, data_source_parameter_value). Leave empty to return all objects.
  5. Enter an API Token.
  6. [Run request]

Example Response

A single-item request returns the record in the external_content object; the list call returns the records in an external_contents array.

{
    "external_content": {
        "id": 123,
        "name": "My External Content",
        "description": "",
        "category": 1,
        "external_content_url": "https://example.com/embedded-page",
        "plugin_connection_profile_id": null,
        "external_report_reference_id": "",
        "content_type_alias": "other",
        "business_owner_id": 5,
        "data_steward_id": 5,
        "technical_owner_id": 5
    }
}

Fields Description

Parameter NameValue TypeDescription
id
integerThe ID of the External Content.
name
stringThe name of the External Content.
description
stringThe description of the External Content.
category
stringThe Category associated with the External Content.
external_content_url
stringThe URL of the External Content.
plugin_connection_profile_id
integerThe ID of the Plugin Connection Profile associated with the External Content.
external_report_reference_id
integerThe External Report Reference ID for plugin-based content.
content_type_alias
stringThe alias of the content type.
business_owner_id
integerThe User ID of the Business Owner of the External Content.
data_steward_id
integerThe User ID of the Data Steward of the External Content.
technical_owner_id
integerThe User ID of the Technical Owner of the External Content.

2. Create External Content

A POST request to /api/external_content creates a new External Content object based on an External Content template.

  1. Item: external_content
  2. Methods: POST
  3. Request: Provide the JSON body with a valid template ID and any additional fields (see POST Parameters Description).
  4. Enter an API Token.
  5. [Run request]

POST Parameters Description

FieldValue TypeDescription
templateintegerTemplate ID used to initialize the new External Content. Required, and must be a valid External Content Template. 
  • To locate the External Content Template ID: Access Admin > Reference Objects > Object Templates > External Content > Open an External Content Template, its ID can be found in the URL: <MI instance>/editor/template/external-content/<ID>#info
namestringDisplay name of the External Content. If not provided, it is auto-generated.
external_content_urlstringThe URL of external web content to embed. Cannot be used together with external_report_reference_id when the content type requires a plugin source.
external_report_reference_idintegerReference to an External Report from a connected plugin (e.g., Tableau, Power BI). When provided, must match the content type's source plugin.

3. Update External Content

A PUT request to /api/external_content/id/<ID> updates the specified External Content object.

  1. Item: external_content
  2. Methods: PUT
  3. ID: Input the ID of the External Content to update.
  4. Request: Provide the JSON body with the fields to change, the allowed fields are: name, category, external_content_url/external_report_reference_id, business_owner_id, technical_owner_id.
  5. Enter an API Token.
  6. [Run request]

4. Delete External Content

A DELETE request to /api/external_content/id/<ID> deletes the specified External Content object.

  1. Item: external_content
  2. Methods: DELETE
  3. ID: Enter the ID of the External Content to delete.
  4. Enter an API Token.
  5. [Run request]