Stories

A story represents an activity associated with an object in the Asana system. Stories are generated by the system whenever users take actions such as creating or assigning tasks, or moving tasks between projects. Comments are also a form of user-generated story.

Stories have the following fields:
Field Description
id 1234 Read-only. Globally unique ID of the story. Note: This field is under active migration to the gid field—please see our blog post for more information.
gid "1234" Read-only. Globally unique ID of the story.
resource_type "story" Read-only. The resource type of this resource. The value for this resource is always story.
resource_subtype "comment_added" "description_changed" "liked" ... Read-only. The type of story. This provides fine-grained information about what triggered the story’s creation. There are many story subtypes, so inspect the data returned from Asana’s API to find the value for your use case.
created_at '2012-02-22T02:06:58.147Z' The time at which this story was created.
created_by { id: 12345, gid: "12345", name: 'Tim Bizarro' } null The user who created the story.
liked false True if the story is liked by the authorized user, false if not.

Note: This property only exists for stories that provide likes.
likes [ { id: 1123, gid: "1123", name: 'Mittens' }, ... ] Read-only. Array of users who have liked this story.

Note: This property only exists for stories that provide likes.
num_likes 5 Read-only. The number of users who have liked this story.

Note: This property only exists for stories that provide likes.
text 'marked today' 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.
html_text '<body>Get whatever <a href='https://app.asana.com/0/1123/list'>Sashimi</a> has.</body>' HTML formatted text for a comment.

Note: This field is under active migration—please see our blog post for more information.
target { id: 1234, name: 'Bug task' } Read-only. The object this story is associated with. Currently may only be a task.
is_pinned false Whether the story is pinned on the target.

Note: This field is only present on comment and attachment stories.
is_edited false Whether the text of the story has been edited after creation.

Note: This field is only present on comment stories.
source 'web' Read-only. The component of the Asana product the user used to create the story.
type 'comment' 'system' Read-only. Deprecated: new integrations should prefer the resource_subtype field. The type of this story. For more fine-grained inspection of story types, see the resource_subtype property.

GET STORIES ON OBJECT

GET    /tasks/{task_gid}/stories

Returns the compact records for all stories on the task.

Parameter Description
task_gid "124816" Required: Globally unique identifier for the task.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/stories

# Response
HTTP/1.1 200
{
  "data": [
    {
      "id": 2001,
      "gid": "2001",
      "resource_type": "story",
      "resource_subtype": "added_to_project",
      "text": "added to Things To Buy",
      "created_at": "2011-12-21T23:23:01.259Z",
      "type": "system",
      "created_by": {
        "id": 5678,
        "gid": "5678",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    },
    {
      "id": 2002,
      "gid": "2002",
      "resource_type": "story",
      "resource_subtype": "comment_added",
      "text": "Again? Wow, we really go through this stuff fast.",
      "created_at": "2012-01-02T21:32:40.112Z",
      "type": "comment",
      "created_by": {
        "id": 1234,
        "gid": "1234",
        "resource_type": "user",
        "name": "Tim Bizarro"
      }
    }
  ]
}

GET A SINGLE STORY

GET    /stories/{story_gid}

Returns the full record for a single story.

Parameter Description
story_gid "182764" Required: Globally unique identifier for the story.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/stories/2001

# Response
HTTP/1.1 200
{
  "data": {
    "id": 2001,
    "gid": "2001"
    "resource_type": "story",
    "resource_subtype": "comment_added",
    "target": {
      "id": 1234,
      "gid": "1234",
      "resource_type": "task",
      "name": "Buy catnip"
    },
    "text": "Yes, please!",
    "created_at": "2012-02-22T02:06:58.147Z",
    "created_by": {
      "id": 1123,
      "gid": "1123",
      "resource_type": "user",
      "name": "Mittens"
    },
    "source": "web",
    "type": "comment",
    "is_edited": false,
    "is_pinned": false
  }
}

COMMENTING ON AN OBJECT

POST    /tasks/{task_gid}/stories

Adds a comment to a task. 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.

Parameter Description
task_gid 124816 Required: Globally unique identifier for the task.
text 'This is a comment.' Required: The plain text of the comment to add.
# Request
curl -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/tasks/1001/stories \
--data-urlencode "text=This is a very nice comment."

# Response
HTTP/1.1 200
{
  "data": {
    "id": 2001,
    "gid": "2001"
    "resource_type": "story",
    "resource_subtype": "comment_added",
    "target": {
      "id": 1001,
      "gid": "1001",
      "resource_type": "task",
      "name": "Buy catnip"
    },
    "text": "This is a very nice comment.",
    "created_at": "2011-12-21T23:23:01.259Z",
    "created_by": {
      "id": 5678,
      "gid": "5678",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    "source": "api",
    "type": "comment",
    "is_edited": false,
    "is_pinned": false
  }
}

UPDATE A STORY

PUT    /stories/{story_gid}

Updates the story and returns the full record for the updated story. Only comment stories can have their text updated, and only comment stories and attachment stories can be pinned. Only one of text and html_text can be specified.

Parameter Description
story_gid "182764" Required: Globally unique identifier for the story.
text 'This is a comment.' The plain text with which to update the comment.
html_text 'Get whatever <a href='https://app.asana.com/0/1123/1234'>Sashimi</a> has.' The rich text with which to update the comment.
is_pinned false Whether the story should be pinned on the resource.
# Request
curl --request PUT -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/stories/2001 \
--data-urlencode "text=This is some updated text."

# Response
HTTP/1.1 200
{
  "data": {
    "id": 2001,
    "gid": "2001"
    "resource_type": "story",
    "target": {
      "id": 1001,
      "gid": "1001",
      "resource_type": "task",
      "name": "Buy catnip"
    },
    "text": "This is some updated text.",
    "created_at": "2011-12-21T23:23:01.259Z",
    "created_by": {
      "id": 5678,
      "gid": "5678",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    "source": "api",
    "type": "comment",
    "is_edited": true,
    "is_pinned": false,
  }
}

DELETE A STORY

DELETE    /stories/{story_gid}

Deletes a story. A user can only delete stories they have created. Returns an empty data record.

Parameter Description
story_gid "182764" Required: Globally unique identifier for the story.
# Request
curl --request DELETE -H "Authorization: Bearer <personal_access_token>" \
https://app.asana.com/api/1.0/stories/2001

# Response
HTTP/1.1 200
{
  "data": {}
}