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.
hearted false True if the story is hearted by the authorized user, false if not.

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

Note: This property only exists for stories that provide hearts.
num_hearts 5 Read-only. The number of users who have hearted this story.

Note: This property only exists for stories that provide hearts.
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 Sashimi 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.
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",
    "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",
    "id": 2001
  }
}