Back to AsanaCreate A Story On A Task
Adds a story to a task. This endpoint currently only allows for comment
stories to be created. The comment will be authored by the currently
authenticated user, and timestamped when the server receives the request.
Returns the full record for the new story added to the task.
Input
type: object
properties:
parameters:
type: object
properties:
task_gid:
type: string
description: The task to operate on.
opt_pretty:
type: boolean
description: >-
Provides “pretty” output.
Provides the response in a “pretty” format. In the case of JSON this
means doing proper line breaking and indentation to make it readable.
This will take extra time and increase the response size so it is
advisable only to use this during debugging.
opt_fields:
type: array
items:
type: string
description: >-
Defines fields to return.
Some requests return *compact* representations of objects in order to
conserve resources and complete the request more efficiently. Other
times requests return more information than you may need. This option
allows you to list the exact set of fields that the API should be sure
to return for the objects. The field names should be provided as
paths, described below.
The id of included objects will always be returned, regardless of the
field options.
required:
- task_gid
title: Parameters
data:
type: object
properties:
data:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
created_at:
description: The time at which this resource was created.
type: string
format: date-time
readOnly: true
example: '2012-02-22T02:06:58.147Z'
resource_subtype:
description: >-
The subtype of this resource. Different subtypes retain many of
the same fields and behavior, but may render differently in Asana
or represent resources with different semantic meaning.
type: string
readOnly: true
example: comment_added
text:
description: >-
The plain text of the comment to add. Cannot be used with
html_text.
type: string
example: This is a comment.
html_text:
description: >-
[Opt In](/docs/inputoutput-options). HTML formatted text for a
comment. This will not include the name of the creator.
type: string
example: <body>This is a comment.</body>
is_pinned:
description: '*Conditional*. Whether the story should be pinned on the resource.'
type: boolean
example: false
sticker_name:
description: >-
The name of the sticker in this story. `null` if there is no
sticker.
type: string
enum:
- green_checkmark
- people_dancing
- dancing_unicorn
- heart
- party_popper
- people_waving_flags
- splashing_narwhal
- trophy
- yeti_riding_unicorn
- celebrating_people
- determined_climbers
- phoenix_spreading_love
example: dancing_unicorn
title: Data
Output
type: object
properties:
data:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
created_at:
description: The time at which this resource was created.
type: string
format: date-time
readOnly: true
example: '2012-02-22T02:06:58.147Z'
resource_subtype:
description: >-
The subtype of this resource. Different subtypes retain many of the
same fields and behavior, but may render differently in Asana or
represent resources with different semantic meaning.
type: string
readOnly: true
example: comment_added
text:
description: The plain text of the comment to add. Cannot be used with html_text.
type: string
example: This is a comment.
html_text:
description: >-
[Opt In](/docs/inputoutput-options). HTML formatted text for a
comment. This will not include the name of the creator.
type: string
example: <body>This is a comment.</body>
is_pinned:
description: '*Conditional*. Whether the story should be pinned on the resource.'
type: boolean
example: false
sticker_name:
description: The name of the sticker in this story. `null` if there is no sticker.
type: string
enum:
- green_checkmark
- people_dancing
- dancing_unicorn
- heart
- party_popper
- people_waving_flags
- splashing_narwhal
- trophy
- yeti_riding_unicorn
- celebrating_people
- determined_climbers
- phoenix_spreading_love
example: dancing_unicorn
created_by:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: '*Read-only except when same user as requester*. The user’s name.'
example: Greg Sanchez
type:
type: string
enum:
- comment
- system
readOnly: true
example: comment
is_editable:
description: >-
*Conditional*. Whether the text of the story can be edited after
creation.
type: boolean
readOnly: true
example: false
is_edited:
description: >-
*Conditional*. Whether the text of the story has been edited after
creation.
type: boolean
readOnly: true
example: false
hearted:
description: >-
*Deprecated - please use likes instead*
*Conditional*. True if the story is hearted by the authorized user,
false if not.
type: boolean
readOnly: true
example: false
hearts:
description: |-
*Deprecated - please use likes instead*
*Conditional*. Array of likes for users who have hearted this story.
type: array
readOnly: true
items:
type: object
properties:
gid:
description: Globally unique identifier of the object, as a string.
type: string
readOnly: true
example: '12345'
user:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: >-
*Read-only except when same user as requester*. The user’s
name.
example: Greg Sanchez
num_hearts:
description: |-
*Deprecated - please use likes instead*
*Conditional*. The number of users who have hearted this story.
type: integer
readOnly: true
example: 5
liked:
description: >-
*Conditional*. True if the story is liked by the authorized user,
false if not.
type: boolean
readOnly: true
example: false
likes:
description: '*Conditional*. Array of likes for users who have liked this story.'
type: array
readOnly: true
items:
type: object
properties:
gid:
description: Globally unique identifier of the object, as a string.
type: string
readOnly: true
example: '12345'
user:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: >-
*Read-only except when same user as requester*. The user’s
name.
example: Greg Sanchez
num_likes:
description: '*Conditional*. The number of users who have liked this story.'
type: integer
readOnly: true
example: 5
previews:
description: |-
*Conditional*. A collection of previews to be displayed in the story.
*Note: This property only exists for comment stories.*
type: array
readOnly: true
items:
type: object
properties:
fallback:
description: >-
Some fallback text to display if unable to display the full
preview.
type: string
example: >-
Greg: Great! I like this
idea.\n\nhttps//a_company.slack.com/archives/ABCDEFG/12345678
footer:
description: Text to display in the footer.
type: string
example: Mar 17, 2019 1:25 PM
header:
description: Text to display in the header.
type: string
example: Asana for Slack
header_link:
description: Where the header will link to.
type: string
example: https://asana.comn/apps/slack
html_text:
description: HTML formatted text for the body of the preview.
type: string
example: <body>Great! I like this idea.</body>
text:
description: Text for the body of the preview.
type: string
example: Great! I like this idea.
title:
description: Text to display as the title.
type: string
example: Greg
title_link:
description: Where to title will link to.
type: string
example: https://asana.slack.com/archives/ABCDEFG/12345678
old_name:
description: '*Conditional*'''
type: string
example: This was the Old Name
new_name:
description: '*Conditional*'
type: string
readOnly: true
example: This is the New Name
old_dates:
type: object
properties:
start_on:
description: >-
The day on which work for this goal begins, or null if the goal
has no start date. This takes a date with `YYYY-MM-DD` format, and
cannot be set unless there is an accompanying due date.
type: string
format: date
example: '2019-09-14T00:00:00.000Z'
nullable: true
due_at:
description: >-
The UTC date and time on which this task is due, or null if the
task has no due time. This takes an ISO 8601 date string in UTC
and should not be used together with `due_on`.
type: string
format: date-time
example: '2019-09-15T02:06:58.158Z'
nullable: true
due_on:
description: >-
The localized day on which this goal is due. This takes a date
with format `YYYY-MM-DD`.
type: string
format: date
example: '2019-09-15T00:00:00.000Z'
new_dates:
type: object
properties:
start_on:
description: >-
The day on which work for this goal begins, or null if the goal
has no start date. This takes a date with `YYYY-MM-DD` format, and
cannot be set unless there is an accompanying due date.
type: string
format: date
example: '2019-09-14T00:00:00.000Z'
nullable: true
due_at:
description: >-
The UTC date and time on which this task is due, or null if the
task has no due time. This takes an ISO 8601 date string in UTC
and should not be used together with `due_on`.
type: string
format: date-time
example: '2019-09-15T02:06:58.158Z'
nullable: true
due_on:
description: >-
The localized day on which this goal is due. This takes a date
with format `YYYY-MM-DD`.
type: string
format: date
example: '2019-09-15T00:00:00.000Z'
old_resource_subtype:
description: '*Conditional*'
type: string
readOnly: true
example: default_task
new_resource_subtype:
description: '*Conditional*'
type: string
readOnly: true
example: milestone
story:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
created_at:
description: The time at which this resource was created.
type: string
format: date-time
readOnly: true
example: '2012-02-22T02:06:58.147Z'
created_by:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: >-
*Read-only except when same user as requester*. The user’s
name.
example: Greg Sanchez
resource_subtype:
description: >-
The subtype of this resource. Different subtypes retain many of
the same fields and behavior, but may render differently in Asana
or represent resources with different semantic meaning.
type: string
readOnly: true
example: comment_added
text:
description: >-
*Create-only*. Human-readable text for the story or comment.
This will not include the name of the creator.
*Note: This is not guaranteed to be stable for a given type of
story. For example, text for a reassignment may not always say
“assigned to …” as the text for a story can both be edited and
change based on the language settings of the user making the
request.*
Use the `resource_subtype` property to discover the action that
created the story.
type: string
example: marked today
assignee:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: '*Read-only except when same user as requester*. The user’s name.'
example: Greg Sanchez
follower:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: '*Read-only except when same user as requester*. The user’s name.'
example: Greg Sanchez
old_section:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: >-
The name of the section (i.e. the text displayed as the section
header).
type: string
example: Next Actions
new_section:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: >-
The name of the section (i.e. the text displayed as the section
header).
type: string
example: Next Actions
task:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the task.
type: string
example: Bug Task
resource_subtype:
type: string
description: >-
The subtype of this resource. Different subtypes retain many of
the same fields and behavior, but may render differently in Asana
or represent resources with different semantic meaning.
The resource_subtype `milestone` represent a single moment in
time. This means tasks with this subtype cannot have a start_date.
enum:
- default_task
- milestone
- section
- approval
example: default_task
project:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: >-
Name of the project. This is generally a short sentence fragment
that fits on a line in the UI for maximum readability. However, it
can be longer.
type: string
example: Stuff to buy
tag:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: >-
Name of the tag. This is generally a short sentence fragment that
fits on a line in the UI for maximum readability. However, it can
be longer.
type: string
example: Stuff to buy
custom_field:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the custom field.
type: string
example: Status
resource_subtype:
description: |
The type of the custom field. Must be one of the given values.
type: string
example: text
enum:
- text
- enum
- multi_enum
- number
- date
- people
type:
description: >
*Deprecated: new integrations should prefer the resource_subtype
field.* The type of the custom field. Must be one of the given
values.
type: string
readOnly: true
enum:
- text
- enum
- multi_enum
- number
enum_options:
description: >-
*Conditional*. Only relevant for custom fields of type `enum`.
This array specifies the possible values which an `enum` custom
field can adopt. To modify the enum options, refer to [working
with enum options](/reference/createenumoptionforcustomfield).
type: array
items:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the enum option.
type: string
example: Low
enabled:
description: >-
Whether or not the enum option is a selectable value for the
custom field.
type: boolean
example: true
color:
description: The color of the enum option. Defaults to ‘none’.
type: string
example: blue
enabled:
description: '*Conditional*. Determines if the custom field is enabled or not.'
type: boolean
example: true
date_value:
type: object
properties:
date:
type: string
description: A string representing the date in YYYY-MM-DD format.
example: '2024-08-23T00:00:00.000Z'
date_time:
type: string
description: >-
A string representing the date in ISO 8601 format. If no time
value is selected, the value of `date-time` will be `null`.
example: '2024-08-23T22:00:00.000Z'
enum_value:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the enum option.
type: string
example: Low
enabled:
description: >-
Whether or not the enum option is a selectable value for the
custom field.
type: boolean
example: true
color:
description: The color of the enum option. Defaults to ‘none’.
type: string
example: blue
multi_enum_values:
description: >-
*Conditional*. Only relevant for custom fields of type
`multi_enum`. This object is the chosen values of a `multi_enum`
custom field.
type: array
items:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the enum option.
type: string
example: Low
enabled:
description: >-
Whether or not the enum option is a selectable value for the
custom field.
type: boolean
example: true
color:
description: The color of the enum option. Defaults to ‘none’.
type: string
example: blue
number_value:
description: >-
*Conditional*. This number is the value of a `number` custom
field.
type: number
example: 5.2
text_value:
description: '*Conditional*. This string is the value of a `text` custom field.'
type: string
example: Some Value
display_value:
description: >-
A string representation for the value of the custom field.
Integrations that don't require the underlying type should use
this field to read values. Using this field will future-proof an
app against new custom field types.
type: string
readOnly: true
example: blue
nullable: true
old_text_value:
description: '*Conditional*'
type: string
readOnly: true
example: This was the Old Text
new_text_value:
description: '*Conditional*'
type: string
readOnly: true
example: This is the New Text
old_number_value:
description: '*Conditional*'
type: integer
readOnly: true
example: 1
new_number_value:
description: '*Conditional*'
type: integer
readOnly: true
example: 2
old_enum_value:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the enum option.
type: string
example: Low
enabled:
description: >-
Whether or not the enum option is a selectable value for the
custom field.
type: boolean
example: true
color:
description: The color of the enum option. Defaults to ‘none’.
type: string
example: blue
new_enum_value:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the enum option.
type: string
example: Low
enabled:
description: >-
Whether or not the enum option is a selectable value for the
custom field.
type: boolean
example: true
color:
description: The color of the enum option. Defaults to ‘none’.
type: string
example: blue
old_date_value:
type: object
properties:
start_on:
description: >-
The day on which work for this goal begins, or null if the goal
has no start date. This takes a date with `YYYY-MM-DD` format, and
cannot be set unless there is an accompanying due date.
type: string
format: date
example: '2019-09-14T00:00:00.000Z'
nullable: true
due_at:
description: >-
The UTC date and time on which this task is due, or null if the
task has no due time. This takes an ISO 8601 date string in UTC
and should not be used together with `due_on`.
type: string
format: date-time
example: '2019-09-15T02:06:58.158Z'
nullable: true
due_on:
description: >-
The localized day on which this goal is due. This takes a date
with format `YYYY-MM-DD`.
type: string
format: date
example: '2019-09-15T00:00:00.000Z'
new_date_value:
type: object
properties:
start_on:
description: >-
The day on which work for this goal begins, or null if the goal
has no start date. This takes a date with `YYYY-MM-DD` format, and
cannot be set unless there is an accompanying due date.
type: string
format: date
example: '2019-09-14T00:00:00.000Z'
nullable: true
due_at:
description: >-
The UTC date and time on which this task is due, or null if the
task has no due time. This takes an ISO 8601 date string in UTC
and should not be used together with `due_on`.
type: string
format: date-time
example: '2019-09-15T02:06:58.158Z'
nullable: true
due_on:
description: >-
The localized day on which this goal is due. This takes a date
with format `YYYY-MM-DD`.
type: string
format: date
example: '2019-09-15T00:00:00.000Z'
old_people_value:
description: '*Conditional*. The old value of a people custom field story.'
type: array
readOnly: true
items:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: '*Read-only except when same user as requester*. The user’s name.'
example: Greg Sanchez
new_people_value:
description: '*Conditional*. The new value of a people custom field story.'
type: array
readOnly: true
items:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
type: string
description: '*Read-only except when same user as requester*. The user’s name.'
example: Greg Sanchez
old_multi_enum_values:
description: '*Conditional*. The old value of a multi-enum custom field story.'
type: array
readOnly: true
items:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the enum option.
type: string
example: Low
enabled:
description: >-
Whether or not the enum option is a selectable value for the
custom field.
type: boolean
example: true
color:
description: The color of the enum option. Defaults to ‘none’.
type: string
example: blue
new_multi_enum_values:
description: '*Conditional*. The new value of a multi-enum custom field story.'
type: array
readOnly: true
items:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the enum option.
type: string
example: Low
enabled:
description: >-
Whether or not the enum option is a selectable value for the
custom field.
type: boolean
example: true
color:
description: The color of the enum option. Defaults to ‘none’.
type: string
example: blue
new_approval_status:
description: '*Conditional*. The new value of approval status.'
type: string
readOnly: true
example: approved
old_approval_status:
description: '*Conditional*. The old value of approval status.'
type: string
readOnly: true
example: pending
duplicate_of:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the task.
type: string
example: Bug Task
resource_subtype:
type: string
description: >-
The subtype of this resource. Different subtypes retain many of
the same fields and behavior, but may render differently in Asana
or represent resources with different semantic meaning.
The resource_subtype `milestone` represent a single moment in
time. This means tasks with this subtype cannot have a start_date.
enum:
- default_task
- milestone
- section
- approval
example: default_task
duplicated_from:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the task.
type: string
example: Bug Task
resource_subtype:
type: string
description: >-
The subtype of this resource. Different subtypes retain many of
the same fields and behavior, but may render differently in Asana
or represent resources with different semantic meaning.
The resource_subtype `milestone` represent a single moment in
time. This means tasks with this subtype cannot have a start_date.
enum:
- default_task
- milestone
- section
- approval
example: default_task
dependency:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the task.
type: string
example: Bug Task
resource_subtype:
type: string
description: >-
The subtype of this resource. Different subtypes retain many of
the same fields and behavior, but may render differently in Asana
or represent resources with different semantic meaning.
The resource_subtype `milestone` represent a single moment in
time. This means tasks with this subtype cannot have a start_date.
enum:
- default_task
- milestone
- section
- approval
example: default_task
source:
description: The component of the Asana product the user used to trigger the story.
type: string
enum:
- web
- email
- mobile
- api
- unknown
readOnly: true
example: web
target:
type: object
properties:
gid:
description: Globally unique identifier of the resource, as a string.
type: string
readOnly: true
example: '12345'
x-insert-after: false
resource_type:
description: The base type of this resource.
type: string
readOnly: true
example: task
x-insert-after: gid
name:
description: The name of the task.
type: string
example: Bug Task
resource_subtype:
type: string
description: >-
The subtype of this resource. Different subtypes retain many of
the same fields and behavior, but may render differently in Asana
or represent resources with different semantic meaning.
The resource_subtype `milestone` represent a single moment in
time. This means tasks with this subtype cannot have a start_date.
enum:
- default_task
- milestone
- section
- approval
example: default_task