Appearance
Get widget metadata ​
API ReferenceNote: The path is a placeholder. The actual path is determined by the configuration of the app component.
Get the metadata from the app server to render a widget.
OpenAPI definition ​
json
{
"openapi": "3.0.0",
"info": {
"description": "This is the interface for handling requests for app components. This reference is generated from an [OpenAPI spec] (https://raw.githubusercontent.com/Asana/openapi/master/defs/app_components_oas.yaml).",
"title": "App Components",
"termsOfService": "https://asana.com/terms",
"contact": {
"name": "Asana Support",
"url": "https://asana.com/support"
},
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0"
},
"version": "0.1",
"x-docs-schema-whitelist": [
"AttachedResourceResponse",
"FormField-Checkbox",
"FormField-Date",
"FormField-Datetime",
"FormField-Dropdown",
"FormField-MultiLineText",
"FormField-RadioButton",
"FormField-RichText",
"FormField-SingleLineText",
"FormField-StaticText",
"FormField-Typeahead",
"FormMetadataResponse",
"RanActionResponse",
"WidgetFooter-CustomText",
"WidgetFooter-Created",
"WidgetFooter-Updated",
"WidgetMetadataResponse",
"WidgetField-DatetimeWithIcon",
"WidgetField-Pill",
"WidgetField-TextWithIcon",
"TypeaheadListResponse",
"TypeaheadItem",
"FormValues",
"BadRequestResponse",
"UnauthorizedResponse",
"ForbiddenResponse",
"NotFoundResponse",
"InternalServerErrorResponse"
]
},
"x-readme": {
"explorer-enabled": false
},
"servers": [
{
"url": "{siteUrl}",
"description": "Main endpoint."
}
],
"tags": [
{
"name": "Widgets",
"description": "The widget is displayed when the user views a task with an attachment with a resource URL matching your capability’s `match_resource_url_pattern`. When this happens, Asana will make a signed request to your `widget_metadata_url`, and expect a response with information to render in the widget."
}
],
"components": {
"parameters": {
"attachment": {
"name": "attachment",
"required": true,
"in": "query",
"schema": {
"type": "string"
},
"description": "The attachment ID of the URL attachment."
},
"expires_at": {
"name": "expires_at",
"required": true,
"in": "query",
"schema": {
"type": "string"
},
"description": "The time (in ISO 8601 date format) when the request should expire."
},
"user": {
"name": "user",
"required": true,
"in": "query",
"schema": {
"type": "string"
},
"description": "The user GID this hook is coming from."
},
"resource_url": {
"name": "resource_url",
"required": true,
"in": "query",
"schema": {
"type": "string"
},
"description": "The URL of the URL attachment on the task (i.e., Jira issue, GitHub pull request)"
},
"task": {
"name": "task",
"required": true,
"in": "query",
"schema": {
"type": "string"
},
"description": "The task GID this hook is coming from."
},
"workspace": {
"name": "workspace",
"required": true,
"in": "query",
"schema": {
"type": "string"
},
"description": "The workspace GID this hook is coming from."
}
},
"responses": {
"BadRequest": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"Unauthorized": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"Forbidden": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForbiddenResponse"
}
}
}
},
"NotFound": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
}
},
"InternalServerError": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerErrorResponse"
}
}
}
}
},
"schemas": {
"BadRequestResponse": {
"description": "An error response object indicating a bad request (i.e., a status code of `400`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Illegal or malformed request."
}
}
},
"ForbiddenResponse": {
"description": "An error response object indicating a forbidden request (i.e., a status code of `403`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Access forbidden."
}
}
},
"InternalServerErrorResponse": {
"description": "An error response object indicating a request that could not be found (i.e., a status code of `500`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Internal server error."
}
}
},
"NotFoundResponse": {
"description": "An error response object indicating a request that could not be found (i.e., a status code of `404`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Not found."
}
}
},
"UnauthorizedResponse": {
"description": "An error response object indicating a unauthorized request (i.e., a status code of `401`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Authorization required."
}
}
},
"WidgetMetadataResponse": {
"description": "An object containing information about the widget.",
"type": "object",
"required": [
"metadata",
"template"
],
"properties": {
"template": {
"description": "The interface name and version of a distinct widget UI layout. A `template` is directly associated with a particular `metadata` schema.",
"type": "string",
"enum": [
"summary_with_details_v0"
],
"example": "summary_with_details_v0"
},
"metadata": {
"description": "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`.",
"type": "object",
"required": [
"fields",
"footer",
"title"
],
"properties": {
"title": {
"description": "The text to show in the title of the widget. Max length of 200 characters.",
"type": "string",
"example": "Status"
},
"fields": {
"description": "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.\n\nValid object schemas: [WidgetField-DatetimeWithIcon](/reference/app-components-widgets/widgets#widgetfield-datetimewithicon), [WidgetField-Pill](/reference/app-components-widgets/widgets#widgetfield-pill), [WidgetField-TextWithIcon](/reference/app-components-widgets/widgets#widgetfield-textwithicon).",
"type": "array"
},
"subtitle": {
"description": "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.",
"type": "string",
"example": "Custom App Story · Open in Custom App"
},
"subicon_url": {
"description": "The URL of the subicon next to the subtitle . If not provided, no icon will be shown.",
"type": "string",
"example": "https://example-icon.png"
},
"footer": {
"type": "object",
"description": "Contains the information to display a footer on the widget.\n\nValid schemas: [WidgetFooter-Created](/reference/app-components-widgets/widgets#widgetfooter-created), [WidgetFooter-CustomText](/reference/app-components-widgets/widgets#widgetfooter-customtext), [WidgetFooter-Updated](/reference/app-components-widgets/widgets#widgetfooter-updated)."
},
"num_comments": {
"description": "The number of comments to display on the lower right corner of the widget. If not provided, no comment count will be shown",
"type": "integer",
"example": 2
}
}
}
}
}
}
},
"paths": {
"/widget_metadata_url_path_placeholder": {
"parameters": [
{
"$ref": "#/components/parameters/resource_url"
},
{
"$ref": "#/components/parameters/workspace"
},
{
"$ref": "#/components/parameters/task"
},
{
"$ref": "#/components/parameters/user"
},
{
"$ref": "#/components/parameters/attachment"
},
{
"$ref": "#/components/parameters/expires_at"
}
],
"get": {
"summary": "Get widget metadata",
"description": "_Note: The path is a placeholder. The actual path is determined by the configuration of the app component._\n\nGet the metadata from the app server to render a widget. <br> <br> <a href=\"https://d3ki9tyy5l5ruj.cloudfront.net/obj/92841480867031372af8983f2906d26fbff6a2cc/ac-widget-metadata.png\">\n \n</a>",
"tags": [
"Widgets"
],
"operationId": "getWidgetMetadata",
"responses": {
"200": {
"description": "Successfully retrieved the metadata for a single widget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WidgetMetadataResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"418": {
"$ref": "#/components/responses/Unauthorized"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
}
}
}