📘
Getting started
To get started, see widgets in the app components guide.

Schemas

WidgetMetadata

An object containing information about the widget. See get widget metadata.

Property	Type	Description
`metadata` (required)	object	The metadata (i.e., underlying definition) of a widget. `metadata` must exist alongside a `template`, and its schema must be specific to the value of that `template`.
» `error`	string	The error that should be displayed to the user.
» `fields` (required)	array	A list of fields showing data from external resources (i.e., an array of WidgetField objects). A widget must contain at least 1 field and no more than 5 fields. Valid object schemas: WidgetField-DatetimeWithIcon WidgetField-Pill WidgetField-TextWithIcon
» `footer` (required)	object	Contains the information to display a footer on the widget. Valid schemas: WidgetFooter-Created WidgetFooter-CustomText WidgetFooter-Updated
» `num_comments`	integer	The number of comments to display on the lower right corner of the widget. If not provided, no comment count will be shown
» `subicon_url`	string	The URL of the subicon next to the subtitle. If not provided, no icon will be shown.
» `subtitle`	string	The text to show under the title of the widget, next to "Open in {App Name}". If not provided, the `resource_name` from the app definition will be used as default.
» `title` (required)	string	The text to show in the title of the widget. Max length of 200 characters.
`template` (required)	string	The interface name and version of a distinct widget UI layout. A `template` is directly associated with a particular `metadata` schema.

{
  "metadata": {
    "error": "The resource cannot be accessed",
    "fields": [],
    "footer": {},
    "num_comments": 2,
    "subicon_url": "https://example-icon.png",
    "subtitle": "Custom App Story · Open in Custom App",
    "title": "Status"
  },
  "template": "summary_with_details_v0"
}

WidgetField-DatetimeWithIcon

A widget field that displays a timestamp and an optional icon.

Property	Type	Description
`datetime`	string	The time (in ISO 8601 date format) to display next to the icon.
`icon_url`	string	Optional. The URL of the icon to display next to the time.
`name` (required)	string	The text (i.e., label) to show in the title of the field. Limit 40 characters.
`type` (required)	string	The type of widget field.

{
  "datetime": "2012-02-22T02:06:58.147Z",
  "icon_url": "https://example-icon.png",
  "name": "Status",
  "type": "datetime_with_icon"
}

WidgetField-Pill

A widget field that displays custom text in a colored "pill" format.

Property	Type	Description
`color` (required)	string	The color of the pill.
`name` (required)	string	The text (i.e., label) to show in the title of the field. Limit 40 characters.
`text` (required)	string	The text to show in the field. Limit 40 characters.
`type` (required)	string	The type of widget field.

{
  "color": "cool-gray",
  "name": "Status",
  "text": "In Progress",
  "type": "pill"
}

WidgetField-TextWithIcon

A widget field that displays custom text with an optional icon.

Property	Type	Description
`icon_url`	string	Optional. The URL of the icon to display next to the text.
`name` (required)	string	The text (i.e., label) to show in the title of the field. Limit 40 characters.
`text` (required)	string	The text to show in the field. Limit 40 characters.
`type` (required)	string	The type of widget field.

{
  "icon_url": "https://example-icon.png",
  "name": "Status",
  "text": "In Progress",
  "type": "text_with_icon"
}

WidgetFooter-Created

A widget footer that displays the timestamp of the resource's creation time.

Property	Type	Description
`created_at` (required)	string	The time (in ISO 8601 date format) to show in the footer.
`footer_type` (required)	string	The type of widget footer.

{
  "created_at": "2012-02-22T02:06:58.147Z",
  "footer_type": "created"
}

WidgetFooter-CustomText

A widget footer that displays custom text and an optional icon.

Property	Type	Description
`footer_type` (required)	string	The text to show in the footer.
`icon_url`	string	Optional. The icon to show in the footer next to the text. If not provided, no icon will be shown.
`text` (required)	string	The text to show in the footer.

{
  "footer_type": "custom_text",
  "icon_url": "https://example-icon.png",
  "text": "This is a custom footer message"
}

WidgetFooter-Updated

A widget footer that displays the timestamp of the resource's last updated time.

Property	Type	Description
`footer_type` (required)	string	The type of widget footer.
`last_updated_at` (required)	string	The time (in ISO 8601 date format) to show in the footer.

{
  "footer_type": "updated",
  "last_updated_at": "2012-02-22T02:06:58.147Z"
}

Error schemas

BadRequest

An error response object indicating a bad request (i.e., a status code of 400).

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The error to display.

{
  "data": {
    "error": "Illegal or malformed request."
  }
}

Forbidden

An error response object indicating a forbidden request (i.e., a status code of 403).

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The error to display.

{
  "data": {
    "error": "Access forbidden."
  }
}

InternalServerError

An error response object indicating a request that could not be found (i.e., a status code of 500).

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The error to display.

{
  "data": {
    "error": "Internal server error."
  }
}

NotFound

An error response object indicating a request that could not be found (i.e., a status code of 404).

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The error to display.

{
  "data": {
    "error": "Not found."
  }
}

Unauthorized

An error response object indicating a unauthorized request (i.e., a status code of 401).

Property	Type	Description
`data`	object	An object containing an `error` string to display to the user.
» `error`	string	The error to display.

{
  "data": {
    "error": "Authorization required."
  }
}