Asana
  1. Stories
Asana
  • Attachments
    • Delete an attachment
      DELETE
    • Get an attachment
      GET
    • Get attachments for a task
      GET
    • Upload an attachment
      POST
  • Batch API
    • Submit parallel requests
      POST
  • Custom Fields
    • Create a custom field
      POST
    • Delete a custom field
      DELETE
    • Get a custom field
      GET
    • Update a custom field
      PUT
    • Create an enum option
      POST
    • Reorder a custom field's enum
      POST
    • Update an enum option
      PUT
    • Get a workspace's custom fields
      GET
  • Events
    • Get events on a resource
      GET
  • Goals
    • Get goals
      GET
    • Create a goal
      POST
    • Delete a goal
      DELETE
    • Get a goal
      GET
    • Update a goal
      PUT
    • Add a collaborator to a goal
      POST
    • Add a subgoal to a parent goal
      POST
    • Add a project/portfolio as supporting work for a goal.
      POST
    • Get parent goals from a goal
      GET
    • Remove a collaborator from a goal
      POST
    • Remove a subgoal from a goal
      POST
    • Remove a project/portfolio as supporting work for a goal.
      POST
    • Create a goal metric
      POST
    • Update a goal metric
      POST
    • Get subgoals from a goal
      GET
    • Get supporting work from a goal
      GET
  • Jobs
    • Get a job by id
  • Organization Exports
    • Create an organization export request
    • Get details on an org export request
  • Teams
    • Get teams in an organization
    • Create a team
    • Get a team
    • Add a user to a team
    • Remove a user from a team
    • Get teams for a user
  • Portfolio Memberships
    • Get multiple portfolio memberships
    • Get a portfolio membership
    • Get memberships from a portfolio
  • Portfolios
    • Get multiple portfolios
    • Create a portfolio
    • Delete a portfolio
    • Get a portfolio
    • Update a portfolio
    • Add a custom field to a portfolio
    • Add a portfolio item
    • Add users to a portfolio
    • Get portfolio items
    • Remove a custom field from a portfolio
    • Remove a portfolio item
    • Remove users from a portfolio
  • Custom Field Settings
    • Get a portfolio's custom fields
    • Get a project's custom fields
  • Project Memberships
    • Get a project membership
    • Get memberships from a project
  • Project Statuses
    • Delete a project status
    • Get a project status
    • Get statuses from a project
    • Create a project status
  • Projects
    • Get multiple projects
    • Create a project
    • Delete a project
    • Get a project
    • Update a project
    • Add a custom field to a project
    • Add followers to a project
    • Add users to a project
    • Duplicate a project
    • Remove a custom field from a project
    • Remove followers from a project
    • Remove users from a project
    • Get task count of a project
    • Get projects a task is in
    • Get a team's projects
    • Create a project in a team
    • Get all projects in a workspace
    • Create a project in a workspace
  • Sections
    • Get sections in a project
    • Create a section in a project
    • Move or Insert sections
    • Delete a section
    • Get a section
    • Update a section
    • Add task to section
  • Tasks
    • Get tasks from a project
    • Get tasks from a section
    • Get tasks from a tag
    • Get multiple tasks
    • Create a task
    • Delete a task
    • Get a task
    • Update a task
    • Set dependencies for a task
    • Set dependents for a task
    • Add followers to a task
    • Add a project to a task
    • Add a tag to a task
    • Get dependencies from a task
    • Get dependents from a task
    • Duplicate a task
    • Unlink dependencies from a task
    • Unlink dependents from a task
    • Remove followers from a task
    • Remove a project from a task
    • Remove a tag from a task
    • Set the parent of a task
    • Get subtasks from a task
    • Create a subtask
    • Get tasks from a user task list
    • Search tasks in a workspace
  • Stories
    • Delete a story
      DELETE
    • Get a story
      GET
    • Update a story
      PUT
    • Get stories from a task
      GET
    • Create a story on a task
      POST
  • Tags
    • Get multiple tags
    • Create a tag
    • Delete a tag
    • Get a tag
    • Update a tag
    • Get a task's tags
    • Get tags in a workspace
    • Create a tag in a workspace
  • Team Memberships
    • Get team memberships
    • Get a team membership
    • Get memberships from a team
    • Get memberships from a user
  • Users
    • Get users in a team
    • Get multiple users
    • Get a user
    • Get a user's favorites
    • Get users in a workspace or organization
  • Time Periods
    • Get time periods
    • Get a time period
  • User Task Lists
    • Get a user task list
    • Get a user's task list
  • Workspace Memberships
    • Get workspace memberships for a user
    • Get a workspace membership
    • Get the workspace memberships for a workspace
  • Webhooks
    • Get multiple webhooks
    • Establish a webhook
    • Delete a webhook
    • Get a webhook
  • Workspaces
    • Get multiple workspaces
    • Get a workspace
    • Update a workspace
    • Add a user to a workspace or organization
    • Remove a user from a workspace or organization
  • Typeahead
    • Get objects via typeahead
  1. Stories

Create a story on a task

POST
/tasks/{task_gid}/stories
Stories
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.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://app.asana.com/api/1.0/tasks//stories' \
--header 'Content-Type: application/json' \
--data-raw ''
Response Response Example
201 - Example 1
{
  "data": {
    "gid": "12345",
    "resource_type": "task",
    "created_at": "2012-02-22T02:06:58.147Z",
    "html_text": "<body>This is a comment.<body>",
    "is_pinned": false,
    "resource_subtype": "comment_added",
    "sticker_name": "dancing_unicorn",
    "text": "This is a comment.",
    "assignee": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Greg Sanchez"
    },
    "created_by": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Greg Sanchez"
    },
    "custom_field": {
      "gid": "12345",
      "resource_type": "task",
      "display_value": "blue",
      "enabled": true,
      "enum_options": [
        {
          "gid": "12345",
          "resource_type": "task",
          "color": "blue",
          "enabled": true,
          "name": "Low"
        }
      ],
      "name": "Status",
      "number_value": 5.2,
      "resource_subtype": "text",
      "text_value": "Some Value",
      "type": "text"
    },
    "dependency": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Bug Task"
    },
    "duplicate_of": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Bug Task"
    },
    "duplicated_from": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Bug Task"
    },
    "follower": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Greg Sanchez"
    },
    "hearted": false,
    "hearts": [
      {
        "gid": "12345",
        "user": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Greg Sanchez"
        }
      }
    ],
    "is_edited": false,
    "liked": false,
    "likes": [
      {
        "gid": "12345",
        "user": {
          "gid": "12345",
          "resource_type": "task",
          "name": "Greg Sanchez"
        }
      }
    ],
    "new_approval_status": "approved",
    "new_dates": {
      "due_at": "2019-09-15T02:06:58.158Z",
      "due_on": "2019-09-15",
      "start_on": "2019-09-14"
    },
    "new_enum_value": {
      "gid": "12345",
      "resource_type": "task",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    },
    "new_multi_enum_values": [
      {
        "gid": "12345",
        "resource_type": "task",
        "color": "blue",
        "enabled": true,
        "name": "Low"
      }
    ],
    "new_name": "This is the New Name",
    "new_number_value": 2,
    "new_resource_subtype": "milestone",
    "new_section": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Next Actions"
    },
    "new_text_value": "This is the New Text",
    "num_hearts": 5,
    "num_likes": 5,
    "old_approval_status": "pending",
    "old_dates": {
      "due_at": "2019-09-15T02:06:58.158Z",
      "due_on": "2019-09-15",
      "start_on": "2019-09-14"
    },
    "old_enum_value": {
      "gid": "12345",
      "resource_type": "task",
      "color": "blue",
      "enabled": true,
      "name": "Low"
    },
    "old_multi_enum_values": [
      {
        "gid": "12345",
        "resource_type": "task",
        "color": "blue",
        "enabled": true,
        "name": "Low"
      }
    ],
    "old_name": "This was the Old Name",
    "old_number_value": 1,
    "old_resource_subtype": "default_task",
    "old_section": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Next Actions"
    },
    "old_text_value": "This was the Old Text",
    "previews": [
      {
        "fallback": "Greg: Great! I like this idea.\\n\\nhttps//a_company.slack.com/archives/ABCDEFG/12345678",
        "footer": "Mar 17, 2019 1:25 PM",
        "header": "Asana for Slack",
        "header_link": "https://asana.comn/apps/slack",
        "html_text": "<body>Great! I like this idea.</body>",
        "text": "Great! I like this idea.",
        "title": "Greg",
        "title_link": "https://asana.slack.com/archives/ABCDEFG/12345678"
      }
    ],
    "project": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Stuff to buy"
    },
    "source": "web",
    "story": {
      "gid": "12345",
      "resource_type": "task",
      "created_at": "2012-02-22T02:06:58.147Z",
      "created_by": {
        "gid": "12345",
        "resource_type": "task",
        "name": "Greg Sanchez"
      },
      "resource_subtype": "comment_added",
      "text": "marked today"
    },
    "tag": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Stuff to buy"
    },
    "target": {
      "gid": "1234",
      "name": "Bug Task"
    },
    "task": {
      "gid": "12345",
      "resource_type": "task",
      "name": "Bug Task"
    }
  }
}

Request

Path Params
task_gid
string 
required
Body Params application/json
data
object (StoryBase) 
optional
A story represents an activity associated with an object in the Asana system.
html_text
string 
optional
Opt In. HTML formatted text for a comment. This will not include the name of the creator.
Example:
<body>This is a comment.<body>
is_pinned
boolean 
optional
Conditional. Whether the story should be pinned on the resource.
Example:
false
sticker_name
enum<string> 
optional
The name of the sticker in this story. null if there is no sticker.
Allowed values:
green_checkmarkpeople_dancingdancing_unicornheartparty_popperpeople_waving_flagssplashing_narwhaltrophyyeti_riding_unicorncelebrating_peopledetermined_climbersphoenix_spreading_love
Example:
dancing_unicorn
text
string 
optional
The plain text of the comment to add. Cannot be used with html_text.
Example:
This is a comment.
Examples

Responses

🟢201Successfully created a new story.
application/json
Body
data
object (StoryResponse) 
optional
A story represents an activity associated with an object in the Asana system.
assignee
object 
UserCompact
optional
A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
created_by
object 
UserCompact
optional
A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
custom_field
object 
CustomFieldCompact
optional
Custom Fields store the metadata that is used in order to add user-specified information to tasks in Asana. Be sure to reference the Custom Fields developer documentation for more information about how custom fields relate to various resources in Asana.
Users in Asana can lock custom fields, which will make them read-only when accessed by other users. Attempting to edit a locked custom field will return HTTP error code 403 Forbidden.
dependency
object 
TaskCompact
optional
The task is the basic object around which many operations in Asana are centered.
duplicate_of
object 
TaskCompact
optional
The task is the basic object around which many operations in Asana are centered.
duplicated_from
object 
TaskCompact
optional
The task is the basic object around which many operations in Asana are centered.
follower
object 
UserCompact
optional
A user object represents an account in Asana that can be given access to various workspaces, projects, and tasks.
hearted
boolean 
read-onlyoptional
Deprecated - please use likes instead
Conditional. True if the story is hearted by the authorized user, false if not.
Example:
false
hearts
array[object (Like) {2}] 
read-onlyoptional
Deprecated - please use likes instead
Conditional. Array of likes for users who have hearted this story.
is_edited
boolean 
read-onlyoptional
Conditional. Whether the text of the story has been edited after creation.
Example:
false
liked
boolean 
read-onlyoptional
Conditional. True if the story is liked by the authorized user, false if not.
Example:
false
likes
array[object (Like) {2}] 
read-onlyoptional
Conditional. Array of likes for users who have liked this story.
new_approval_status
string 
read-onlyoptional
Conditional
Example:
approved
new_dates
object 
StoryResponseDates
read-onlyoptional
Conditional
new_enum_value
object 
EnumOption
optional
Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 50.
You can add enum options to a custom field by using the POST /custom_fields/custom_field_gid/enum_options endpoint.
It is not possible to remove or delete an enum option. Instead, enum options can be disabled by updating the enabled field to false with the PUT /enum_options/enum_option_gid endpoint. Other attributes can be updated similarly.
On creation of an enum option, enabled is always set to true, meaning the enum option is a selectable value for the custom field. Setting enabled=false is equivalent to “trashing” the enum option in the Asana web app within the “Edit Fields” dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.
Enum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using insert_before or insert_after to reference an existing enum option. Only one of insert_before and insert_after can be provided when creating a new enum option.
An enum options list can be reordered with the POST /custom_fields/custom_field_gid/enum_options/insert endpoint.
new_multi_enum_values
array[object (EnumOption) {5}] 
read-onlyoptional
Conditional
new_name
string 
read-onlyoptional
Conditional
Example:
This is the New Name
new_number_value
integer 
read-onlyoptional
Conditional
Example:
2
new_resource_subtype
string 
read-onlyoptional
Conditional
Example:
milestone
new_section
object 
SectionCompact
optional
A section is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.
new_text_value
string 
read-onlyoptional
Conditional
Example:
This is the New Text
num_hearts
integer 
read-onlyoptional
Deprecated - please use likes instead
Conditional. The number of users who have hearted this story.
Example:
5
num_likes
integer 
read-onlyoptional
Conditional. The number of users who have liked this story.
Example:
5
old_approval_status
string 
read-onlyoptional
Conditional
Example:
pending
old_dates
object 
StoryResponseDates
read-onlyoptional
Conditional
old_enum_value
object 
EnumOption
optional
Enum options are the possible values which an enum custom field can adopt. An enum custom field must contain at least 1 enum option but no more than 50.
You can add enum options to a custom field by using the POST /custom_fields/custom_field_gid/enum_options endpoint.
It is not possible to remove or delete an enum option. Instead, enum options can be disabled by updating the enabled field to false with the PUT /enum_options/enum_option_gid endpoint. Other attributes can be updated similarly.
On creation of an enum option, enabled is always set to true, meaning the enum option is a selectable value for the custom field. Setting enabled=false is equivalent to “trashing” the enum option in the Asana web app within the “Edit Fields” dialog. The enum option will no longer be selectable but, if the enum option value was previously set within a task, the task will retain the value.
Enum options are an ordered list and by default new enum options are inserted at the end. Ordering in relation to existing enum options can be specified on creation by using insert_before or insert_after to reference an existing enum option. Only one of insert_before and insert_after can be provided when creating a new enum option.
An enum options list can be reordered with the POST /custom_fields/custom_field_gid/enum_options/insert endpoint.
old_multi_enum_values
array[object (EnumOption) {5}] 
read-onlyoptional
Conditional
old_name
string 
optional
Conditional'
Example:
This was the Old Name
old_number_value
integer 
read-onlyoptional
Conditional
Example:
1
old_resource_subtype
string 
read-onlyoptional
Conditional
Example:
default_task
old_section
object 
SectionCompact
optional
A section is a subdivision of a project that groups tasks together. It can either be a header above a list of tasks in a list view or a column in a board view of a project.
old_text_value
string 
read-onlyoptional
Conditional
Example:
This was the Old Text
previews
array[object (Preview) {8}] 
read-onlyoptional
Conditional. A collection of previews to be displayed in the story.
Note: This property only exists for comment stories.
project
object 
ProjectCompact
optional
A project represents a prioritized list of tasks in Asana or a board with columns of tasks represented as cards. It exists in a single workspace or organization and is accessible to a subset of users in that workspace or organization, depending on its permissions.
source
enum<string> 
read-onlyoptional
The component of the Asana product the user used to trigger the story.
Allowed values:
webemailmobileapiunknown
Example:
web
story
object 
StoryCompact
optional
A story represents an activity associated with an object in the Asana system.
tag
object 
TagCompact
optional
A tag is a label that can be attached to any task in Asana. It exists in a single workspace or organization.
target
object 
read-onlyoptional
The object this story is associated with. Currently may only be a task.
task
object 
TaskCompact
optional
The task is the basic object around which many operations in Asana are centered.
gid
string 
read-onlyoptional
Globally unique identifier of the resource, as a string.
Example:
12345
resource_type
string 
read-onlyoptional
The base type of this resource.
Example:
task
created_at
string <date-time>
read-onlyoptional
The time at which this resource was created.
Example:
2012-02-22T02:06:58.147Z
html_text
string 
optional
Opt In. HTML formatted text for a comment. This will not include the name of the creator.
Example:
<body>This is a comment.<body>
is_pinned
boolean 
optional
Conditional. Whether the story should be pinned on the resource.
Example:
false
resource_subtype
string 
read-onlyoptional
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.
Example:
comment_added
sticker_name
enum<string> 
optional
The name of the sticker in this story. null if there is no sticker.
Allowed values:
green_checkmarkpeople_dancingdancing_unicornheartparty_popperpeople_waving_flagssplashing_narwhaltrophyyeti_riding_unicorncelebrating_peopledetermined_climbersphoenix_spreading_love
Example:
dancing_unicorn
text
string 
optional
The plain text of the comment to add. Cannot be used with html_text.
Example:
This is a comment.
🟠400400
🟠401401
🟠403403
🟠404404
🔴500500
Modified at 2022-09-13 02:00:32
Previous
Get stories from a task
Next
Get multiple tags
Built with