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 are a form of history in the system, and as such they are read-only. Once generated, it is not possible to modify a story.

Stories have the following fields:
Field Description
id 1234 Read-only. Globally unique ID of the story.
created_at '2012-02-22T02:06:58.147Z' The time at which this story was created.
created_by { id: 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, 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 …”. The API currently does not provide a structured way of inspecting the meaning of a story.
html_text 'Get whatever <a href='https://app.asana.com/0/1123/1234'>Sashimi</a> has.' Read-only. HTML formatted text for a comment. This will not include the name of the creator.

Note: This field is only returned if explicitly requested using the opt_fields query parameter.
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 trigger the story.
type 'comment' Read-only. The type of story this is.

GET STORIES ON OBJECT

GET    /tasks/task-id/stories

Returns the compact records for all stories on the task.

Parameter Description
task 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": [
    {
      "text": "added to Things To Buy",
      "created_at": "2011-12-21T23:23:01.259Z",
      "type": "system",
      "id": 2001,
      "created_by": {
        "id": 5678,
        "name": "Greg Sanchez"
      }
    },
    {
      "text": "Again? Wow, we really go through this stuff fast.",
      "created_at": "2012-01-02T21:32:40.112Z",
      "type": "comment",
      "id": 2002,
      "created_by": {
        "id": 1234,
        "name": "Tim Bizarro"
      }
    }
  ]
}

GET A SINGLE STORY

GET    /stories/story-id

Returns the full record for a single story.

Parameter Description
story 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": {
    "target": {
      "id": 1234,
      "name": "Buy catnip"
    },
    "text": "Yes, please!",
    "created_at": "2012-02-22T02:06:58.147Z",
    "created_by": {
      "id": 1123,
      "name": "Mittens"
    },
    "source": "web",
    "type": "comment",
    "is_edited": false,
    "is_pinned": false,
    "id": 2001
  }
}

COMMENTING ON AN OBJECT

POST    /tasks/task-id/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 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": {
    "target": {
      "id": 1001,
      "name": "Buy catnip"
    },
    "text": "This is a very nice comment.",
    "created_at": "2011-12-21T23:23:01.259Z",
    "created_by": {
      "id": 5678,
      "name": "Greg Sanchez"
    },
    "source": "api",
    "type": "comment",
    "is_edited": false,
    "is_pinned": false,
    "id": 2001
  }
}

UPDATE A STORY

PUT    /stories/story-id

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 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": {
    "target": {
      "id": 1001,
      "name": "Buy catnip"
    },
    "text": "This is some updated text.",
    "created_at": "2011-12-21T23:23:01.259Z",
    "created_by": {
      "id": 5678,
      "name": "Greg Sanchez"
    },
    "source": "api",
    "type": "comment",
    "is_edited": true,
    "is_pinned": false,
    "id": 2001
  }
}