Mavenlink

Story State Changes

Story State Changes in Mavenlink act as an audit trail for changes to the state of a Story.

Story State Change objects have four readable attributes. They are:

  • id the unique identifier for this story state change object
  • created_at the date the story state change was recorded in Mavenlink
  • state the new state of the story (started, not started, or completed)
  • formatted_state the formatted version of the new state of the story (Started, Not Started, or Completed)

Fetching Story State Changes

The story state changes endpoint provides a list of state changes for a given story. story_id is a required parameter to retrieve story state changes for a given story.

As with all API listing actions, you can provide per_page and page to paginate your response. You may also limit the response to one story state change using the only parameter.

To list all story state changes' of a Story#10 using curl, run:

curl "https://api.mavenlink.com/api/v1/story_state_changes.json?story_id=10"

Associated Objects

You can include story state changes' associations with the include param. For example, to include the story and user for StoryStateChange#5, you would do the following:

curl "https://api.mavenlink.com/api/v1/story_state_changes/5.json?include=story,user"

In this example, our API will ensure that the returned JSON contains top-level keys called stories and users, where you can find associated data by inspecting the StoryStateChange's story_id and user_id. See Object Associations to learn more. The following associations can be requested through the API:

  • story - when included, the story_id will reference the story for which the story state change belongs
  • user - when included, the user_id will reference the user for which the story state change belongs

Ordering Story State Changes

Valid orders are:

  • created_at

The default order is created_at:asc.

Getting a Single Story State Change

As with all resources, you can request either GET /api/v1/story_state_changes.json?only=5 or GET /api/v1/story_state_changes/5.json.

Creating New Story State Changes for a Story

You cannot create a story state change directly. They will be created for you automatically when you set the state of a Story.

Updating Story State Changes

You cannot update a story state change.

Destroying Story State Changes

You cannot destroy a story state change.