Widgets

API Reference

📘

Getting started Skip link to Getting started

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

Schemas Skip link to Schemas

WidgetMetadata Skip link to 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.

JSON

{
  "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 Skip link to 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.

JSON

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

---

WidgetField-Pill Skip link to 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.

JSON

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

---

WidgetField-TextWithIcon Skip link to 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.

JSON

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

---

WidgetFooter-Created Skip link to 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.

JSON

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

---

WidgetFooter-CustomText Skip link to 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.

JSON

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

---

WidgetFooter-Updated Skip link to 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.

JSON

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

---

Error schemas Skip link to Error schemas

BadRequest Skip link to 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.

JSON

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

---

Forbidden Skip link to 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.

JSON

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

---

InternalServerError Skip link to 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.

JSON

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

---

NotFound Skip link to 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.

JSON

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

---

Unauthorized Skip link to 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.

JSON

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

Updated 8 months ago

---

Did this page help you?

Yes

No

Updated8 months ago

---

Did this page help you?

Yes

No